> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach

> Attaches a plan to a customer. Handles new subscriptions, upgrades and downgrades.

Use this endpoint to subscribe a customer to a plan, upgrade/downgrade between plans, or add an add-on product.

export const DynamicResponseExample = ({json, statusCode = "200"}) => {
  const toCamelCase = str => {
    return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
  };
  const convertKeysToCamelCase = obj => {
    if (Array.isArray(obj)) {
      return obj.map(item => convertKeysToCamelCase(item));
    }
    if (obj !== null && typeof obj === "object") {
      return Object.keys(obj).reduce((acc, key) => {
        const camelKey = toCamelCase(key);
        acc[camelKey] = convertKeysToCamelCase(obj[key]);
        return acc;
      }, {});
    }
    return obj;
  };
  const [isTypeScript, setIsTypeScript] = useState(() => {
    if (typeof window !== "undefined") {
      try {
        const lang = localStorage.getItem("code");
        return JSON.parse(lang) === "typescript";
      } catch {
        return true;
      }
    }
    return true;
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      if (event.detail?.key === "code") {
        try {
          const value = JSON.parse(event.detail.value);
          setIsTypeScript(value === "typescript");
        } catch {}
      }
    };
    const pollInterval = setInterval(() => {
      try {
        const lang = localStorage.getItem("code");
        const value = JSON.parse(lang);
        setIsTypeScript(value === "typescript");
      } catch {}
    }, 300);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, []);
  const camelCaseJson = useMemo(() => convertKeysToCamelCase(json), [json]);
  const snakeCaseString = JSON.stringify(json, null, 2);
  const camelCaseString = JSON.stringify(camelCaseJson, null, 2);
  return <ResponseExample>
			{isTypeScript ? <CodeBlock language="json" filename={statusCode}>
					{camelCaseString}
				</CodeBlock> : <CodeBlock language="json" filename={statusCode}>
					{snakeCaseString}
				</CodeBlock>}
		</ResponseExample>;
};

export const DynamicResponseField = ({children, name, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedName = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(name) : name;
    } catch {
      return name;
    }
  }, [name, lang]);
  return <ResponseField name={resolvedName} {...props}>
			{children}
		</ResponseField>;
};

export const DynamicParamField = ({children, body, path, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedBody = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(body) : body;
    } catch {
      return body;
    }
  }, [body, lang]);
  const resolvedPath = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(path) : path;
    } catch {
      return path;
    }
  }, [path, lang]);
  return <ParamField body={resolvedBody} path={resolvedPath} {...props}>
			{children}
		</ParamField>;
};

<Note>
  The attach endpoint subscribes a customer to a plan. It handles new
  subscriptions, upgrades, and downgrades automatically. For modifying an
  existing subscription (like changing quantities or canceling), use
  [update](/api-reference/billing/billingUpdate) instead.
</Note>

### Common Use Cases

<CodeGroup>
  ```typescript Subscribe to a plan theme={null}
  const response = await autumn.billing.attach({
      customerId: "cus_123",
      planId: "pro_plan",
  });

  if (response.paymentUrl) {
      // Redirect customer to checkout
      window.location.href = response.paymentUrl;
  }
  ```

  ```typescript Custom pricing theme={null}
  const response = await autumn.billing.attach({
      customerId: "cus_123",
      planId: "enterprise_plan",
      customize: {
          price: {
              amount: 999, // $999
              interval: "month",
          },
      },
  });
  ```

  ```typescript Attach plan with prepaid quantities theme={null}
  const response = await autumn.billing.attach({
      customerId: "cus_123",
      planId: "team_plan",
      featureQuantities: [{ featureId: "seats", quantity: 5 }],
  });
  ```

  ```typescript Pass metadata to Stripe subscription theme={null}
  const response = await autumn.billing.attach({
      customerId: "cus_123",
      planId: "pro_plan",
      checkoutSessionParams: {
          subscriptionData: {
              metadata: {
                  userId: "internal-user-id",
                  source: "upgrade-flow",
              },
          },
      },
  });
  ```
</CodeGroup>

### Stripe checkout session params

Use `checkoutSessionParams` to pass additional data to the Stripe checkout session. Values you provide are deep-merged with Autumn's internal parameters, so your fields are preserved alongside ones Autumn sets automatically (like `trial_end` or internal metadata).

This is useful for attaching custom metadata to the Stripe subscription created during checkout — for example, linking subscriptions to internal user IDs or tracking the source of the purchase.

### Currency

