--- title: "POST /v1/billing.preview_multi_attach" method: POST path: "/v1/billing.preview_multi_attach" tags: ["billing"] --- # POST /v1/billing.preview_multi_attach `POST /v1/billing.preview_multi_attach` Previews the billing changes that would occur when attaching multiple plans, without actually making any changes. Use this endpoint to show customers what they will be charged before confirming a multi-plan subscription. ## Headers - `x-api-version` string, required ## Request body - object - `customer_id` string, required — The ID of the customer to attach the plans to. - `entity_id` string — The ID of the entity to attach the plans to. - `plans` object[], required — The list of plans to attach to the customer. - `plan_id` string, required — The ID of the plan to attach. - `customize` object — Customize the plan to attach. Can override the price, items, or licenses. - `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. - `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 - … - `amount` number - `flat_amount` number - `additional_currencies` object[] — Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies. - … - `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. - `feature_quantities` object[] — If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. - `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. - `subscription_id` string — A unique ID to identify this subscription. Useful when attaching the same plan multiple times. - `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. - `currency` string — Currency to bill this multi-attach in (e.g. usd, eur). Must match the customer's currency if they are already locked to one, and every plan must offer a paid price in it. Defaults to the customer's currency, then the org default. - `invoice_mode` object — Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. - `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). - `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. - `checkout_session_params` object — Additional parameters to pass into the creation of the Stripe checkout session. - `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. - `new_billing_subscription` boolean — Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one. - `enable_plan_immediately` boolean — If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout. - `customer_data` CustomerData — Customer details to set when creating a customer - `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 - `create_in_stripe` boolean — Whether to create the customer in Stripe - `auto_enable_plan_id` string — The ID of the free plan to auto-enable for the customer - `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. - `entity_data` object - `feature_id` string, required — The feature ID that this entity is associated with - `name` string — Name of the entity - `billing_controls` object — Billing controls for the entity. - `spend_limits` object[] — List of spend limits per feature. Each entry caps overage (overage_limit) and/or per-interval usage (usage_limit). - `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 for this entity. An entity entry overrides the customer's for that feature. - `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. ## Response `200` OK - object - `customer_id` string, required — The ID of the customer. - `line_items` object[], required - `display_name` string, required — The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. - `description` string, required — A detailed description of the line item. - `subtotal` number, required — The amount in cents before discounts and tax for this line item. - `total` number, required — The final amount in cents after discounts and tax for this line item. - `discounts` object[] — List of discounts applied to this line item. - `amount_off` number, required - `percent_off` number - `reward_id` string - `reward_name` string - `plan_id` string, required — The ID of the plan that this line item belongs to. - `feature_id` string, nullable, required — The ID of the feature that this line item belongs to. - `period` object — The period of time that this line item is being charged for. - `start` number, required — The start of the period in milliseconds since the Unix epoch. - `end` number, required — The end of the period in milliseconds since the Unix epoch. - `quantity` number, required — The quantity of the line item. - `subtotal` number, required — The total amount in cents before discounts and tax for the current billing period. - `total` number, required — The final amount in cents after discounts and tax for the current billing period. - `currency` string, required — The three-letter ISO currency code (e.g., 'usd'). - `next_cycle` object — Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles. - `starts_at` number, required — Unix timestamp (milliseconds) when the next billing cycle starts. - `subtotal` number, required — The total amount in cents before discounts and tax for the next cycle. - `total` number, required — The final amount in cents after discounts and tax for the next cycle. - `line_items` object[], required — List of line items for the next billing cycle. - `display_name` string, required — The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. - `description` string, required — A detailed description of the line item. - `subtotal` number, required — The amount in cents before discounts and tax for this line item. - `total` number, required — The final amount in cents after discounts and tax for this line item. - `discounts` object[] — List of discounts applied to this line item. - `amount_off` number, required - `percent_off` number - `reward_id` string - `reward_name` string - `plan_id` string, required — The ID of the plan that this line item belongs to. - `feature_id` string, nullable, required — The ID of the feature that this line item belongs to. - `period` object — The period of time that this line item is being charged for. - `start` number, required — The start of the period in milliseconds since the Unix epoch. - `end` number, required — The end of the period in milliseconds since the Unix epoch. - `quantity` number, required — The quantity of the line item. - `usage_line_items` object[], required — List of line items for usage-based features in the next cycle. - `display_name` string, required — The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name. - `plan_id` string, required — The ID of the plan that this line item belongs to. - `feature_id` string, nullable, required — The ID of the feature that this line item belongs to. - `period` object — The period of time that this line item is being charged for. - `start` number, required — The start of the period in milliseconds since the Unix epoch. - `end` number, required — The end of the period in milliseconds since the Unix epoch. - `expand` string[] — Expand the response with additional data. - `incoming` object[], required — Products or subscription changes being added or updated. - `plan_id` string, required — The ID of the plan affected by this preview change. - `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. - `feature_quantities` object[], required — The feature quantity selections associated with this plan change. - `feature_id` string, required — The ID of the adjustable feature included in this change. - `quantity` number, required — The quantity that will apply for this feature in the change. - `effective_at` number, nullable, required — When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately. - `canceled_at` number, nullable, required — When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled. - `expires_at` number, nullable, required — When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire. - `outgoing` object[], required — Products or subscription changes being removed or ended. - `plan_id` string, required — The ID of the plan affected by this preview change. - `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. - `feature_quantities` object[], required — The feature quantity selections associated with this plan change. - `feature_id` string, required — The ID of the adjustable feature included in this change. - `quantity` number, required — The quantity that will apply for this feature in the change. - `effective_at` number, nullable, required — When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately. - `canceled_at` number, nullable, required — When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled. - `expires_at` number, nullable, required — When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire. - `redirect_to_checkout` boolean, required — Whether the customer will be redirected to a checkout page if attach is called. - `checkout_type` 'stripe_checkout' | 'autumn_checkout', nullable, required — The type of checkout that will be used if the customer is redirected to a checkout page. - `tax` object — Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location. - `total` number, required — Total tax amount in major currency units. - `amount_inclusive` number, required — Tax included in line item subtotals. - `amount_exclusive` number, required — Tax added on top of subtotals. - `currency` string, required — Three-letter currency code. - `status` 'complete' | 'incomplete', required — Calculation status ('complete' when Stripe Tax succeeds or 'incomplete' when Stripe Tax returned 0 or errored). - `invoice_credits` object — Stripe customer invoice credits preview. - `balance` number, required — Stripe customer credit balance available, expressed as a positive number in major currency units. - `currency` string, required — Three-letter currency code. --- [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)