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

# POST /v1/billing.update

`POST /v1/billing.update`

Updates an existing subscription. Use to modify feature quantities, cancel, or change plan configuration.

Use this endpoint to update prepaid quantities, cancel a subscription (immediately or at end of cycle), or modify subscription settings.

## 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 — The ID of the plan to update. Optional if subscription_id is provided, or if the customer has only one product.
  - `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
  - `invoice_mode` 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.
    - `enabled` boolean, required — When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
    - `enable_plan_immediately` boolean — If true, enables the plan immediately even though the invoice is not paid yet.
    - `finalize` boolean — If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
    - `invoice_template_id` string — ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
    - `net_terms_days` integer — Number of days the customer has to pay the invoice before it is due (Stripe days_until_due).
  - `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.
  - `redirect_mode` 'always' | 'if_required' | 'never' — Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects.
  - `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.
  - `cancel_action` 'cancel_immediately' | 'cancel_end_of_cycle' | 'uncancel' — Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.
  - `billing_cycle_anchor` 'now' — Reset the billing cycle anchor immediately with 'now'
  - `no_billing_changes` boolean — If true, the subscription is updated internally without applying billing changes in Stripe.
  - `refund_last_payment` 'prorated' | 'full' — Controls how the last payment is refunded on immediate cancellation. 'prorated' refunds the unused portion, 'full' refunds the entire last payment.
  - `recalculate_balances` object — Controls whether balances should be recalculated during the subscription update.
    - `enabled` boolean, required — If true, recalculates balances during the subscription update. Only applicable when updating feature quantities.
  - `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[] — Total seat quantities (inclusive of the license's included count) per license plan offered by this plan. Licenses not listed keep their current paid quantity.
    - `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.

## Response `200`

OK

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

---

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