Pass `currency` to bill the attach in a specific currency the plan offers via [`additional_currencies`](/documentation/concepts/plans#multiple-currencies). If omitted, Autumn uses the customer's currency, falling back to your organization's default.

A customer who has paid is locked to their currency: passing a different one, or attaching a plan that doesn't offer a paid price in their currency, fails with a `currency_mismatch` error before any billing happens.

### Body Parameters

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

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

<DynamicParamField body="plan_id" type="string" required>
  The ID of the plan.
</DynamicParamField>

<DynamicParamField body="feature_quantities" type="object[]">
  If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.

  <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="customize" type="object">
  Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.

  <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>

        <DynamicParamField body="additional_currencies" type="object[]">
          Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

          <Expandable title="properties">
            <DynamicParamField body="currency" type="string" required>
              Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
            </DynamicParamField>

            <DynamicParamField body="amount" type="number" required>
              Price amount in this currency. Set explicitly per currency, not converted from the base amount.
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>
      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="items" type="object[]">
      Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add\_items / remove\_items / deprecated update\_items.

      <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="additional_currencies" type="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'.

              <Expandable title="properties">
                <DynamicParamField body="currency" type="string" required>
                  Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                </DynamicParamField>

                <DynamicParamField body="amount" type="number" required>
                  Price amount in this currency. Set explicitly per currency, not converted from the base amount.
                </DynamicParamField>
              </Expandable>
            </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" />

                <DynamicParamField body="additional_currencies" type="object[]">
                  Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.

                  <Expandable title="properties">
                    <DynamicParamField body="currency" type="string" required>
                      Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                    </DynamicParamField>

                    <DynamicParamField body="amount" type="number">
                      Per-unit amount for this tier in this currency.
                    </DynamicParamField>

                    <DynamicParamField body="flat_amount" type="number">
                      Flat amount for this tier in this currency, if the tier uses one.
                    </DynamicParamField>
                  </Expandable>
                </DynamicParamField>
              </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 | null">
              Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.
            </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>

    <DynamicParamField body="add_items" type="object[]">
      Items to add to 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="additional_currencies" type="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'.

              <Expandable title="properties">
                <DynamicParamField body="currency" type="string" required>
                  Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                </DynamicParamField>

                <DynamicParamField body="amount" type="number" required>
                  Price amount in this currency. Set explicitly per currency, not converted from the base amount.
                </DynamicParamField>
              </Expandable>
            </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" />

                <DynamicParamField body="additional_currencies" type="object[]">
                  Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.

                  <Expandable title="properties">
                    <DynamicParamField body="currency" type="string" required>
                      Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                    </DynamicParamField>

                    <DynamicParamField body="amount" type="number">
                      Per-unit amount for this tier in this currency.
                    </DynamicParamField>

                    <DynamicParamField body="flat_amount" type="number">
                      Flat amount for this tier in this currency, if the tier uses one.
                    </DynamicParamField>
                  </Expandable>
                </DynamicParamField>
              </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 | null">
              Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.
            </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>

    <DynamicParamField body="remove_items" type="object[]">
      Filters selecting items to remove from the plan.

      <Expandable title="properties">
        <DynamicParamField body="feature_id" type="string">
          Match items linked to this feature.
        </DynamicParamField>

        <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'">
          Match items with this billing method (prepaid or usage\_based).
        </DynamicParamField>

        <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
          Match items with this interval. Accepts either a BillingInterval (price-side) or a ResetInterval (reset-side, includes day/hour/minute) so price-less items keyed by reset.interval can be disambiguated.
        </DynamicParamField>

        <DynamicParamField body="interval_count" type="integer">
          Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.
        </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="billing_controls" type="object">
      Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.

      <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. Pass count to set the current window's consumed top-ups.

              <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>

                <DynamicParamField body="count" type="number">
                  Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.
                </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 (caps overage spend).

          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string">
              Optional feature ID this spend limit applies to.
            </DynamicParamField>

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

            <DynamicParamField body="limit_type" type="'absolute' | 'usage_percentage'">
              How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
            </DynamicParamField>

            <DynamicParamField body="overage_limit" type="number">
              Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.
            </DynamicParamField>

            <DynamicParamField body="skip_overage_billing" type="boolean">
              When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="usage_limits" type="object[]">
          List of hard usage caps per feature (max units per interval).

          <Expandable title="properties">
            <DynamicParamField body="feature_id" type="string" required>
              The feature this usage limit applies to.
            </DynamicParamField>

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

            <DynamicParamField body="limit" type="number" required>
              Maximum units allowed per interval.
            </DynamicParamField>

            <DynamicParamField body="interval" type="'day' | 'week' | 'month' | 'year'" required>
              Interval for the cap, aligned to the customer's billing cycle.
            </DynamicParamField>

            <DynamicParamField body="filter" type="object">
              When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.

              <Expandable title="properties">
                <DynamicParamField body="properties.{key}" type="string" required />
              </Expandable>
            </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="upsert_licenses" type="object[]">
      License links to add or override for this customer, keyed by license\_plan\_id. Omitted fields inherit the plan catalog link (included defaults to 1 when the license is not in the catalog). A bare entry restores the license to pure catalog inheritance.

      <Expandable title="properties">
        <DynamicParamField body="license_plan_id" type="string" required />

        <DynamicParamField body="included" type="integer" />

        <DynamicParamField body="prepaid_only" type="boolean" />

        <DynamicParamField body="customize" type="object | null">
          <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>

                <DynamicParamField body="additional_currencies" type="object[]">
                  Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

                  <Expandable title="properties">
                    <DynamicParamField body="currency" type="string" required>
                      Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                    </DynamicParamField>

                    <DynamicParamField body="amount" type="number" required>
                      Price amount in this currency. Set explicitly per currency, not converted from the base amount.
                    </DynamicParamField>
                  </Expandable>
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="add_items" type="object[]">
              <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="additional_currencies" type="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'.

                      <Expandable title="properties">
                        <DynamicParamField body="currency" type="string" required>
                          Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
                        </DynamicParamField>

                        <DynamicParamField body="amount" type="number" required>
                          Price amount in this currency. Set explicitly per currency, not converted from the base amount.
                        </DynamicParamField>
                      </Expandable>
                    </DynamicParamField>

                    <DynamicParamField body="tiers" type="object[]">
                      Tiered pricing. Either 'amount' or 'tiers' is required.

                      <Expandable title="properties">
                        <DynamicParamField body="to" type="any" />

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

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

                        <DynamicParamField body="additional_currencies" type="any[]">
                          Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
                        </DynamicParamField>
                      </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 | null">
                      Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.
                    </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>

            <DynamicParamField body="remove_items" type="object[]">
              <Expandable title="properties">
                <DynamicParamField body="feature_id" type="string">
                  Match items linked to this feature.
                </DynamicParamField>

                <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'">
                  Match items with this billing method (prepaid or usage\_based).
                </DynamicParamField>

                <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
                  Match items with this interval. Accepts either a BillingInterval (price-side) or a ResetInterval (reset-side, includes day/hour/minute) so price-less items keyed by reset.interval can be disambiguated.
                </DynamicParamField>

                <DynamicParamField body="interval_count" type="integer">
                  Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.
                </DynamicParamField>
              </Expandable>
            </DynamicParamField>
          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="metadata" type="object" />
      </Expandable>
    </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. This uses Stripe's send\_invoice collection method.

  <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>

    <DynamicParamField body="invoice_template_id" type="string">
      ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
    </DynamicParamField>

    <DynamicParamField body="net_terms_days" type="integer">
      Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="proration_behavior" type="'prorate_immediately' | 'none'">
  How to handle proration when updating an existing subscription. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
</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="subscription_id" type="string">
  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.
</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="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="billing_cycle_anchor" type="any">
  Reset the billing cycle anchor immediately with 'now'.
</DynamicParamField>

<DynamicParamField body="plan_schedule" type="'immediate' | 'end_of_cycle'">
  When the plan change should take effect. 'immediate' applies now, 'end\_of\_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
</DynamicParamField>

<DynamicParamField body="starts_at" type="integer">
  Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription.
</DynamicParamField>

<DynamicParamField body="ends_at" type="integer">
  Unix timestamp in milliseconds for when the attached plan should end.
</DynamicParamField>

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

<DynamicParamField body="long_lived_checkout" type="boolean">
  If true, returns an Autumn-hosted checkout link that can create a fresh Stripe checkout session when opened.
</DynamicParamField>

<DynamicParamField body="custom_line_items" type="object[]">
  Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans).

  <Expandable title="properties">
    <DynamicParamField body="amount" type="number" required>
      Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
    </DynamicParamField>

    <DynamicParamField body="description" type="string" required>
      Description for the line item.
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="processor_subscription_id" type="string">
  The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.
