Stripe.Billing reference

Alert

Source: src/Stripe/Alert.ts

A Stripe Billing Alert — notifies you when a usage threshold on a Billing Meter is crossed. title, alertType, and usageThreshold are immutable; changing them replaces the alert. status is changed with Stripe’s activate/deactivate endpoints.

Billing alerts have no metadata field and cannot be hard-deleted. Destroying this resource archives the alert (irreversible). Archived alerts leave the list API and cannot be reactivated.

Alert: Creating an Alert

Usage threshold on a meter

const apiCalls = yield* Stripe.BillingMeter("api-calls", {
  displayName: "API Calls",
  eventName: "api_call",
  defaultAggregation: { formula: "sum" },
});
const highUsage = yield* Stripe.Alert("high-usage", {
  title: "API Request usage alert",
  usageThreshold: {
    gte: 10000,
    meter: apiCalls.id,
    recurrence: "one_time",
  },
});

Limit the alert to one customer

const highUsage = yield* Stripe.Alert("high-usage", {
  title: "Customer API usage alert",
  usageThreshold: {
    gte: 1000,
    meter: apiCalls.id,
    recurrence: "one_time",
    filters: [{ type: "customer", customer: customer.id }],
  },
});

Alert: Updating an Alert

const highUsage = yield* Stripe.Alert("high-usage", {
  title: "API Request usage alert",
  usageThreshold: {
    gte: 10000,
    meter: apiCalls.id,
    recurrence: "one_time",
  },
  status: "inactive",
});

Alert: Archiving an Alert

// stack.destroy() / resource removal archives the alert
const highUsage = yield* Stripe.Alert("high-usage", {
  title: "API Request usage alert",
  usageThreshold: {
    gte: 10000,
    meter: apiCalls.id,
    recurrence: "one_time",
  },
});

BillingMeter

Source: src/Stripe/BillingMeter.ts

A Stripe Billing Meter — how usage events are aggregated over a billing period for usage-based prices. eventName, defaultAggregation, customerMapping, eventTimeWindow, and valueSettings are immutable. Changing eventName replaces the meter. Display name updates in place; status is changed with Stripe’s activate/deactivate endpoints.

Billing meters have no metadata field and cannot be hard-deleted. Destroying this resource deactivates the meter. Deactivated meters still occupy their eventName, so a later deploy with the same event name reactivates the existing meter.

BillingMeter: Creating a Billing Meter

Sum aggregation

const apiCalls = yield* Stripe.BillingMeter("api-calls", {
  displayName: "API Calls",
  eventName: "api_call",
  defaultAggregation: { formula: "sum" },
});

Count with custom value key

const tokens = yield* Stripe.BillingMeter("tokens", {
  displayName: "Tokens",
  eventName: "token_used",
  defaultAggregation: { formula: "count" },
  valueSettings: { eventPayloadKey: "tokens" },
  customerMapping: {
    type: "by_id",
    eventPayloadKey: "stripe_customer_id",
  },
});

BillingMeter: Updating a Billing Meter

const apiCalls = yield* Stripe.BillingMeter("api-calls", {
  displayName: "API Calls (updated)",
  eventName: "api_call",
  defaultAggregation: { formula: "sum" },
});

BillingMeter: Deactivating a Billing Meter

// stack.destroy() / resource removal calls deactivate
const apiCalls = yield* Stripe.BillingMeter("api-calls", {
  displayName: "API Calls",
  eventName: "api_call",
  defaultAggregation: { formula: "sum" },
});

BillingPortalConfiguration

Source: src/Stripe/BillingPortalConfiguration.ts

A Stripe Customer Portal configuration — the features, branding, and return URL used when creating portal sessions. features is required on create. Name, metadata, business profile, login page, return URL, features, and active update in place. Stripe does not hard-delete portal configurations; destroying this resource deactivates it (active: false).

BillingPortalConfiguration: Creating a Configuration

Invoice history only

const portal = yield* Stripe.BillingPortalConfiguration("customer-portal", {
  name: "Customer portal",
  features: {
    invoiceHistory: { enabled: true },
  },
});

Customer updates and payment methods

const portal = yield* Stripe.BillingPortalConfiguration("customer-portal", {
  name: "Customer portal",
  defaultReturnUrl: "https://example.com/account",
  features: {
    invoiceHistory: { enabled: true },
    customerUpdate: {
      enabled: true,
      allowedUpdates: ["email", "address"],
    },
    paymentMethodUpdate: { enabled: true },
  },
  metadata: { env: "prod" },
});

BillingPortalConfiguration: Updating a Configuration

const portal = yield* Stripe.BillingPortalConfiguration("customer-portal", {
  name: "Customer portal (updated)",
  features: {
    invoiceHistory: { enabled: true },
    subscriptionCancel: { enabled: true, mode: "at_period_end" },
  },
  metadata: { env: "prod", revision: "2" },
});

BillingPortalConfiguration: Deactivating a Configuration

// stack.destroy() / resource removal sets active: false
const portal = yield* Stripe.BillingPortalConfiguration("customer-portal", {
  features: { invoiceHistory: { enabled: true } },
});

CreateBillingPortalSession

Source: src/Stripe/CreateBillingPortalSession.ts

Create a Stripe Billing Portal Session over HTTP. The portal is Stripe’s hosted page where a customer updates their card, switches plans, downloads invoices, or cancels — so your app never has to build those screens. Create the session for the customer and redirect them to session.url.

Account-scoped — binds the API key onto the host, not a specific resource.

CreateBillingPortalSession: Letting a customer manage their subscription

const createPortal = yield* Stripe.CreateBillingPortalSession();

// inside a Worker route
const session = yield* createPortal({
  customer: customerId,
  return_url: `${origin}/account`,
});
// redirect to session.url

