---
title: "Setup Payment"
openapi: "openapi POST /v1/billing.setup_payment"
---

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

### Body Parameters

<DynamicParamField body="customer_id" type="string" required>
  The ID of the customer to attach the 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">
  If specified, the plan will be attached to the customer after setup.
</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, 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>

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

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

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

              </Expandable>
            </DynamicParamField>

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

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

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

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

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

            <DynamicParamField body="max_purchase" type="number | 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="tiers" type="object[]">
              Tiered pricing. Either 'amount' or 'tiers' is required.
              <Expandable title="properties">
                <DynamicParamField body="to" type="number" required />

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

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

              </Expandable>
            </DynamicParamField>

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

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

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

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

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

            <DynamicParamField body="max_purchase" type="number | 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>

  </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="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="billing_cycle_anchor" type="any">
  Reset the billing cycle anchor immediately with 'now'.
</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="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="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>


### Response

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

<DynamicResponseField name="entity_id" type="string">
  The ID of the entity the plan (if specified) will be attached to after setup.
</DynamicResponseField>

<DynamicResponseField name="url" type="string">
  URL to redirect the customer to setup their payment.
</DynamicResponseField>


<ResponseExample>
```json 200
{
  "customer_id": "cus_123",
  "url": "https://checkout.stripe.com/..."
}
```
</ResponseExample>