</DynamicParamField>

<DynamicParamField body="carry_over_balances" type="object">
  Whether to carry over balances from the previous plan.

  <Expandable title="properties">
    <DynamicParamField body="enabled" type="boolean" required>
      Whether to carry over balances from the previous plan.
    </DynamicParamField>

    <DynamicParamField body="feature_ids" type="string[]">
      The IDs of the features to carry over balances from. If left undefined, all features will be carried over.
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="carry_over_usages" type="object">
  Whether to carry over usages from the previous plan.

  <Expandable title="properties">
    <DynamicParamField body="enabled" type="boolean" required>
      Whether to carry over usages from the previous plan.
    </DynamicParamField>

    <DynamicParamField body="feature_ids" type="string[]">
      The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="license_quantities" type="object[]">
  Seat quantities for the plan's licenses, keyed by license plan.

  <Expandable title="properties">
    <DynamicParamField body="license_plan_id" type="string" required>
      The license plan to set seat quantity for.
    </DynamicParamField>

    <DynamicParamField body="quantity" type="integer" required>
      Total seats for the license, inclusive of the plan's included amount — seats beyond it are paid.
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="metadata.{key}" type="string">
  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.
</DynamicParamField>

<DynamicParamField body="no_billing_changes" type="boolean">
  If true, skips any billing changes for the attach operation.
</DynamicParamField>

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