CreateBillingPortalSessionHttp

Source: src/Stripe/CreateBillingPortalSessionHttp.ts Kind: Layer · Provides: Stripe.CreateBillingPortalSession

HTTP implementation of CreateBillingPortalSession. Provide it on the Function or Worker Effect.

CreateCreditGrant

Source: src/Stripe/CreateCreditGrant.ts

Create a Stripe Credit Grant over HTTP. Account-scoped — binds the API key onto the host, not a specific grant resource.

CreateCreditGrant: Creating a Credit Grant at runtime

const create = yield* Stripe.CreateCreditGrant();
const grant = yield* create({
  customer: "cus_123",
  amount: { type: "monetary", monetary: { currency: "usd", value: 1000 } },
  applicability_config: { scope: { price_type: "metered" } },
  category: "promotional",
  name: "Welcome credits",
});

CreateCreditGrantHttp

Source: src/Stripe/CreateCreditGrantHttp.ts Kind: Layer · Provides: Stripe.CreateCreditGrant

HTTP implementation of CreateCreditGrant. Provide it on the Function or Worker Effect.

CreditGrant

Source: src/Stripe/CreditGrant.ts

A Stripe Credit Grant — prepaid or promotional billing credits allocated to a customer and applied against metered prices. Amount, customer, applicability, category, effective time, and priority are immutable; changing them replaces the grant. expiresAt and metadata update in place. Credit grants cannot be hard-deleted: destroying this resource voids the grant (voided_at is set). Already-voided grants are treated as success.

CreditGrant: Creating a Credit Grant

Promotional credits for metered prices

const customer = yield* Stripe.Customer("alice", {
  email: "alice@example.com",
});
const grant = yield* Stripe.CreditGrant("welcome-credits", {
  customer: customer.id,
  amount: { type: "monetary", monetary: { currency: "usd", value: 1000 } },
  applicabilityConfig: { scope: { priceType: "metered" } },
  category: "promotional",
  name: "Welcome credits",
});

Paid credits scoped to specific prices

const grant = yield* Stripe.CreditGrant("prepaid", {
  customer: customer.id,
  amount: { type: "monetary", monetary: { currency: "usd", value: 5000 } },
  applicabilityConfig: {
    scope: { prices: [{ id: price.id }] },
  },
  category: "paid",
});

CreditGrant: Updating a Credit Grant

const grant = yield* Stripe.CreditGrant("welcome-credits", {
  customer: customer.id,
  amount: { type: "monetary", monetary: { currency: "usd", value: 1000 } },
  expiresAt: 4102444800,
  metadata: { campaign: "spring" },
});

CreditGrant: Voiding a Credit Grant

// stack.destroy() / resource removal calls void
const grant = yield* Stripe.CreditGrant("welcome-credits", {
  customer: customer.id,
  amount: { type: "monetary", monetary: { currency: "usd", value: 1000 } },
});

RetrieveAlert

Source: src/Stripe/RetrieveAlert.ts

Retrieve a bound Stripe Billing Alert over HTTP.

RetrieveAlert: Reading an Alert

const retrieve = yield* Stripe.RetrieveAlert(highUsage);
const live = yield* retrieve();

RetrieveAlertHttp

Source: src/Stripe/RetrieveAlertHttp.ts Kind: Layer · Provides: Stripe.RetrieveAlert

HTTP implementation of RetrieveAlert.

RetrieveBillingMeter

Source: src/Stripe/RetrieveBillingMeter.ts

Retrieve a bound Stripe Billing Meter over HTTP.

RetrieveBillingMeter: Reading a Billing Meter

const retrieve = yield* Stripe.RetrieveBillingMeter(usage);
const live = yield* retrieve();

RetrieveBillingMeterHttp

Source: src/Stripe/RetrieveBillingMeterHttp.ts Kind: Layer · Provides: Stripe.RetrieveBillingMeter

HTTP implementation of RetrieveBillingMeter.

RetrieveBillingPortalConfiguration

Source: src/Stripe/RetrieveBillingPortalConfiguration.ts

Retrieve a bound Stripe Billing Portal Configuration over HTTP.

RetrieveBillingPortalConfiguration: Reading a Portal Configuration

const retrieve = yield* Stripe.RetrieveBillingPortalConfiguration(portal);
const live = yield* retrieve();

RetrieveBillingPortalConfigurationHttp

Source: src/Stripe/RetrieveBillingPortalConfigurationHttp.ts Kind: Layer · Provides: Stripe.RetrieveBillingPortalConfiguration

HTTP implementation of RetrieveBillingPortalConfiguration.

RetrieveCreditGrant

Source: src/Stripe/RetrieveCreditGrant.ts

Retrieve a bound Stripe Credit Grant over HTTP.

RetrieveCreditGrant: Reading a Credit Grant

const retrieve = yield* Stripe.RetrieveCreditGrant(grant);
const live = yield* retrieve();

RetrieveCreditGrantHttp

Source: src/Stripe/RetrieveCreditGrantHttp.ts Kind: Layer · Provides: Stripe.RetrieveCreditGrant

HTTP implementation of RetrieveCreditGrant. Provide it on the Function or Worker Effect.

UpdateCreditGrant

Source: src/Stripe/UpdateCreditGrant.ts

Update a bound Stripe Credit Grant over HTTP. Mutable fields are expires_at and metadata.

UpdateCreditGrant: Updating a Credit Grant

const update = yield* Stripe.UpdateCreditGrant(grant);
const live = yield* update({ expires_at: 4102444800 });

UpdateCreditGrantHttp

Source: src/Stripe/UpdateCreditGrantHttp.ts Kind: Layer · Provides: Stripe.UpdateCreditGrant

HTTP implementation of UpdateCreditGrant. Provide it on the Function or Worker Effect.