---
title: "Multi Attach"
openapi: "openapi POST /v1/billing.multi_attach"
---

import { DynamicParamField } from "/snippets/dynamic-param-field.jsx";
import { DynamicResponseField } from "/snippets/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/snippets/dynamic-response-example.jsx";

### Body Parameters

<DynamicParamField body="customer_id" type="string" required>
  The ID of the customer to attach the plans to.
</DynamicParamField>

<DynamicParamField body="entity_id" type="string">
  The ID of the entity to attach the plans to.
</DynamicParamField>

<DynamicParamField body="plans" type="object[]" required>
  The list of plans to attach to the customer.
  <Expandable title="properties">
    <DynamicParamField body="plan_id" type="string" required>
      The ID of the plan to attach.
    </DynamicParamField>

    <DynamicParamField body="customize" type="object">
      Customize the plan to attach. Can override the price or items.
      <Expandable title="properties">
        <DynamicParamField body="price" type="object | null">
          Base price configuration for a plan.
          <Expandable title="properties">
            <DynamicParamField body="amount" type="number" required>
              Base price amount for the plan.
            </DynamicParamField>

            <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
              Billing interval (e.g. 'month', 'year').
            </DynamicParamField>

            <DynamicParamField body="interval_count" type="number">
              Number of intervals per billing cycle. Defaults to 1.
            </DynamicParamField>

          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="items" type="object[]">
          Override the items in the plan.
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string" required>
              The ID of the feature to configure.
            </DynamicParamField>

            <DynamicParamField body="included" type="number">
              Number of free units included. Balance resets to this each interval for consumable features.
            </DynamicParamField>

            <DynamicParamField body="unlimited" type="boolean">
              If true, customer has unlimited access to this feature.
            </DynamicParamField>

            <DynamicParamField body="reset" type="object">
              Reset configuration for consumable features. Omit for non-consumable features like seats.
              <Expandable title="properties">
                <DynamicParamField body="interval" type="'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.
                </DynamicParamField>

                <DynamicParamField body="interval_count" type="number">
                  Number of intervals between resets. Defaults to 1.
                </DynamicParamField>

              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="price" type="object">
              Pricing for usage beyond included units. Omit for free features.
              <Expandable title="properties">
                <DynamicParamField body="amount" type="number">
                  Price per billing_units after included usage. Either 'amount' or 'tiers' is required.
                </DynamicParamField>

                <DynamicParamField body="tiers" type="object[]">
                  Tiered pricing. Either 'amount' or 'tiers' is required.
                  <Expandable title="properties">
                    <DynamicParamField body="to" type="number" required />

                    <DynamicParamField body="amount" type="number" />

                    <DynamicParamField body="flat_amount" type="number" />

                  </Expandable>
                </DynamicParamField>

                <DynamicParamField body="tier_behavior" type="'graduated' | 'volume'" />

                <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
                  Billing interval. For consumable features, should match reset.interval.
                </DynamicParamField>

                <DynamicParamField body="interval_count" type="number">
                  Number of intervals per billing cycle. Defaults to 1.
                </DynamicParamField>

                <DynamicParamField body="billing_units" type="number">
                  Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
                </DynamicParamField>

                <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'" required>
                  'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
                </DynamicParamField>

                <DynamicParamField body="max_purchase" type="number">
                  Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total.
                </DynamicParamField>

              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="proration" type="object">
              Proration settings for prepaid features. Controls mid-cycle quantity change billing.
              <Expandable title="properties">
                <DynamicParamField body="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" required>
                  Billing behavior when quantity increases mid-cycle.
                </DynamicParamField>

                <DynamicParamField body="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" required>
                  Credit behavior when quantity decreases mid-cycle.
                </DynamicParamField>

              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="rollover" type="object">
              Rollover config for unused units. If set, unused included units carry over.
              <Expandable title="properties">
                <DynamicParamField body="max" type="number">
                  Max rollover units. Omit for unlimited rollover.
                </DynamicParamField>

                <DynamicParamField body="max_percentage" type="number">
                  Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
                </DynamicParamField>

                <DynamicParamField body="expiry_duration_type" type="'month' | 'forever'" required>
                  When rolled over units expire.
                </DynamicParamField>

                <DynamicParamField body="expiry_duration_length" type="number">
                  Number of periods before expiry.
                </DynamicParamField>

              </Expandable>
            </DynamicParamField>

          </Expandable>
        </DynamicParamField>

      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="feature_quantities" type="object[]">
      If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature.
      <Expandable title="properties">
        <DynamicParamField body="feature_id" type="string" required>
          The ID of the feature to set quantity for.
        </DynamicParamField>

        <DynamicParamField body="quantity" type="number">
          The quantity of the feature.
        </DynamicParamField>

        <DynamicParamField body="adjustable" type="boolean">
          Whether the customer can adjust the quantity.
        </DynamicParamField>

      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="version" type="number">
      The version of the plan to attach.
    </DynamicParamField>

    <DynamicParamField body="subscription_id" type="string">
      A unique ID to identify this subscription. Useful when attaching the same plan multiple times.
    </DynamicParamField>

  </Expandable>
