Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
billing

Attaches multiple plans to a customer in a single request. Creates a single Stripe subscription with all plans consolidated.

Use this endpoint when you need to subscribe a customer to multiple plans at once, such as a base plan plus add-ons, or to create a bundle of products.

post/v1/billing.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.

entity_idstring

The ID of the entity, if the plan was attached to an entity.

payment_urlstring nullable required

URL to redirect the customer to complete payment. Null if no payment action is required.

Example response

{
  "customer_id": "cus_123",
  "invoice": {
    "status": "paid",
    "stripe_id": "in_1234",
    "total": 4900,
    "currency": "usd",
    "hosted_invoice_url": "https://invoice.stripe.com/..."
  },
  "payment_url": null
}