Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
billing

Create a payment setup session for a customer to add or update their payment method.

post/v1/billing.setup_payment

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer to attach the plan to.

entity_idstring

The ID of the entity to attach the plan to.

plan_idstring

If specified, the plan will be attached to the customer after setup.

versionnumber

The version of the plan to attach.

proration_behavior'prorate_immediately' | 'none'

How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.

subscription_idstring

A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.

success_urlstring

URL to redirect to after successful checkout.

billing_cycle_anchor'now'

Reset the billing cycle anchor immediately with 'now'.

starts_atinteger

Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription.

ends_atinteger

Unix timestamp in milliseconds for when the attached plan should end.

checkout_session_paramsobject

Additional parameters to pass into the creation of the Stripe checkout session.

processor_subscription_idstring

The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.

metadataobject

Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn_' are reserved and will be stripped.

no_billing_changesboolean

If true, skips any billing changes for the attach operation.

enable_plan_immediatelyboolean

If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer_product is inserted before the customer completes the hosted form.

tax_rate_idstring

Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items.

currencystring

Currency to bill this attach in (e.g. usd, eur). Must match the customer's currency if they are already locked to one, and the plan must offer a paid price in it. Defaults to the customer's currency, then the org default.

Example request

{
  "customer_id": "cus_123",
  "success_url": "https://example.com/account/billing"
}

Response

OK

customer_idstring required

The ID of the customer

entity_idstring

The ID of the entity the plan (if specified) will be attached to after setup.

urlstring required

URL to redirect the customer to setup their payment.

Example response

{
  "customer_id": "cus_123",
  "url": "https://checkout.stripe.com/..."
}