</DynamicParamField>

<DynamicParamField body="free_trial" type="object | null">
  Free trial configuration for a plan.
  <Expandable title="properties">
    <DynamicParamField body="duration_length" type="number" required>
      Number of duration_type periods the trial lasts.
    </DynamicParamField>

    <DynamicParamField body="duration_type" type="'day' | 'month' | 'year'">
      Unit of time for the trial ('day', 'month', 'year').
    </DynamicParamField>

    <DynamicParamField body="card_required" type="boolean">
      If true, payment method required to start trial. Customer is charged after trial ends.
    </DynamicParamField>

    <DynamicParamField body="on_end" type="'bill' | 'revert'">
      Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
    </DynamicParamField>

  </Expandable>
</DynamicParamField>

<DynamicParamField body="invoice_mode" type="object">
  Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately.
  <Expandable title="properties">
    <DynamicParamField body="enabled" type="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.
    </DynamicParamField>

    <DynamicParamField body="enable_plan_immediately" type="boolean">
      If true, enables the plan immediately even though the invoice is not paid yet.
    </DynamicParamField>

    <DynamicParamField body="finalize" type="boolean">
      If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
    </DynamicParamField>

  </Expandable>
</DynamicParamField>

<DynamicParamField body="discounts" type="object[]">
  List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
  <Expandable title="properties">
    <DynamicParamField body="reward_id" type="string">
      The ID of the reward to apply as a discount.
    </DynamicParamField>

    <DynamicParamField body="promotion_code" type="string">
      The promotion code to apply as a discount.
    </DynamicParamField>

  </Expandable>
</DynamicParamField>

<DynamicParamField body="success_url" type="string">
  URL to redirect to after successful checkout.
</DynamicParamField>

<DynamicParamField body="checkout_session_params" type="object">
  Additional parameters to pass into the creation of the Stripe checkout session.
</DynamicParamField>

<DynamicParamField body="redirect_mode" type="'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.
</DynamicParamField>

<DynamicParamField body="new_billing_subscription" type="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.
</DynamicParamField>

<DynamicParamField body="enable_plan_immediately" type="boolean">
  If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout.
</DynamicParamField>

<DynamicParamField body="customer_data" type="object">
  Customer details to set when creating a customer
  <Expandable title="properties">
    <DynamicParamField body="name" type="string | null">
      Customer's name
    </DynamicParamField>

    <DynamicParamField body="email" type="string | null">
      Customer's email address
    </DynamicParamField>

    <DynamicParamField body="fingerprint" type="string | null">
      Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
    </DynamicParamField>

    <DynamicParamField body="metadata" type="object | null">
      Additional metadata for the customer
    </DynamicParamField>

    <DynamicParamField body="stripe_id" type="string | null">
      Stripe customer ID if you already have one
    </DynamicParamField>

    <DynamicParamField body="create_in_stripe" type="boolean">
      Whether to create the customer in Stripe
    </DynamicParamField>

    <DynamicParamField body="auto_enable_plan_id" type="string">
      The ID of the free plan to auto-enable for the customer
    </DynamicParamField>

    <DynamicParamField body="send_email_receipts" type="boolean">
      Whether to send email receipts to this customer
    </DynamicParamField>

    <DynamicParamField body="billing_controls" type="object">
      Billing controls for the customer (auto top-ups, etc.)
      <Expandable title="properties">
        <DynamicParamField body="auto_topups" type="object[]">
          List of auto top-up configurations per feature.
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string" required>
              The ID of the feature (credit balance) to auto top-up.
            </DynamicParamField>

            <DynamicParamField body="enabled" type="boolean">
              Whether auto top-up is enabled.
            </DynamicParamField>

            <DynamicParamField body="threshold" type="number" required>
              When the balance drops below this threshold, an auto top-up will be purchased.
            </DynamicParamField>

            <DynamicParamField body="quantity" type="number" required>
              Amount of credits to add per auto top-up.
            </DynamicParamField>

            <DynamicParamField body="purchase_limit" type="object">
              Optional rate limit to cap how often auto top-ups occur.
              <Expandable title="properties">
                <DynamicParamField body="interval" type="'hour' | 'day' | 'week' | 'month'" required>
                  The time interval for the purchase limit window.
                </DynamicParamField>

                <DynamicParamField body="interval_count" type="number">
                  Number of intervals in the purchase limit window.
                </DynamicParamField>

                <DynamicParamField body="limit" type="number" required>
                  Maximum number of auto top-ups allowed within the interval.
                </DynamicParamField>

              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="invoice_mode" type="boolean">
              When true, auto top-up creates a send_invoice invoice instead of auto-charging.
            </DynamicParamField>

          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="spend_limits" type="object[]">
          List of overage spend limits per feature.
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string">
              Optional feature ID this spend limit applies to.
            </DynamicParamField>

            <DynamicParamField body="enabled" type="boolean">
              Whether this spend limit is enabled.
            </DynamicParamField>

            <DynamicParamField body="overage_limit" type="number">
              Maximum allowed overage spend for the target feature.
            </DynamicParamField>

          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="usage_alerts" type="object[]">
          List of usage alert configurations per feature.
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string">
              The feature ID this alert applies to.
            </DynamicParamField>

            <DynamicParamField body="enabled" type="boolean">
              Whether this usage alert is enabled.
            </DynamicParamField>

            <DynamicParamField body="threshold" type="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).
            </DynamicParamField>

            <DynamicParamField body="threshold_type" 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.
            </DynamicParamField>

            <DynamicParamField body="name" type="string">
              Optional user-defined label to distinguish multiple alerts on the same feature.
            </DynamicParamField>

          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="overage_allowed" type="object[]">
          List of overage allowed controls per feature. When enabled, usage can exceed balance.
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string" required>
              The feature ID this overage allowed control applies to.
            </DynamicParamField>

            <DynamicParamField body="enabled" type="boolean">
              Whether overage is allowed for this feature.
            </DynamicParamField>

          </Expandable>
        </DynamicParamField>

      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="config" type="object">
      Miscellaneous configurations for the customer.
      <Expandable title="properties">
        <DynamicParamField body="disable_pooled_balance" type="boolean">
          Whether to disable the shared customer-level pool for entities.
        </DynamicParamField>

      </Expandable>
    </DynamicParamField>

  </Expandable>