<DynamicParamField body="tax_rate_id" type="string">
  Stripe tax rate ID (txr\_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items.
</DynamicParamField>

<DynamicParamField body="currency" type="string">
  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.
</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' | 'payment_processing'">
      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 theme={null}
  {
    "customer_id": "cus_123",
    "payment_url": "https://checkout.stripe.com/..."
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi POST /v1/billing.attach
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.3.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths:
  /v1/billing.attach:
    post:
      tags:
        - billing
      description: >-
        Attaches a plan to a customer. Handles new subscriptions, upgrades and
        downgrades.


        Use this endpoint to subscribe a customer to a plan, upgrade/downgrade
        between plans, or add an add-on product.
      operationId: attach
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            default: 2.3.0
          x-speakeasy-globals-hidden: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                  description: The ID of the customer to attach the plan to.
                entity_id:
                  type: string
                  description: The ID of the entity to attach the plan to.
                plan_id:
                  type: string
                  description: The ID of the plan.
                feature_quantities:
                  type: array
                  items:
                    type: object
                    properties:
                      feature_id:
                        type: string
                        description: The ID of the feature to set quantity for.
                      quantity:
                        type: number
                        minimum: 0
                        description: The quantity of the feature.
                      adjustable:
                        type: boolean
                        description: Whether the customer can adjust the quantity.
                    required:
                      - feature_id
                    title: FeatureQuantity
                    description: Quantity configuration for a prepaid feature.
                  description: >-
                    If this plan contains prepaid features, use this field to
                    specify the quantity of each prepaid feature. This quantity
                    includes the included amount and billing units defined when
                    setting up the plan.
                version:
                  type: number
                  description: The version of the plan to attach.
                customize:
                  type: object
                  properties:
                    price:
                      anyOf:
                        - type: object
                          properties:
                            amount:
                              type: number
                              description: Base price amount for the plan.
                            interval:
                              enum:
                                - one_off
                                - week
                                - month
                                - quarter
                                - semi_annual
                                - year
                              type: string
                              description: Billing interval (e.g. 'month', 'year').
                            interval_count:
                              type: number
                              description: >-
                                Number of intervals per billing cycle. Defaults
                                to 1.
                            additional_currencies:
                              type: array
                              items:
                                type: object
                                properties:
                                  currency:
                                    type: string
                                    description: >-
                                      Three-letter Stripe-supported currency
                                      code (e.g. 'eur', 'gbp').
                                  amount:
                                    type: number
                                    description: >-
                                      Price amount in this currency. Set
                                      explicitly per currency, not converted
                                      from the base amount.
                                required:
                                  - currency
                                  - amount
                              description: >-
                                Base price amounts in additional currencies. The
                                base 'amount' is in the org's default currency.
                          required:
                            - amount
                            - interval
                          title: BasePrice
                          description: Base price configuration for a plan.
                        - type: 'null'
                      description: >-
                        Override the base price of the plan. Pass null to remove
                        the base price.
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: The ID of the feature to configure.
                          included:
                            type: number
                            description: >-
                              Number of free units included. Balance resets to
                              this each interval for consumable features.
                          unlimited:
                            type: boolean
                            description: >-
                              If true, customer has unlimited access to this
                              feature.
                          reset:
                            type: object
                            properties:
                              interval:
                                enum:
                                  - one_off
                                  - minute
                                  - hour
                                  - day
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                                description: >-
                                  Interval at which balance resets (e.g.
                                  'month', 'year'). For consumable features
                                  only.
                              interval_count:
                                type: number
                                description: >-
                                  Number of intervals between resets. Defaults
                                  to 1.
                            required:
                              - interval
                            description: >-
                              Reset configuration for consumable features. Omit
                              for non-consumable features like seats.
                          price:
                            type: object
                            properties:
                              amount:
                                type: number
                                description: >-
                                  Price per billing_units after included usage.
                                  Either 'amount' or 'tiers' is required.
                              additional_currencies:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    currency:
                                      type: string
                                      description: >-
                                        Three-letter Stripe-supported currency
                                        code (e.g. 'eur', 'gbp').
                                    amount:
                                      type: number
                                      description: >-
                                        Price amount in this currency. Set
                                        explicitly per currency, not converted
                                        from the base amount.
                                  required:
                                    - currency
                                    - amount
                                description: >-
                                  Amounts in additional currencies for this flat
                                  price. The base 'amount' is in the org's
                                  default currency. Only valid with 'amount',
                                  not 'tiers'.
                              tiers:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    to:
                                      anyOf:
                                        - type: number
                                        - const: inf
                                    amount:
                                      type: number
                                    flat_amount:
                                      type: number
                                    additional_currencies:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          currency:
                                            type: string
                                            description: >-
                                              Three-letter Stripe-supported currency
                                              code (e.g. 'eur', 'gbp').
                                          amount:
                                            type: number
                                            description: >-
                                              Per-unit amount for this tier in this
                                              currency.
                                          flat_amount:
                                            type: number
                                            description: >-
                                              Flat amount for this tier in this
                                              currency, if the tier uses one.
                                        required:
                                          - currency
                                      description: >-
                                        Per-currency amounts for this tier. Tier
                                        boundaries ('to') are shared across all
                                        currencies.
                                  required:
                                    - to
                                description: >-
                                  Tiered pricing.  Either 'amount' or 'tiers' is
                                  required.
                              tier_behavior:
                                enum:
                                  - graduated
                                  - volume
                                type: string
                              interval:
                                enum:
                                  - one_off
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                                description: >-
                                  Billing interval. For consumable features,
                                  should match reset.interval.
                              interval_count:
                                type: number
                                default: 1
                                description: >-
                                  Number of intervals per billing cycle.
                                  Defaults to 1.
                              billing_units:
                                type: number
                                default: 1
                                description: >-
                                  Units per price increment. Usage is rounded UP
                                  when billed (e.g. billing_units=100 means 101
                                  rounds to 200).
                              billing_method:
                                enum:
                                  - prepaid
                                  - usage_based
                                type: string
                                description: >-
                                  'prepaid' for upfront payment (seats),
                                  'usage_based' for pay-as-you-go.
                              max_purchase:
                                anyOf:
                                  - type: number
                                  - type: 'null'
                                description: >-
                                  Max units purchasable beyond included. E.g.
                                  included=100, max_purchase=300 allows 400
                                  total. Null for no limit.
                            required:
                              - interval
                              - billing_method
                            description: >-
                              Pricing for usage beyond included units. Omit for
                              free features.
                          proration:
                            type: object
                            properties:
                              on_increase:
                                enum:
                                  - bill_immediately
                                  - prorate_immediately
                                  - prorate_next_cycle
                                  - bill_next_cycle
                                type: string
                                description: >-
                                  Billing behavior when quantity increases
                                  mid-cycle.
                              on_decrease:
                                enum:
                                  - prorate
                                  - prorate_immediately
                                  - prorate_next_cycle
                                  - none
                                  - no_prorations
                                type: string
                                description: >-
                                  Credit behavior when quantity decreases
                                  mid-cycle.
                            required:
                              - on_increase
                              - on_decrease
                            description: >-
                              Proration settings for prepaid features. Controls
                              mid-cycle quantity change billing.
                          rollover:
                            type: object
                            properties:
                              max:
                                type: number
                                description: >-
                                  Max rollover units. Omit for unlimited
                                  rollover.
                              max_percentage:
                                type: number
                                description: >-
                                  Maximum rollover as a percentage (0-100) of
                                  included + prepaid grant. Mutually exclusive
                                  with max.
                              expiry_duration_type:
                                enum:
                                  - month
                                  - forever
                                type: string
                                description: When rolled over units expire.
                              expiry_duration_length:
                                type: number
                                description: Number of periods before expiry.
                            required:
                              - expiry_duration_type
                            description: >-
                              Rollover config for unused units. If set, unused
                              included units carry over.
                        required:
                          - feature_id
                        title: PlanItem
                        description: >-
                          Configuration for a feature item in a plan, including
                          usage limits, pricing, and rollover settings.
                      description: >-
                        Override the items in the plan (PUT-style — replaces all
                        existing items). Mutually exclusive with add_items /
                        remove_items / deprecated update_items.
                    add_items:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: The ID of the feature to configure.
                          included:
                            type: number
                            description: >-
                              Number of free units included. Balance resets to
                              this each interval for consumable features.
                          unlimited:
                            type: boolean
                            description: >-
                              If true, customer has unlimited access to this
                              feature.
                          reset:
                            type: object
                            properties:
                              interval:
                                enum:
                                  - one_off
                                  - minute
                                  - hour
                                  - day
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                                description: >-
                                  Interval at which balance resets (e.g.
                                  'month', 'year'). For consumable features
                                  only.
                              interval_count:
                                type: number
                                description: >-
                                  Number of intervals between resets. Defaults
                                  to 1.
                            required:
                              - interval
                            description: >-
                              Reset configuration for consumable features. Omit
                              for non-consumable features like seats.
                          price:
                            type: object
                            properties:
                              amount:
                                type: number
                                description: >-
                                  Price per billing_units after included usage.
                                  Either 'amount' or 'tiers' is required.
                              additional_currencies:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    currency:
                                      type: string
                                      description: >-
                                        Three-letter Stripe-supported currency
                                        code (e.g. 'eur', 'gbp').
                                    amount:
                                      type: number
                                      description: >-
                                        Price amount in this currency. Set
                                        explicitly per currency, not converted
                                        from the base amount.
                                  required:
                                    - currency
                                    - amount
                                description: >-
                                  Amounts in additional currencies for this flat
                                  price. The base 'amount' is in the org's
                                  default currency. Only valid with 'amount',
                                  not 'tiers'.
                              tiers:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    to:
                                      anyOf:
                                        - type: number
                                        - const: inf
                                    amount:
                                      type: number
                                    flat_amount:
                                      type: number
                                    additional_currencies:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          currency:
                                            type: string
                                            description: >-
                                              Three-letter Stripe-supported currency
                                              code (e.g. 'eur', 'gbp').
                                          amount:
                                            type: number
                                            description: >-
                                              Per-unit amount for this tier in this
                                              currency.
                                          flat_amount:
                                            type: number
                                            description: >-
                                              Flat amount for this tier in this
                                              currency, if the tier uses one.
                                        required:
                                          - currency
                                      description: >-
                                        Per-currency amounts for this tier. Tier
                                        boundaries ('to') are shared across all
                                        currencies.
                                  required:
                                    - to
                                description: >-
                                  Tiered pricing.  Either 'amount' or 'tiers' is
                                  required.
                              tier_behavior:
                                enum:
                                  - graduated
                                  - volume
                                type: string
                              interval:
                                enum:
                                  - one_off
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                                description: >-
                                  Billing interval. For consumable features,
                                  should match reset.interval.
                              interval_count:
                                type: number
                                default: 1
                                description: >-
                                  Number of intervals per billing cycle.
                                  Defaults to 1.
                              billing_units:
                                type: number
                                default: 1
                                description: >-
                                  Units per price increment. Usage is rounded UP
                                  when billed (e.g. billing_units=100 means 101
                                  rounds to 200).
                              billing_method:
                                enum:
                                  - prepaid
                                  - usage_based
                                type: string
                                description: >-
                                  'prepaid' for upfront payment (seats),
                                  'usage_based' for pay-as-you-go.
                              max_purchase:
                                anyOf:
                                  - type: number
                                  - type: 'null'
                                description: >-
                                  Max units purchasable beyond included. E.g.
                                  included=100, max_purchase=300 allows 400
                                  total. Null for no limit.
                            required:
                              - interval
                              - billing_method
                            description: >-
                              Pricing for usage beyond included units. Omit for
                              free features.
                          proration:
                            type: object
                            properties:
                              on_increase:
                                enum:
                                  - bill_immediately
                                  - prorate_immediately
                                  - prorate_next_cycle
                                  - bill_next_cycle
                                type: string
                                description: >-
                                  Billing behavior when quantity increases
                                  mid-cycle.
                              on_decrease:
                                enum:
                                  - prorate
                                  - prorate_immediately
                                  - prorate_next_cycle
                                  - none
                                  - no_prorations
                                type: string
                                description: >-
                                  Credit behavior when quantity decreases
                                  mid-cycle.
                            required:
                              - on_increase
                              - on_decrease
                            description: >-
                              Proration settings for prepaid features. Controls
                              mid-cycle quantity change billing.
                          rollover:
                            type: object
                            properties:
                              max:
                                type: number
                                description: >-
                                  Max rollover units. Omit for unlimited
                                  rollover.
                              max_percentage:
                                type: number
                                description: >-
                                  Maximum rollover as a percentage (0-100) of
                                  included + prepaid grant. Mutually exclusive
                                  with max.
                              expiry_duration_type:
                                enum:
                                  - month
                                  - forever
                                type: string
                                description: When rolled over units expire.
                              expiry_duration_length:
                                type: number
                                description: Number of periods before expiry.
                            required:
                              - expiry_duration_type
                            description: >-
                              Rollover config for unused units. If set, unused
                              included units carry over.
                        required:
                          - feature_id
                        title: PlanItem
                        description: >-
                          Configuration for a feature item in a plan, including
                          usage limits, pricing, and rollover settings.
                      description: Items to add to the plan.
                    remove_items:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: Match items linked to this feature.
                          billing_method:
                            enum:
                              - prepaid
                              - usage_based
                            type: string
                            description: >-
                              Match items with this billing method (prepaid or
                              usage_based).
                          interval:
                            anyOf:
                              - enum:
                                  - one_off
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                              - enum:
                                  - one_off
                                  - minute
                                  - hour
                                  - day
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                            description: >-
                              Match items with this interval. Accepts either a
                              BillingInterval (price-side) or a ResetInterval
                              (reset-side, includes day/hour/minute) so
                              price-less items keyed by reset.interval can be
                              disambiguated.
                          interval_count:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                            exclusiveMinimum: 0
                            description: >-
                              Match items with this interval_count.
                              Disambiguates between items that share an interval
                              but differ in count.
                        title: PlanItemFilter
                        description: >-
                          Filter for matching plan items. All provided fields
                          must match (AND).
                      description: Filters selecting items to remove from the plan.
                    free_trial:
                      anyOf:
                        - type: object
                          properties:
                            duration_length:
                              type: number
                              description: Number of duration_type periods the trial lasts.
                            duration_type:
                              enum:
                                - day
                                - month
                                - year
                              type: string
                              default: month
                              description: >-
                                Unit of time for the trial ('day', 'month',
                                'year').
                            card_required:
                              type: boolean
                              default: true
                              description: >-
                                If true, payment method required to start trial.
                                Customer is charged after trial ends.
                            on_end:
                              enum:
                                - bill
                                - revert
                              type: string
                              description: >-
                                Behavior when the trial ends. 'bill' charges the
                                customer (default). 'revert' expires the trial
                                and restores the customer's previous plan.
                          required:
                            - duration_length
                          title: FreeTrialParams
                          description: Free trial configuration for a plan.
                        - type: 'null'
                      description: >-
                        Override the plan's default free trial. Pass an object
                        to set a custom trial, or null to remove the trial
                        entirely.
                    billing_controls:
                      type: object
                      properties:
                        auto_topups:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: >-
                                  The ID of the feature (credit balance) to auto
                                  top-up.
                              enabled:
                                type: boolean
                                default: false
                                description: Whether auto top-up is enabled.
                              threshold:
                                type: number
                                description: >-
                                  When the balance drops below this threshold,
                                  an auto top-up will be purchased.
                              quantity:
                                type: number
                                minimum: 1
                                description: Amount of credits to add per auto top-up.
                              purchase_limit:
                                type: object
                                properties:
                                  interval:
                                    enum:
                                      - hour
                                      - day
                                      - week
                                      - month
                                    type: string
                                    description: >-
                                      The time interval for the purchase limit
                                      window.
                                  interval_count:
                                    type: number
                                    minimum: 1
                                    default: 1
                                    description: >-
                                      Number of intervals in the purchase limit
                                      window.
                                  limit:
                                    type: number
                                    minimum: 1
                                    description: >-
                                      Maximum number of auto top-ups allowed
                                      within the interval.
                                  count:
                                    type: number
                                    minimum: 0
                                    description: >-
                                      Set the current window's consumed auto
                                      top-up count. Omit to leave runtime state
                                      unchanged.
                                required:
                                  - interval
                                  - limit
                                description: >-
                                  Optional rate limit to cap how often auto
                                  top-ups occur. Pass count to set the current
                                  window's consumed top-ups.
                              invoice_mode:
                                type: boolean
                                description: >-
                                  When true, auto top-up creates a send_invoice
                                  invoice instead of auto-charging.
                            required:
                              - feature_id
                              - threshold
                              - quantity
                          description: List of auto top-up configurations per feature.
                        spend_limits:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: >-
                                  Optional feature ID this spend limit applies
                                  to.
                              enabled:
                                type: boolean
                                default: false
                                description: Whether the overage spend limit is enabled.
                              limit_type:
                                enum:
                                  - absolute
                                  - usage_percentage
                                type: string
                                description: >-
                                  How overage_limit is interpreted: an absolute
                                  overage cap (default) or a percentage of the
                                  main-plan allowance.
                              overage_limit:
                                type: number
                                minimum: 0
                                description: >-
                                  Overage cap for the feature: absolute units,
                                  or a percent (e.g. 120) when limit_type is
                                  usage_percentage.
                              skip_overage_billing:
                                type: boolean
                                description: >-
                                  When true, overage for this feature is not
                                  posted to Stripe. Usage tracking and balance
                                  resets still behave normally.
                          description: >-
                            List of overage spend limits per feature (caps
                            overage spend).
                        usage_limits:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: The feature this usage limit applies to.
                              enabled:
                                type: boolean
                                default: true
                                description: Whether this usage limit is enabled.
                              limit:
                                type: number
                                minimum: 0
                                description: Maximum units allowed per interval.
                              interval:
                                enum:
                                  - day
                                  - week
                                  - month
                                  - year
                                type: string
                                description: >-
                                  Interval for the cap, aligned to the
                                  customer's billing cycle.
                              filter:
                                type: object
                                properties:
                                  properties:
                                    type: object
                                    propertyNames:
                                      type: string
                                      minLength: 1
                                      maxLength: 64
                                    additionalProperties:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                          maxLength: 128
                                        - type: number
                                        - type: boolean
                                required:
                                  - properties
                                description: >-
                                  When set, only usage from events whose
                                  properties match counts toward this cap. Omit
                                  to count all usage of the feature.
                            required:
                              - feature_id
                              - limit
                              - interval
                          description: >-
                            List of hard usage caps per feature (max units per
                            interval).
                        usage_alerts:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: The feature ID this alert applies to.
                              enabled:
                                type: boolean
                                default: true
                                description: Whether this usage alert is enabled.
                              threshold:
                                type: number
                                minimum: 0
                                description: >-
                                  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:
                                enum:
                                  - usage
                                  - usage_percentage
                                  - remaining
                                  - remaining_percentage
                                type: string
                                description: >-
                                  Whether the threshold is an absolute count or
                                  a percentage of the usage allowance or
                                  remaining balance.
                              name:
                                type: string
                                description: >-
                                  Optional user-defined label to distinguish
                                  multiple alerts on the same feature.
                            required:
                              - threshold
                              - threshold_type
                          description: List of usage alert configurations per feature.
                        overage_allowed:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: >-
                                  The feature ID this overage allowed control
                                  applies to.
                              enabled:
                                type: boolean
                                default: false
                                description: Whether overage is allowed for this feature.
                            required:
                              - feature_id
                          description: >-
                            List of overage allowed controls per feature. When
                            enabled, usage can exceed balance.
                      description: >-
                        Override the plan's billing controls (auto top-ups,
                        spend limits, usage limits, usage alerts, overage
                        allowed) for this customer.
                    upsert_licenses:
                      type: array
                      items:
                        type: object
                        properties:
                          license_plan_id:
                            type: string
                          included:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          prepaid_only:
                            type: boolean
                          customize:
                            anyOf:
                              - type: object
                                properties:
                                  price:
                                    anyOf:
                                      - type: object
                                        properties:
                                          amount:
                                            type: number
                                            description: Base price amount for the plan.
                                          interval:
                                            enum:
                                              - one_off
                                              - week
                                              - month
                                              - quarter
                                              - semi_annual
                                              - year
                                            type: string
                                            description: Billing interval (e.g. 'month', 'year').
                                          interval_count:
                                            type: number
                                            description: >-
                                              Number of intervals per billing cycle.
                                              Defaults to 1.
                                          additional_currencies:
                                            type: array
                                            items:
                                              type: object
                                              properties:
                                                currency:
                                                  type: string
                                                  description: >-
                                                    Three-letter Stripe-supported currency
                                                    code (e.g. 'eur', 'gbp').
                                                amount:
                                                  type: number
                                                  description: >-
                                                    Price amount in this currency. Set
                                                    explicitly per currency, not converted
                                                    from the base amount.
                                              required:
                                                - currency
                                                - amount
                                            description: >-
                                              Base price amounts in additional
                                              currencies. The base 'amount' is in the
                                              org's default currency.
                                        required:
                                          - amount
                                          - interval
                                        title: BasePrice
                                        description: Base price configuration for a plan.
                                      - type: 'null'
                                  add_items:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        feature_id:
                                          type: string
                                          description: The ID of the feature to configure.
                                        included:
                                          type: number
                                          description: >-
                                            Number of free units included. Balance
                                            resets to this each interval for
                                            consumable features.
                                        unlimited:
                                          type: boolean
                                          description: >-
                                            If true, customer has unlimited access
                                            to this feature.
                                        reset:
                                          type: object
                                          properties:
                                            interval:
                                              enum:
                                                - one_off
                                                - minute
                                                - hour
                                                - day
                                                - week
                                                - month
                                                - quarter
                                                - semi_annual
                                                - year
                                              type: string
                                              description: >-
                                                Interval at which balance resets (e.g.
                                                'month', 'year'). For consumable
                                                features only.
                                            interval_count:
                                              type: number
                                              description: >-
                                                Number of intervals between resets.
                                                Defaults to 1.
                                          required:
                                            - interval
                                          description: >-
                                            Reset configuration for consumable
                                            features. Omit for non-consumable
                                            features like seats.
                                        price:
                                          type: object
                                          properties:
                                            amount:
                                              type: number
                                              description: >-
                                                Price per billing_units after included
                                                usage. Either 'amount' or 'tiers' is
                                                required.
                                            additional_currencies:
                                              type: array
                                              items:
                                                type: object
                                                properties:
                                                  currency:
                                                    type: string
                                                    description: >-
                                                      Three-letter Stripe-supported currency
                                                      code (e.g. 'eur', 'gbp').
                                                  amount:
                                                    type: number
                                                    description: >-
                                                      Price amount in this currency. Set
                                                      explicitly per currency, not converted
                                                      from the base amount.
                                                required:
                                                  - currency
                                                  - amount
                                              description: >-
                                                Amounts in additional currencies for
                                                this flat price. The base 'amount' is in
                                                the org's default currency. Only valid
                                                with 'amount', not 'tiers'.
                                            tiers:
                                              type: array
                                              items:
                                                type: object
                                                properties:
                                                  to:
                                                    anyOf:
                                                      - {}
                                                      - {}
                                                  amount:
                                                    type: number
                                                  flat_amount:
                                                    type: number
                                                  additional_currencies:
                                                    type: array
                                                    items: {}
                                                    description: >-
                                                      Per-currency amounts for this tier. Tier
                                                      boundaries ('to') are shared across all
                                                      currencies.
                                              description: >-
                                                Tiered pricing.  Either 'amount' or
                                                'tiers' is required.
                                            tier_behavior:
                                              enum:
                                                - graduated
                                                - volume
                                              type: string
                                            interval:
                                              enum:
                                                - one_off
                                                - week
                                                - month
                                                - quarter
                                                - semi_annual
                                                - year
                                              type: string
                                              description: >-
                                                Billing interval. For consumable
                                                features, should match reset.interval.
                                            interval_count:
                                              type: number
                                              default: 1
                                              description: >-
                                                Number of intervals per billing cycle.
                                                Defaults to 1.
                                            billing_units:
                                              type: number
                                              default: 1
                                              description: >-
                                                Units per price increment. Usage is
                                                rounded UP when billed (e.g.
                                                billing_units=100 means 101 rounds to
                                                200).
                                            billing_method:
                                              enum:
                                                - prepaid
                                                - usage_based
                                              type: string
                                              description: >-
                                                'prepaid' for upfront payment (seats),
                                                'usage_based' for pay-as-you-go.
                                            max_purchase:
                                              anyOf:
                                                - type: number
                                                - type: 'null'
                                              description: >-
                                                Max units purchasable beyond included.
                                                E.g. included=100, max_purchase=300
                                                allows 400 total. Null for no limit.
                                          required:
                                            - interval
                                            - billing_method
                                          description: >-
                                            Pricing for usage beyond included units.
                                            Omit for free features.
                                        proration:
                                          type: object
                                          properties:
                                            on_increase:
                                              enum:
                                                - bill_immediately
                                                - prorate_immediately
                                                - prorate_next_cycle
                                                - bill_next_cycle
                                              type: string
                                              description: >-
                                                Billing behavior when quantity increases
                                                mid-cycle.
                                            on_decrease:
                                              enum:
                                                - prorate
                                                - prorate_immediately
                                                - prorate_next_cycle
                                                - none
                                                - no_prorations
                                              type: string
                                              description: >-
                                                Credit behavior when quantity decreases
                                                mid-cycle.
                                          required:
                                            - on_increase
                                            - on_decrease
                                          description: >-
                                            Proration settings for prepaid features.
                                            Controls mid-cycle quantity change
                                            billing.
                                        rollover:
                                          type: object
                                          properties:
                                            max:
                                              type: number
                                              description: >-
                                                Max rollover units. Omit for unlimited
                                                rollover.
                                            max_percentage:
                                              type: number
                                              description: >-
                                                Maximum rollover as a percentage (0-100)
                                                of included + prepaid grant. Mutually
                                                exclusive with max.
                                            expiry_duration_type:
                                              enum:
                                                - month
                                                - forever
                                              type: string
                                              description: When rolled over units expire.
                                            expiry_duration_length:
                                              type: number
                                              description: Number of periods before expiry.
                                          required:
                                            - expiry_duration_type
                                          description: >-
                                            Rollover config for unused units. If
                                            set, unused included units carry over.
                                      required:
                                        - feature_id
                                      title: PlanItem
                                      description: >-
                                        Configuration for a feature item in a
                                        plan, including usage limits, pricing,
                                        and rollover settings.
                                  remove_items:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        feature_id:
                                          type: string
                                          description: Match items linked to this feature.
                                        billing_method:
                                          enum:
                                            - prepaid
                                            - usage_based
                                          type: string
                                          description: >-
                                            Match items with this billing method
                                            (prepaid or usage_based).
                                        interval:
                                          anyOf:
                                            - enum:
                                                - one_off
                                                - week
                                                - month
                                                - quarter
                                                - semi_annual
                                                - year
                                              type: string
                                            - enum:
                                                - one_off
                                                - minute
                                                - hour
                                                - day
                                                - week
                                                - month
                                                - quarter
                                                - semi_annual
                                                - year
                                              type: string
                                          description: >-
                                            Match items with this interval. Accepts
                                            either a BillingInterval (price-side) or
                                            a ResetInterval (reset-side, includes
                                            day/hour/minute) so price-less items
                                            keyed by reset.interval can be
                                            disambiguated.
                                        interval_count:
                                          type: integer
                                          minimum: -9007199254740991
                                          maximum: 9007199254740991
                                          exclusiveMinimum: 0
                                          description: >-
                                            Match items with this interval_count.
                                            Disambiguates between items that share
                                            an interval but differ in count.
                                      title: PlanItemFilter
                                      description: >-
                                        Filter for matching plan items. All
                                        provided fields must match (AND).
                              - type: 'null'
                          metadata:
                            type: object
                            propertyNames:
                              type: string
                            additionalProperties: {}
                        required:
                          - license_plan_id
                      description: >-
                        License links to add or override for this customer,
                        keyed by license_plan_id. Omitted fields inherit the
                        plan catalog link (included defaults to 1 when the
                        license is not in the catalog). A bare entry restores
                        the license to pure catalog inheritance.
                  description: >-
                    Customize the plan to attach. Can override the price, items,
                    licenses, free trial, or a combination.
                invoice_mode:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                      description: >-
                        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:
                      type: boolean
                      default: false
                      description: >-
                        If true, enables the plan immediately even though the
                        invoice is not paid yet.
                    finalize:
                      type: boolean
                      default: true
                      description: >-
                        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:
                      type: string
                      description: >-
                        ID of an invoice template (configured in billing
                        settings) whose footer (e.g. bank details) is applied to
                        the invoice.
                    net_terms_days:
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                      exclusiveMinimum: 0
                      description: >-
                        Number of days the customer has to pay the invoice
                        before it is due (Stripe days_until_due).
                  required:
                    - enabled
                  description: >-
                    Invoice mode creates a draft or open invoice and sends it to
                    the customer, instead of charging their card immediately.
                    This uses Stripe's send_invoice collection method.
                proration_behavior:
                  enum:
                    - prorate_immediately
                    - none
                  type: string
                  description: >-
                    How to handle proration when updating an existing
                    subscription. 'prorate_immediately' charges/credits prorated
                    amounts now, 'none' skips creating any charges.
                redirect_mode:
                  enum:
                    - always
                    - if_required
                    - never
                  type: string
                  description: >-
                    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.
                  default: if_required
                subscription_id:
                  type: string
                  description: >-
                    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.
                discounts:
                  type: array
                  items:
                    type: object
                    properties:
                      reward_id:
                        type: string
                        description: The ID of the reward to apply as a discount.
                      promotion_code:
                        type: string
                        description: The promotion code to apply as a discount.
                    title: AttachDiscount
                    description: >-
                      A discount to apply. Can be either a reward ID or a
                      promotion code.
                  description: >-
                    List of discounts to apply. Each discount can be an Autumn
                    reward ID, Stripe coupon ID, or Stripe promotion code.
                success_url:
                  type: string
                  description: URL to redirect to after successful checkout.
                new_billing_subscription:
                  type: boolean
                  description: >-
                    Only applicable when the customer has an existing Stripe
                    subscription. If true, creates a new separate subscription
                    instead of merging into the existing one.
                billing_cycle_anchor:
                  const: now
                  description: Reset the billing cycle anchor immediately with 'now'.
                plan_schedule:
                  enum:
                    - immediate
                    - end_of_cycle
                  type: string
                  description: >-
                    When the plan change should take effect. 'immediate' applies
                    now, 'end_of_cycle' schedules for the end of the current
                    billing cycle. By default, upgrades are immediate and
                    downgrades are scheduled.
                starts_at:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                  description: >-
                    Unix timestamp in milliseconds for when the attached plan
                    should start. Future dates create a scheduled subscription.
                ends_at:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                  description: >-
                    Unix timestamp in milliseconds for when the attached plan
                    should end.
                checkout_session_params:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                  description: >-
                    Additional parameters to pass into the creation of the
                    Stripe checkout session.
                long_lived_checkout:
                  type: boolean
                  description: >-
                    If true, returns an Autumn-hosted checkout link that can
                    create a fresh Stripe checkout session when opened.
                custom_line_items:
                  type: array
                  items:
                    type: object
                    properties:
                      amount:
                        type: number
                        description: >-
                          Amount in dollars for this line item (e.g. 10.50). Can
                          be negative for credits.
                      description:
                        type: string
                        description: Description for the line item.
                    required:
                      - amount
                      - description
                  description: >-
                    Custom line items that override the auto-generated proration
                    invoice. Only valid for immediate plan changes (eg. upgrades
                    or one off plans).
                processor_subscription_id:
                  type: string
                  description: >-
                    The processor subscription ID to link. Use this to attach an
                    existing Stripe subscription instead of creating a new one.
                carry_over_balances:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                      description: Whether to carry over balances from the previous plan.
                    feature_ids:
                      type: array
                      items:
                        type: string
                      description: >-
                        The IDs of the features to carry over balances from. If
                        left undefined, all features will be carried over.
                  required:
                    - enabled
                  description: Whether to carry over balances from the previous plan.
                carry_over_usages:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                      description: Whether to carry over usages from the previous plan.
                    feature_ids:
                      type: array
                      items:
                        type: string
                      description: >-
                        The IDs of the features to carry over usages for. If
                        left undefined, all consumable features will be carried
                        over.
                  required:
                    - enabled
                  description: Whether to carry over usages from the previous plan.
                license_quantities:
                  type: array
                  items:
                    type: object
                    properties:
                      license_plan_id:
                        type: string
                        description: The license plan to set seat quantity for.
                      quantity:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                        description: >-
                          Total seats for the license, inclusive of the plan's
                          included amount — seats beyond it are paid.
                    required:
                      - license_plan_id
                      - quantity
                  description: >-
                    Seat quantities for the plan's licenses, keyed by license
                    plan.
                metadata:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: string
                  description: >-
                    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_changes:
                  type: boolean
                  description: If true, skips any billing changes for the attach operation.
                enable_plan_immediately:
                  type: boolean
                  description: >-
                    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_id:
                  type: string
                  description: >-
                    Stripe tax rate ID (txr_...) to apply as the default tax
                    rate on the created subscription, invoice, or checkout
                    session line items.
                currency:
                  type: string
                  description: >-
                    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.
              required:
                - customer_id
                - plan_id
              title: AttachParams
              examples:
                - customer_id: cus_123
                  plan_id: pro_plan
            example:
              customer_id: cus_123
              plan_id: pro_plan
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_id:
                    type: string
                    description: The ID of the customer.
                  entity_id:
                    type: string
                    description: >-
                      The ID of the entity, if the plan was attached to an
                      entity.
                  invoice:
                    type: object
                    properties:
                      status:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: >-
                          The status of the invoice (e.g., 'paid', 'open',
                          'draft').
                      stripe_id:
                        type: string
                        description: The Stripe invoice ID.
                      total:
                        type: number
                        description: The total amount of the invoice in cents.
                      currency:
                        type: string
                        description: The three-letter ISO currency code (e.g., 'usd').
                      hosted_invoice_url:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: >-
                          URL to the hosted invoice page where the customer can
                          view and pay the invoice.
                    required:
                      - status
                      - stripe_id
                      - total
                      - currency
                      - hosted_invoice_url
                    description: >-
                      Invoice details if an invoice was created. Only present
                      when a charge was made.
                  payment_url:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      URL to redirect the customer to complete payment. Null if
                      no payment action is required.
                  required_action:
                    type: object
                    properties:
                      code:
                        enum:
                          - 3ds_required
                          - payment_method_required
                          - payment_failed
                          - payment_processing
                        type: string
                        description: The type of action required to complete the payment.
                      reason:
                        type: string
                        description: >-
                          A human-readable explanation of why this action is
                          required.
                    required:
                      - code
                      - reason
                    description: >-
                      Details about any action required to complete the payment.
                      Present when the payment could not be processed
                      automatically.
                required:
                  - customer_id
                  - payment_url
                examples:
                  - customer_id: cus_123
                    payment_url: https://checkout.stripe.com/...
              example:
                customer_id: cus_123
                payment_url: https://checkout.stripe.com/...
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.billing.attach({
              customerId: "cus_123",
              planId: "pro_plan",
            });
        - lang: python
          label: Python (SDK)
          source: |-
            from autumn_sdk import Autumn

            autumn = Autumn(secret_key="am_sk_test...")

            res = autumn.billing.attach(
                customer_id="cus_123",
                plan_id="pro_plan",
                redirect_mode="if_required",
            )
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````