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

# POST /v1/customers.update

`POST /v1/customers.update`

Updates an existing customer by ID.

## Headers

- `x-api-version` string, required

## Request body

- object
  - `customer_id` string, required — ID of the customer to update
  - `name` string, nullable — Customer's name
  - `email` string, email, nullable — Customer's email address
  - `fingerprint` string, nullable — Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
  - `metadata` object, nullable — Additional metadata for the customer
  - `stripe_id` string, nullable — Stripe customer ID if you already have one
  - `send_email_receipts` boolean — Whether to send email receipts to this customer
  - `currency` string, nullable — Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.
  - `billing_controls` object — Billing controls for the customer (auto top-ups, etc.)
    - `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.
  - `config` object — Miscellaneous configurations for the customer.
    - `disable_pooled_balance` boolean — Whether to disable the shared customer-level pool for entities.
    - `disable_overage_billing` boolean — Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable_overage_billing setting.
  - `new_customer_id` string — Your unique identifier for the customer

## Response `200`

OK

- object
  - `id` string, nullable, required — Your unique identifier for the customer.
  - `name` string, nullable, required — The name of the customer.
  - `email` string, nullable, required — The email address of the customer.
  - `created_at` number, required — Timestamp of customer creation in milliseconds since epoch.
  - `fingerprint` string, nullable, required — A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
  - `stripe_id` string, nullable, required — Stripe customer ID.
  - `env` 'sandbox' | 'live', required — The environment this customer was created in.
  - `metadata` object, required — The metadata for the customer.
  - `send_email_receipts` boolean, required — Whether to send email receipts to the customer.
  - `billing_controls` object, required — Billing controls for the customer (auto top-ups, etc.)
    - `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` union — Optional rate limit to cap how often auto top-ups occur. Expand billing_controls.auto_topups.purchase_limit for a count of top ups and the next_reset_at.
        - object
          - `interval` 'hour' | 'day' | 'week' | 'month', nullable, required — The time interval for the purchase limit window. Null when no purchase limit is configured.
          - `interval_count` number, nullable, required — Number of intervals in the purchase limit window. Null when no purchase limit is configured.
          - `limit` number, nullable, required — Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured.
          - `count` number, required — Number of auto top-ups already consumed in the current window.
          - `next_reset_at` number, required — Unix ms timestamp when the current purchase window ends and the count resets.
        - object
          - `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.
      - `invoice_mode` boolean — When true, auto top-up creates a send_invoice invoice instead of auto-charging.
      - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
    - `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.
      - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
    - `usage_limits` object[] — List of hard usage caps per feature, with current interval usage.
      - `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` number — Current usage already consumed in the active interval. Response-only; not stored on billing controls.
      - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
    - `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.
      - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
    - `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.
      - `source` 'customer' | 'plan' — Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
  - `subscriptions` object[], required — Active and scheduled recurring plans that this customer has attached.
    - `id` string, required — The unique identifier of this subscription. If a subscription_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
    - `plan` Plan
      - `id` string, required — Unique identifier for the plan.
      - `name` string, required — Display name of the plan.
      - `description` string, nullable, required — Optional description of the plan.
      - `group` string, nullable, required — Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
      - `version` number, required — Version number of the plan. Incremented when plan configuration changes.
      - `add_on` boolean, required — Whether this is an add-on plan that can be attached alongside a main plan.
      - `auto_enable` boolean, required — If true, this plan is automatically attached when a customer is created. Used for free plans.
      - `price` object, nullable, required — Base recurring price for the plan. Null for free plans or usage-only plans.
        - `amount` number, required — Base price amount for the plan.
        - `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.
        - `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.
        - `display` object — Display text for showing this price in pricing pages.
          - `primary_text` string, required — Main display text (e.g. '$10' or '100 messages').
          - `secondary_text` string — Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
      - `items` object[], required — Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
        - `feature_id` string, required — The ID of the feature this item configures.
        - `feature` object — The full feature object if expanded.
          - `id` string, required — The ID of the feature, used to refer to it in other API calls like /track or /check.
          - `name` string, nullable — The name of the feature.
          - `type` 'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system', required — The type of the feature
          - `display` object, nullable — Singular and plural display names for the feature.
            - `singular` string, required — The singular display name for the feature.
            - `plural` string, required — The plural display name for the feature.
          - `credit_schema` object[], nullable — Credit cost schema for credit system features.
            - `metered_feature_id` string, required — The ID of the metered feature (should be a single_use feature).
            - `credit_cost` number, required — The credit cost of the metered feature.
          - `archived` boolean, nullable — Whether or not the feature is archived.
        - `included` number, required — Number of free units included. For consumable features, balance resets to this number each interval.
        - `unlimited` boolean, required — Whether the customer has unlimited access to this feature.
        - `reset` object, nullable, required — Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
          - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
          - `interval_count` number — Number of intervals between resets. Defaults to 1.
        - `price` object, nullable, required — Pricing configuration for usage beyond included units. Null if feature is entirely free.
          - `amount` number — Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
          - `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' (tiered prices carry per-currency amounts on each tier).
            - `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 configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
            - `to` union, required
              - …
            - `amount` number, required
            - `flat_amount` number
            - `additional_currencies` object[]
              - …
          - `tier_behavior` 'graduated' | 'volume'
          - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval for this price. For consumable features, should match reset.interval.
          - `interval_count` number — Number of intervals per billing cycle. Defaults to 1.
          - `billing_units` number, required — Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
          - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
          - `max_purchase` number, nullable, required — Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
        - `display` object — Display text for showing this item in pricing pages.
          - `primary_text` string, required — Main display text (e.g. '$10' or '100 messages').
          - `secondary_text` string — Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
        - `rollover` object — Rollover configuration for unused units. If set, unused included units roll over to the next period.
          - `max` number, nullable, required — Maximum rollover units. Null for unlimited rollover.
          - `max_percentage` number, nullable — 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.
      - `free_trial` object — Free trial configuration. If set, new customers can try this plan before being charged.
        - `duration_length` number, required — Number of duration_type periods the trial lasts.
        - `duration_type` 'day' | 'month' | 'year', required — Unit of time for the trial duration ('day', 'month', 'year').
        - `card_required` boolean, required — Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
        - `on_end` 'bill' | 'revert', nullable — Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
      - `created_at` number, required — Unix timestamp (ms) when the plan was created.
      - `env` 'sandbox' | 'live', required — Environment this plan belongs to ('sandbox' or 'live').
      - `archived` boolean, required — Whether the plan is archived. Archived plans cannot be attached to new customers.
      - `base_variant_id` string, nullable, required — Deprecated. Use variant_details.base_plan_id instead. If this is a variant, the ID of the base plan it was created from.
      - `variant_details` object — Details about how this variant relates to its latest base plan.
        - `base_plan_id` string, required — The ID of the base plan this variant was derived from.
        - `customize` object — The customization that transforms the base plan into this variant.
          - `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.
              - …
          - `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.
              - …
            - `price` object — Pricing for usage beyond included units. Omit for free features.
              - …
            - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing.
              - …
            - `rollover` object — Rollover config for unused units. If set, unused included units carry over.
              - …
          - `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.
              - …
            - `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.
              - …
            - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend).
              - …
            - `usage_limits` object[] — List of hard usage caps per feature (max units per interval).
              - …
            - `usage_alerts` object[] — List of usage alert configurations per feature.
              - …
            - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance.
              - …
      - `config` object, required — Miscellaneous plan-level configuration flags.
        - `ignore_past_due` boolean — If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
      - `billing_controls` object — Plan-level billing controls used as customer defaults.
        - `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.
            - `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.
          - `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.
      - `metadata` object, required — Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
      - `customer_eligibility` object
        - `trial_available` boolean — Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
        - `status` 'active' | 'scheduled' — The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
        - `canceling` boolean — Whether the customer's active instance of this plan is set to cancel.
        - `trialing` boolean — Whether the customer is currently on a free trial of this plan.
        - `attach_action` 'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase', required — The action that would occur if this plan were attached to the customer.
    - `plan_id` string, required — The unique identifier of the subscribed plan.
    - `auto_enable` boolean, required — Whether the plan was automatically enabled for the customer.
    - `add_on` boolean, required — Whether this is an add-on plan rather than a base subscription.
    - `status` 'active' | 'scheduled', required — Current status of the subscription.
    - `past_due` boolean, required — Whether the subscription has overdue payments.
    - `canceled_at` number, nullable, required — Timestamp when the subscription was canceled, or null if not canceled.
    - `expires_at` number, nullable, required — Timestamp when the subscription will expire, or null if no expiry set.
    - `trial_ends_at` number, nullable, required — Timestamp when the trial period ends, or null if not on trial.
    - `started_at` number, required — Timestamp when the subscription started.
    - `current_period_start` number, nullable, required — Start timestamp of the current billing period.
    - `current_period_end` number, nullable, required — End timestamp of the current billing period.
    - `quantity` number, required — Number of units of this subscription (for per-seat plans).
    - `scope` 'customer' | 'entity' — Whether this subscription is attached at the customer level or entity level.
  - `purchases` object[], required — One-time purchases made by the customer.
    - `plan` Plan
      - `id` string, required — Unique identifier for the plan.
      - `name` string, required — Display name of the plan.
      - `description` string, nullable, required — Optional description of the plan.
      - `group` string, nullable, required — Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
      - `version` number, required — Version number of the plan. Incremented when plan configuration changes.
      - `add_on` boolean, required — Whether this is an add-on plan that can be attached alongside a main plan.
      - `auto_enable` boolean, required — If true, this plan is automatically attached when a customer is created. Used for free plans.
      - `price` object, nullable, required — Base recurring price for the plan. Null for free plans or usage-only plans.
        - `amount` number, required — Base price amount for the plan.
        - `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.
        - `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.
        - `display` object — Display text for showing this price in pricing pages.
          - `primary_text` string, required — Main display text (e.g. '$10' or '100 messages').
          - `secondary_text` string — Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
      - `items` object[], required — Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
        - `feature_id` string, required — The ID of the feature this item configures.
        - `feature` object — The full feature object if expanded.
          - `id` string, required — The ID of the feature, used to refer to it in other API calls like /track or /check.
          - `name` string, nullable — The name of the feature.
          - `type` 'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system', required — The type of the feature
          - `display` object, nullable — Singular and plural display names for the feature.
            - `singular` string, required — The singular display name for the feature.
            - `plural` string, required — The plural display name for the feature.
          - `credit_schema` object[], nullable — Credit cost schema for credit system features.
            - `metered_feature_id` string, required — The ID of the metered feature (should be a single_use feature).
            - `credit_cost` number, required — The credit cost of the metered feature.
          - `archived` boolean, nullable — Whether or not the feature is archived.
        - `included` number, required — Number of free units included. For consumable features, balance resets to this number each interval.
        - `unlimited` boolean, required — Whether the customer has unlimited access to this feature.
        - `reset` object, nullable, required — Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
          - `interval` 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.
          - `interval_count` number — Number of intervals between resets. Defaults to 1.
        - `price` object, nullable, required — Pricing configuration for usage beyond included units. Null if feature is entirely free.
          - `amount` number — Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
          - `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' (tiered prices carry per-currency amounts on each tier).
            - `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 configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.
            - `to` union, required
              - …
            - `amount` number, required
            - `flat_amount` number
            - `additional_currencies` object[]
              - …
          - `tier_behavior` 'graduated' | 'volume'
          - `interval` 'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year', required — Billing interval for this price. For consumable features, should match reset.interval.
          - `interval_count` number — Number of intervals per billing cycle. Defaults to 1.
          - `billing_units` number, required — Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
          - `billing_method` 'prepaid' | 'usage_based', required — 'prepaid' for features like seats where customers pay upfront, 'usage_based' for pay-as-you-go after included usage.
          - `max_purchase` number, nullable, required — Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
        - `display` object — Display text for showing this item in pricing pages.
          - `primary_text` string, required — Main display text (e.g. '$10' or '100 messages').
          - `secondary_text` string — Secondary display text (e.g. 'per month' or 'then $0.5 per 100').
        - `rollover` object — Rollover configuration for unused units. If set, unused included units roll over to the next period.
          - `max` number, nullable, required — Maximum rollover units. Null for unlimited rollover.
          - `max_percentage` number, nullable — 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.
      - `free_trial` object — Free trial configuration. If set, new customers can try this plan before being charged.
        - `duration_length` number, required — Number of duration_type periods the trial lasts.
        - `duration_type` 'day' | 'month' | 'year', required — Unit of time for the trial duration ('day', 'month', 'year').
        - `card_required` boolean, required — Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
        - `on_end` 'bill' | 'revert', nullable — Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
      - `created_at` number, required — Unix timestamp (ms) when the plan was created.
      - `env` 'sandbox' | 'live', required — Environment this plan belongs to ('sandbox' or 'live').
      - `archived` boolean, required — Whether the plan is archived. Archived plans cannot be attached to new customers.
      - `base_variant_id` string, nullable, required — Deprecated. Use variant_details.base_plan_id instead. If this is a variant, the ID of the base plan it was created from.
      - `variant_details` object — Details about how this variant relates to its latest base plan.
        - `base_plan_id` string, required — The ID of the base plan this variant was derived from.
        - `customize` object — The customization that transforms the base plan into this variant.
          - `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.
              - …
          - `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.
              - …
            - `price` object — Pricing for usage beyond included units. Omit for free features.
              - …
            - `proration` object — Proration settings for prepaid features. Controls mid-cycle quantity change billing.
              - …
            - `rollover` object — Rollover config for unused units. If set, unused included units carry over.
              - …
          - `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.
              - …
            - `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.
              - …
            - `spend_limits` object[] — List of overage spend limits per feature (caps overage spend).
              - …
            - `usage_limits` object[] — List of hard usage caps per feature (max units per interval).
              - …
            - `usage_alerts` object[] — List of usage alert configurations per feature.
              - …
            - `overage_allowed` object[] — List of overage allowed controls per feature. When enabled, usage can exceed balance.
              - …
      - `config` object, required — Miscellaneous plan-level configuration flags.
        - `ignore_past_due` boolean — If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past_due state.
      - `billing_controls` object — Plan-level billing controls used as customer defaults.
        - `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.
            - `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.
          - `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.
      - `metadata` object, required — Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
      - `customer_eligibility` object
        - `trial_available` boolean — Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
        - `status` 'active' | 'scheduled' — The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.
        - `canceling` boolean — Whether the customer's active instance of this plan is set to cancel.
        - `trialing` boolean — Whether the customer is currently on a free trial of this plan.
        - `attach_action` 'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase', required — The action that would occur if this plan were attached to the customer.
    - `plan_id` string, required — The unique identifier of the purchased plan.
    - `expires_at` number, nullable, required — Timestamp when the purchase expires, or null for lifetime access.
    - `started_at` number, required — Timestamp when the purchase was made.
    - `quantity` number, required — Number of units purchased.
    - `scope` 'customer' | 'entity' — Whether this purchase is attached at the customer level or entity level.
  - `licenses` object[], required — License seat pools granted by the customer's plans, with seat counts.
    - `license_plan_id` string, required — The plan offered as an assignable license.
    - `parent_plan_id` string, required — The plan that offers this license.
    - `license_plan_name` string, required — Display name of the license plan.
    - `granted` number, required — Total seats the customer has for this license, included plus paid.
    - `usage` number, required — Seats currently assigned to entities.
    - `remaining` number, required — Seats still available to assign.
    - `paid_quantity` number, required — Paid seats purchased on top of the plan's included amount.
  - `balances` object, required — Feature balances keyed by feature ID, showing usage limits and remaining amounts.
  - `flags` object, required — Boolean feature flags keyed by feature ID, showing enabled access for on/off features.
  - `config` object — Configuration for the customer.
    - `disable_pooled_balance` boolean — Whether to disable the shared customer-level pool for entities.
    - `disable_overage_billing` boolean — Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable_overage_billing setting.
  - `processors` object — Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.
    - `stripe` object — Stripe processor connection for the customer.
      - `id` string, required — Stripe customer ID.
    - `vercel` object — Vercel processor connection for the customer (public-safe subset).
      - `installation_id` string, required — Vercel marketplace installation ID for this customer.
      - `account_id` string, required — Vercel account ID associated with the installation.
    - `revenuecat` object — RevenueCat processor connection for the customer.
      - `id` string, nullable, required — Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set.

---

[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/versions/29536933c0dc/schema)