</DynamicParamField>

<DynamicParamField body="entity_data" type="object">
  <Expandable title="properties">
    <DynamicParamField body="feature_id" type="string" required>
      The feature ID that this entity is associated with
    </DynamicParamField>

    <DynamicParamField body="name" type="string">
      Name of the entity
    </DynamicParamField>

    <DynamicParamField body="billing_controls" type="object">
      Billing controls for the entity.
      <Expandable title="properties">
        <DynamicParamField body="spend_limits" type="object[]">
          List of overage spend limits per feature.
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string">
              Optional feature ID this spend limit applies to.
            </DynamicParamField>

            <DynamicParamField body="enabled" type="boolean">
              Whether this spend limit is enabled.
            </DynamicParamField>

            <DynamicParamField body="overage_limit" type="number">
              Maximum allowed overage spend for the target feature.
            </DynamicParamField>

          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="usage_alerts" type="object[]">
          List of usage alert configurations per feature.
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string">
              The feature ID this alert applies to.
            </DynamicParamField>

            <DynamicParamField body="enabled" type="boolean">
              Whether this usage alert is enabled.
            </DynamicParamField>

            <DynamicParamField body="threshold" type="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).
            </DynamicParamField>

            <DynamicParamField body="threshold_type" 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.
            </DynamicParamField>

            <DynamicParamField body="name" type="string">
              Optional user-defined label to distinguish multiple alerts on the same feature.
            </DynamicParamField>

          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="overage_allowed" type="object[]">
          List of overage allowed controls per feature. When enabled, usage can exceed balance.
          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string" required>
              The feature ID this overage allowed control applies to.
            </DynamicParamField>

            <DynamicParamField body="enabled" type="boolean">
              Whether overage is allowed for this feature.
            </DynamicParamField>

          </Expandable>
        </DynamicParamField>

      </Expandable>
    </DynamicParamField>

  </Expandable>
</DynamicParamField>


### Response

<DynamicResponseField name="customer_id" type="string">
  The ID of the customer.
</DynamicResponseField>

<DynamicResponseField name="entity_id" type="string">
  The ID of the entity, if the plan was attached to an entity.
</DynamicResponseField>

<DynamicResponseField name="invoice" type="object">
  Invoice details if an invoice was created. Only present when a charge was made.
  <Expandable title="properties">
    <DynamicResponseField name="status" type="string | null">
      The status of the invoice (e.g., 'paid', 'open', 'draft').
    </DynamicResponseField>

    <DynamicResponseField name="stripe_id" type="string">
      The Stripe invoice ID.
    </DynamicResponseField>

    <DynamicResponseField name="total" type="number">
      The total amount of the invoice in cents.
    </DynamicResponseField>

    <DynamicResponseField name="currency" type="string">
      The three-letter ISO currency code (e.g., 'usd').
    </DynamicResponseField>

    <DynamicResponseField name="hosted_invoice_url" type="string | null">
      URL to the hosted invoice page where the customer can view and pay the invoice.
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="payment_url" type="string | null">
  URL to redirect the customer to complete payment. Null if no payment action is required.
</DynamicResponseField>

<DynamicResponseField name="required_action" type="object">
  Details about any action required to complete the payment. Present when the payment could not be processed automatically.
  <Expandable title="properties">
    <DynamicResponseField name="code" type="'3ds_required' | 'payment_method_required' | 'payment_failed'">
      The type of action required to complete the payment.
    </DynamicResponseField>

    <DynamicResponseField name="reason" type="string">
      A human-readable explanation of why this action is required.
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>


<ResponseExample>
```json 200
{
  "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
}
```
</ResponseExample>