---
title: "POST /v1/billing.multi_attach"
method: POST
path: "/v1/billing.multi_attach"
tags: ["billing"]
---

# POST /v1/billing.multi_attach

`POST /v1/billing.multi_attach`

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.

## Headers

- `x-api-version` string, required

## Request body

- object
  - `customer_id` string, required — The ID of the customer to attach the plans to.
  - `entity_id` string — The ID of the entity to attach the plans to.
  - `plans` object[], required — The list of plans to attach to the customer.
    - `plan_id` string, required — The ID of the plan to attach.
    - `customize` object — Customize the plan to attach. Can override the price, items, or licenses.
      - `price` object, nullable — Base price configuration for a plan.
        - `amount` number, required — Base price amount for the plan.
        - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval (e.g. 'month', 'year').
        - `interval_count` number — Number of intervals per billing cycle. Defaults to 1.
        - `additional_currencies` object[] — Base price amounts in additional currencies. The base 'amount' is in the org's default currency.
          - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
          - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount.
      - `items` object[] — Override the items in the plan.
        - `feature_id` string, required — The ID of the feature to configure.
        - `included` number — Number of free units included. Balance resets to this each interval for consumable features.
        - `unlimited` boolean — If true, customer has unlimited access to this feature.
        - `reset` object — Reset configuration for consumable features. Omit for non-consumable features like seats.
          - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
          - `interval_count` number — Number of intervals between resets. Defaults to 1.
        - `price` object — Pricing for usage beyond included units. Omit for free features.
          - `amount` number — Price per billing_units after included usage. Either 'amount' or 'tiers' is required.
          - `additional_currencies` object[] — Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.
            - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
            - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount.
          - `tiers` object[] — Tiered pricing. Either 'amount' or 'tiers' is required.
            - `to` union, required
              - …
            - `amount` number
            - `flat_amount` number
            - `additional_currencies` object[] — Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
              - …
          - `tier_behavior` 'graduated' | 'volume'
          - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval. For consumable features, should match reset.interval.
          - `interval_count` number — Number of intervals per billing cycle. Defaults to 1.
          - `billing_units` number — Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
          - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
          - `max_purchase` number, nullable — Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
        - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing.
          - `on_increase` 'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle', required — Billing behavior when quantity increases mid-cycle.
          - `on_decrease` 'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations', required — Credit behavior when quantity decreases mid-cycle.
        - `rollover` object — Rollover config for unused units. If set, unused included units carry over.
          - `max` number — Max rollover units. Omit for unlimited rollover.
          - `max_percentage` number — Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
          - `expiry_duration_type` 'month' | 'forever', required — When rolled over units expire.
          - `expiry_duration_length` number — Number of periods before expiry.
    - `feature_quantities` object[] — If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature.
      - `feature_id` string, required — The ID of the feature to set quantity for.
      - `quantity` number — The quantity of the feature.
      - `adjustable` boolean — Whether the customer can adjust the quantity.
    - `version` number — The version of the plan to attach.
    - `subscription_id` string — A unique ID to identify this subscription. Useful when attaching the same plan multiple times.
  - `free_trial` object, nullable — Free trial configuration for a plan.
    - `duration_length` number, required — Number of duration_type periods the trial lasts.
    - `duration_type` 'day' | 'month' | 'year' — Unit of time for the trial ('day', 'month', 'year').
    - `card_required` boolean — If true, payment method required to start trial. Customer is charged after trial ends.
    - `on_end` 'bill' | 'revert' — Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
  - `currency` string — 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.
  - `invoice_mode` object — Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately.
    - `enabled` boolean, required — When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
    - `enable_plan_immediately` boolean — If true, enables the plan immediately even though the invoice is not paid yet.
    - `finalize` boolean — If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
    - `invoice_template_id` string — ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
    - `net_terms_days` integer — Number of days the customer has to pay the invoice before it is due (Stripe days_until_due).
  - `discounts` object[] — List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
    - `reward_id` string — The ID of the reward to apply as a discount.
    - `promotion_code` string — The promotion code to apply as a discount.
  - `success_url` string — URL to redirect to after successful checkout.
  - `checkout_session_params` object — 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_subscription` boolean — 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_immediately` boolean — If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout.
  - `customer_data` CustomerData — Customer details to set when creating a customer
    - `name` string, nullable — Customer's name
    - `email` string, email, nullable — Customer's email address
    - `fingerprint` string, nullable — Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
    - `metadata` object, nullable — Additional metadata for the customer
    - `stripe_id` string, nullable — Stripe customer ID if you already have one
    - `create_in_stripe` boolean — Whether to create the customer in Stripe
    - `auto_enable_plan_id` string — The ID of the free plan to auto-enable for the customer
    - `send_email_receipts` boolean — Whether to send email receipts to this customer
    - `currency` string, nullable — Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.
    - `billing_controls` object — Billing controls for the customer (auto top-ups, etc.)
      - `auto_topups` object[] — List of auto top-up configurations per feature.
        - `feature_id` string, required — The ID of the feature (credit balance) to auto top-up.
        - `enabled` boolean — Whether auto top-up is enabled.
        - `threshold` number, required — When the balance drops below this threshold, an auto top-up will be purchased.
        - `quantity` number, required — Amount of credits to add per auto top-up.
        - `purchase_limit` object — Optional rate limit to cap how often auto top-ups occur. Pass count to set the current window's consumed top-ups.
          - `interval` 'hour' | 'day' | 'week' | 'month', required — The time interval for the purchase limit window.
          - `interval_count` number — Number of intervals in the purchase limit window.
          - `limit` number, required — Maximum number of auto top-ups allowed within the interval.
          - `count` number — Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.
        - `invoice_mode` boolean — When true, auto top-up creates a send_invoice invoice instead of auto-charging.
      - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend).
        - `feature_id` string — Optional feature ID this spend limit applies to.
        - `enabled` boolean — Whether the overage spend limit is enabled.
        - `limit_type` 'absolute' | 'usage_percentage' — How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
        - `overage_limit` number — Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
        - `skip_overage_billing` boolean — When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
      - `usage_limits` object[] — List of hard usage caps per feature (max units per interval).
        - `feature_id` string, required — The feature this usage limit applies to.
        - `enabled` boolean — Whether this usage limit is enabled.
        - `limit` number, required — Maximum units allowed per interval.
        - `interval` 'day' | 'week' | 'month' | 'year', required — Interval for the cap, aligned to the customer's billing cycle.
        - `filter` object — When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
          - `properties` object, required
      - `usage_alerts` object[] — List of usage alert configurations per feature.
        - `feature_id` string — The feature ID this alert applies to.
        - `enabled` boolean — Whether this usage alert is enabled.
        - `threshold` number, required — The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
        - `threshold_type` 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage', required — Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
        - `name` string — Optional user-defined label to distinguish multiple alerts on the same feature.
      - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance.
        - `feature_id` string, required — The feature ID this overage allowed control applies to.
        - `enabled` boolean — Whether overage is allowed for this feature.
    - `config` object — Miscellaneous configurations for the customer.
      - `disable_pooled_balance` boolean — Whether to disable the shared customer-level pool for entities.
      - `disable_overage_billing` boolean — Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable_overage_billing setting.
  - `entity_data` object
    - `feature_id` string, required — The feature ID that this entity is associated with
    - `name` string — Name of the entity
    - `billing_controls` object — Billing controls for the entity.
      - `spend_limits` object[] — List of spend limits per feature. Each entry caps overage (overage_limit) and/or per-interval usage (usage_limit).
        - `feature_id` string — Optional feature ID this spend limit applies to.
        - `enabled` boolean — Whether the overage spend limit is enabled.
        - `limit_type` 'absolute' | 'usage_percentage' — How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
        - `overage_limit` number — Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
        - `skip_overage_billing` boolean — When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
      - `usage_limits` object[] — List of hard usage caps per feature for this entity. An entity entry overrides the customer's for that feature.
        - `feature_id` string, required — The feature this usage limit applies to.
        - `enabled` boolean — Whether this usage limit is enabled.
        - `limit` number, required — Maximum units allowed per interval.
        - `interval` 'day' | 'week' | 'month' | 'year', required — Interval for the cap, aligned to the customer's billing cycle.
        - `filter` object — When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
          - `properties` object, required
      - `usage_alerts` object[] — List of usage alert configurations per feature.
        - `feature_id` string — The feature ID this alert applies to.
        - `enabled` boolean — Whether this usage alert is enabled.
        - `threshold` number, required — The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
        - `threshold_type` 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage', required — Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
        - `name` string — Optional user-defined label to distinguish multiple alerts on the same feature.
      - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance.
        - `feature_id` string, required — The feature ID this overage allowed control applies to.
        - `enabled` boolean — Whether overage is allowed for this feature.

## Response `200`

OK

- object
  - `customer_id` string, required — The ID of the customer.
  - `entity_id` string — The ID of the entity, if the plan was attached to an entity.
  - `invoice` object — Invoice details if an invoice was created. Only present when a charge was made.
    - `status` string, nullable, required — The status of the invoice (e.g., 'paid', 'open', 'draft').
    - `stripe_id` string, required — The Stripe invoice ID.
    - `total` number, required — The total amount of the invoice in cents.
    - `currency` string, required — The three-letter ISO currency code (e.g., 'usd').
    - `hosted_invoice_url` string, nullable, required — URL to the hosted invoice page where the customer can view and pay the invoice.
  - `payment_url` string, nullable, required — URL to redirect the customer to complete payment. Null if no payment action is required.
  - `required_action` object — Details about any action required to complete the payment. Present when the payment could not be processed automatically.
    - `code` '3ds_required' | 'payment_method_required' | 'payment_failed' | 'payment_processing', required — The type of action required to complete the payment.
    - `reason` string, required — A human-readable explanation of why this action is required.

---

[API](https://skmtc.net/useautumn/apis/autumn-api.md) · [All operations](https://skmtc.net/useautumn/apis/autumn-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useautumn/autumn-api/revisions/29536933c0dc/schema)