Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
billing

Previews the billing changes that would occur when attaching multiple plans, without actually making any changes.

Use this endpoint to show customers what they will be charged before confirming a multi-plan subscription.

post/v1/billing.preview_multi_attach

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer to attach the plans to.

entity_idstring

The ID of the entity to attach the plans to.

currencystring

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

success_urlstring

URL to redirect to after successful checkout.

checkout_session_paramsobject

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

redirect_mode'always' | 'if_required' | 'never'

Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects.

new_billing_subscriptionboolean

Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.

enable_plan_immediatelyboolean

If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout.

Example request

{
  "customer_id": "cus_123",
  "plans": [
    {
      "plan_id": "pro_plan"
    },
    {
      "plan_id": "addon_seats",
      "feature_quantities": [
        {
          "feature_id": "seats",
          "quantity": 5
        }
      ]
    }
  ]
}

Response

OK

customer_idstring required

The ID of the customer.

subtotalnumber required

The total amount in cents before discounts and tax for the current billing period.

totalnumber required

The final amount in cents after discounts and tax for the current billing period.

currencystring required

The three-letter ISO currency code (e.g., 'usd').

expandstring[]

Expand the response with additional data.

redirect_to_checkoutboolean required

Whether the customer will be redirected to a checkout page if attach is called.

checkout_type'stripe_checkout' | 'autumn_checkout' nullable required

The type of checkout that will be used if the customer is redirected to a checkout page.

Example response

{
  "customerId": "charles",
  "lineItems": [
    {
      "display_name": "Pro seed",
      "description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
      "subtotal": 20,
      "total": 20,
      "discounts": []
    }
  ],
  "subtotal": 20,
  "total": 20,
  "currency": "usd"
}