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

# POST /v1/billing.setup_payment

`POST /v1/billing.setup_payment`

Create a payment setup session for a customer to add or update their payment method.

## Headers

- `x-api-version` string, required

## Request body

- object
  - `customer_id` string, required — The ID of the customer to attach the plan to.
  - `entity_id` string — The ID of the entity to attach the plan to.
  - `plan_id` string — If specified, the plan will be attached to the customer after setup.
  - `feature_quantities` 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.
    - `feature_id` string, required — The ID of the feature to set quantity for.
    - `quantity` number — The quantity of the feature.
    - `adjustable` boolean — Whether the customer can adjust the quantity.
  - `version` number — The version of the plan to attach.
  - `customize` object — Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.
    - `price` object, nullable — Base price configuration for a plan.
      - `amount` number, required — Base price amount for the plan.
      - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval (e.g. 'month', 'year').
      - `interval_count` number — Number of intervals per billing cycle. Defaults to 1.
      - `additional_currencies` object[] — Base price amounts in additional currencies. The base 'amount' is in the org's default currency.
        - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
        - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount.
    - `items` object[] — Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add_items / remove_items / deprecated update_items.
      - `feature_id` string, required — The ID of the feature to configure.
      - `included` number — Number of free units included. Balance resets to this each interval for consumable features.
      - `unlimited` boolean — If true, customer has unlimited access to this feature.
      - `reset` object — Reset configuration for consumable features. Omit for non-consumable features like seats.
        - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
        - `interval_count` number — Number of intervals between resets. Defaults to 1.
      - `price` object — Pricing for usage beyond included units. Omit for free features.
        - `amount` number — Price per billing_units after included usage. Either 'amount' or 'tiers' is required.
        - `additional_currencies` object[] — Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.
          - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
          - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount.
        - `tiers` object[] — Tiered pricing. Either 'amount' or 'tiers' is required.
          - `to` union, required
            - number
            - 'inf'
          - `amount` number
          - `flat_amount` number
          - `additional_currencies` object[] — Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
            - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
            - `amount` number — Per-unit amount for this tier in this currency.
            - `flat_amount` number — Flat amount for this tier in this currency, if the tier uses one.
        - `tier_behavior` 'graduated' | 'volume'
        - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval. For consumable features, should match reset.interval.
        - `interval_count` number — Number of intervals per billing cycle. Defaults to 1.
        - `billing_units` number — Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
        - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
        - `max_purchase` number, nullable — Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
      - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing.
        - `on_increase` 'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle', required — Billing behavior when quantity increases mid-cycle.
        - `on_decrease` 'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations', required — Credit behavior when quantity decreases mid-cycle.
      - `rollover` object — Rollover config for unused units. If set, unused included units carry over.
        - `max` number — Max rollover units. Omit for unlimited rollover.
        - `max_percentage` number — Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
        - `expiry_duration_type` 'month' | 'forever', required — When rolled over units expire.
        - `expiry_duration_length` number — Number of periods before expiry.
    - `add_items` object[] — Items to add to the plan.
      - `feature_id` string, required — The ID of the feature to configure.
      - `included` number — Number of free units included. Balance resets to this each interval for consumable features.
      - `unlimited` boolean — If true, customer has unlimited access to this feature.
      - `reset` object — Reset configuration for consumable features. Omit for non-consumable features like seats.
        - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
        - `interval_count` number — Number of intervals between resets. Defaults to 1.
      - `price` object — Pricing for usage beyond included units. Omit for free features.
        - `amount` number — Price per billing_units after included usage. Either 'amount' or 'tiers' is required.
        - `additional_currencies` object[] — Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.
          - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
          - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount.
        - `tiers` object[] — Tiered pricing. Either 'amount' or 'tiers' is required.
          - `to` union, required
            - number
            - 'inf'
          - `amount` number
          - `flat_amount` number
          - `additional_currencies` object[] — Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
            - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
            - `amount` number — Per-unit amount for this tier in this currency.
            - `flat_amount` number — Flat amount for this tier in this currency, if the tier uses one.
        - `tier_behavior` 'graduated' | 'volume'
        - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval. For consumable features, should match reset.interval.
        - `interval_count` number — Number of intervals per billing cycle. Defaults to 1.
        - `billing_units` number — Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
        - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
        - `max_purchase` number, nullable — Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
      - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing.
        - `on_increase` 'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle', required — Billing behavior when quantity increases mid-cycle.
        - `on_decrease` 'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations', required — Credit behavior when quantity decreases mid-cycle.
      - `rollover` object — Rollover config for unused units. If set, unused included units carry over.
        - `max` number — Max rollover units. Omit for unlimited rollover.
        - `max_percentage` number — Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
        - `expiry_duration_type` 'month' | 'forever', required — When rolled over units expire.
        - `expiry_duration_length` number — Number of periods before expiry.
    - `remove_items` object[] — Filters selecting items to remove from the plan.
      - `feature_id` string — Match items linked to this feature.
      - `billing_method` 'prepaid' | 'usage_based' — Match items with this billing method (prepaid or usage_based).
      - `interval` union — 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.
        - 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
        - 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
      - `interval_count` integer — Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
    - `free_trial` object, nullable — Free trial configuration for a plan.
      - `duration_length` number, required — Number of duration_type periods the trial lasts.
      - `duration_type` 'day' | 'month' | 'year' — Unit of time for the trial ('day', 'month', 'year').
      - `card_required` boolean — If true, payment method required to start trial. Customer is charged after trial ends.
      - `on_end` 'bill' | 'revert' — Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
    - `billing_controls` object — Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
      - `auto_topups` object[] — List of auto top-up configurations per feature.
        - `feature_id` string, required — The ID of the feature (credit balance) to auto top-up.
        - `enabled` boolean — Whether auto top-up is enabled.
        - `threshold` number, required — When the balance drops below this threshold, an auto top-up will be purchased.
        - `quantity` number, required — Amount of credits to add per auto top-up.
        - `purchase_limit` object — Optional rate limit to cap how often auto top-ups occur. Pass count to set the current window's consumed top-ups.
          - `interval` 'hour' | 'day' | 'week' | 'month', required — The time interval for the purchase limit window.
          - `interval_count` number — Number of intervals in the purchase limit window.
          - `limit` number, required — Maximum number of auto top-ups allowed within the interval.
          - `count` number — Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.
        - `invoice_mode` boolean — When true, auto top-up creates a send_invoice invoice instead of auto-charging.
      - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend).
        - `feature_id` string — Optional feature ID this spend limit applies to.
        - `enabled` boolean — Whether the overage spend limit is enabled.
        - `limit_type` 'absolute' | 'usage_percentage' — How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
        - `overage_limit` number — Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
        - `skip_overage_billing` boolean — When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
      - `usage_limits` object[] — List of hard usage caps per feature (max units per interval).
        - `feature_id` string, required — The feature this usage limit applies to.
        - `enabled` boolean — Whether this usage limit is enabled.
        - `limit` number, required — Maximum units allowed per interval.
        - `interval` 'day' | 'week' | 'month' | 'year', required — Interval for the cap, aligned to the customer's billing cycle.
        - `filter` object — When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.
          - `properties` object, required
      - `usage_alerts` object[] — List of usage alert configurations per feature.
        - `feature_id` string — The feature ID this alert applies to.
        - `enabled` boolean — Whether this usage alert is enabled.
        - `threshold` number, required — The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
        - `threshold_type` 'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage', required — Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
        - `name` string — Optional user-defined label to distinguish multiple alerts on the same feature.
      - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance.
        - `feature_id` string, required — The feature ID this overage allowed control applies to.
        - `enabled` boolean — Whether overage is allowed for this feature.
    - `upsert_licenses` 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.
      - `license_plan_id` string, required
      - `included` integer
      - `prepaid_only` boolean
      - `customize` object, nullable
        - `price` object, nullable — Base price configuration for a plan.
          - `amount` number, required — Base price amount for the plan.
          - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval (e.g. 'month', 'year').
          - `interval_count` number — Number of intervals per billing cycle. Defaults to 1.
          - `additional_currencies` object[] — Base price amounts in additional currencies. The base 'amount' is in the org's default currency.
            - `currency` string, required — Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
            - `amount` number, required — Price amount in this currency. Set explicitly per currency, not converted from the base amount.
        - `add_items` object[]
          - `feature_id` string, required — The ID of the feature to configure.
          - `included` number — Number of free units included. Balance resets to this each interval for consumable features.
          - `unlimited` boolean — If true, customer has unlimited access to this feature.
          - `reset` object — Reset configuration for consumable features. Omit for non-consumable features like seats.
            - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.
            - `interval_count` number — Number of intervals between resets. Defaults to 1.
          - `price` object — Pricing for usage beyond included units. Omit for free features.
            - `amount` number — Price per billing_units after included usage. Either 'amount' or 'tiers' is required.
            - `additional_currencies` object[] — Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.
              - …
            - `tiers` object[] — Tiered pricing. Either 'amount' or 'tiers' is required.
              - …
            - `tier_behavior` 'graduated' | 'volume'
            - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval. For consumable features, should match reset.interval.
            - `interval_count` number — Number of intervals per billing cycle. Defaults to 1.
            - `billing_units` number — Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
            - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for upfront payment (seats), 'usage_based' for pay-as-you-go.
            - `max_purchase` number, nullable — Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
          - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing.
            - `on_increase` 'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle', required — Billing behavior when quantity increases mid-cycle.
            - `on_decrease` 'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations', required — Credit behavior when quantity decreases mid-cycle.
          - `rollover` object — Rollover config for unused units. If set, unused included units carry over.
            - `max` number — Max rollover units. Omit for unlimited rollover.
            - `max_percentage` number — Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
            - `expiry_duration_type` 'month' | 'forever', required — When rolled over units expire.
            - `expiry_duration_length` number — Number of periods before expiry.
        - `remove_items` object[]
          - `feature_id` string — Match items linked to this feature.
          - `billing_method` 'prepaid' | 'usage_based' — Match items with this billing method (prepaid or usage_based).
          - `interval` union — 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.
            - 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
            - 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
          - `interval_count` integer — Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
      - `metadata` object
  - `proration_behavior` 'prorate_immediately' | 'none' — How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
  - `subscription_id` 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.
  - `discounts` object[] — List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
    - `reward_id` string — The ID of the reward to apply as a discount.
    - `promotion_code` string — The promotion code to apply as a discount.
  - `success_url` string — URL to redirect to after successful checkout.
  - `billing_cycle_anchor` 'now' — Reset the billing cycle anchor immediately with 'now'.
  - `starts_at` integer — Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription.
  - `ends_at` integer — Unix timestamp in milliseconds for when the attached plan should end.
  - `checkout_session_params` object — Additional parameters to pass into the creation of the Stripe checkout session.
  - `custom_line_items` object[] — Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans).
    - `amount` number, required — Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
    - `description` string, required — Description for the line item.
  - `processor_subscription_id` string — The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.
  - `carry_over_balances` object — Whether to carry over balances from the previous plan.
    - `enabled` boolean, required — Whether to carry over balances from the previous plan.
    - `feature_ids` string[] — The IDs of the features to carry over balances from. If left undefined, all features will be carried over.
  - `carry_over_usages` object — Whether to carry over usages from the previous plan.
    - `enabled` boolean, required — Whether to carry over usages from the previous plan.
    - `feature_ids` string[] — The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.
  - `license_quantities` object[] — Seat quantities for the plan's licenses, keyed by license plan.
    - `license_plan_id` string, required — The license plan to set seat quantity for.
    - `quantity` integer, required — Total seats for the license, inclusive of the plan's included amount — seats beyond it are paid.
  - `metadata` object — 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` boolean — If true, skips any billing changes for the attach operation.
  - `enable_plan_immediately` 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.
  - `tax_rate_id` string — Stripe tax rate ID (txr_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items.
  - `currency` 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.

## Response `200`

OK

- object
  - `customer_id` string, required — The ID of the customer
  - `entity_id` string — The ID of the entity the plan (if specified) will be attached to after setup.
  - `url` string, required — URL to redirect the customer to setup their payment.

---

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