> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview Update

> Previews the billing changes that would occur when updating a subscription, without actually making any changes.

Use this endpoint to show customers prorated charges or refunds before confirming subscription modifications.

### Body Parameters

The ID of the customer to attach the plan to.

The ID of the entity to attach the plan to.

The ID of the plan to update. Optional if subscription\_id is provided, or if the customer has only one product.

If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.

**properties**

The ID of the feature to set quantity for.

The quantity of the feature.

Whether the customer can adjust the quantity.

The version of the plan to attach.

Free trial configuration for a plan.

**properties**

Number of duration\_type periods the trial lasts.

Unit of time for the trial ('day', 'month', 'year').

If true, a payment method is required to start the trial and the customer is charged when it ends. Defaults to false.

Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.

Charge today for billing periods that haven't started yet. Only the plan's base price is billed upfront; usage, prepaid quantities and seats keep billing every period.

**properties**

Number of duration\_type periods to bill upfront, counted from the plan's start date. Must be 1 when the plan starts on a future starts\_at. Set either this or until.

Unit of duration\_length ('day', 'week', 'month', 'year'). Defaults to the plan's billing interval.

Unix timestamp in milliseconds to bill upfront until. With a future starts\_at it must be exactly one billing period after starts\_at. Set either this or duration\_length.

The prices to bill upfront. Omit to bill the plan's base price(s) upfront.

**properties**

The plan whose price to bill upfront. Defaults to the plan in the request.

Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.

**properties**

Base price configuration for a plan.

**properties**

Base price amount for the plan, in major currency units (e.g. dollars).

Billing interval (e.g. 'month', 'year').

Number of intervals per billing cycle. Defaults to 1.

Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add\_items / remove\_items / deprecated update\_items.

**properties**

Bills this many feature units when outstanding overage reaches it.

**properties**

The ID of the feature to configure.

Number of free units included. Balance resets to this each interval for consumable features.

If true, customer has unlimited access to this feature.

Whether entity-level grants contribute to a shared customer balance.

Reset configuration for consumable features. Omit for non-consumable features like seats.

**properties**

Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.

Number of intervals between resets. Defaults to 1.

Pricing for usage beyond included units. Omit for free features.

**properties**

Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.

Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Tiered pricing. Either 'amount' or 'tiers' is required.

**properties**

Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Per-unit amount for this tier in this currency.

Flat amount for this tier in this currency, if the tier uses one.

How tiers price usage. 'graduated' (default) charges each unit at the rate of the tier it falls in. 'volume' picks one tier from total usage. On usage-based items it bills only usage past the included amount, at the rate of the tier total usage reaches, plus its flat\_amount. On prepaid items it charges every unit, the included ones too, at that tier's rate plus its flat\_amount.

Billing interval. For usage-based features, should match reset.interval, unless the price has graduated tiers and reset.interval is a whole multiple of it: each invoice then bills only the newly owed usage, at the tier the reset period has reached.

Number of intervals per billing cycle. Defaults to 1.

Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).

'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.

Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.

Proration settings for prepaid features. Controls mid-cycle quantity change billing.

**properties**

Billing behavior when quantity increases mid-cycle.

Credit behavior when quantity decreases mid-cycle.

Rollover config for unused units. If set, unused included units carry over.

**properties**

Max rollover units. Omit for unlimited rollover.

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

When rolled over units expire.

Number of periods before expiry.

Purchased units expire this long after each purchase. One-off prepaid consumable items only.

**properties**

Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

**properties**

For credit system features: merges into the feature's credit\_schema by metered\_feature\_id for customers on this plan. A row with a rate overrides or adds that feature, a row with `excluded: true` removes it, and unlisted features keep the credit system's rate.

**properties**

ID of the metered feature that draws from this credit system.

Number of metered-feature units priced together. Defaults to one when omitted.

Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

**properties**

Event properties this entry applies to. Every key must equal the tracked property, compared as strings.

Multiplies the matched rate. All matching multipliers stack.

Added to the rate after every factor is applied, in credits per billing-unit group.

**properties**

Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.

Credits consumed per billing-unit group within this tier.

Credits consumed per billing-unit group.

Removes this feature from the credit system for customers on this plan. Cannot be combined with a rate.

For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

**properties**

Default percentage markup for customers on this plan. Use -100 to make usage free.

Per-provider markup percentages for customers on this plan.

**properties**

Per-model markup overrides for customers on this plan.

**properties**

Items to add to the plan.

**properties**

Bills this many feature units when outstanding overage reaches it.

**properties**

The ID of the feature to configure.

Number of free units included. Balance resets to this each interval for consumable features.

If true, customer has unlimited access to this feature.

Whether entity-level grants contribute to a shared customer balance.

Reset configuration for consumable features. Omit for non-consumable features like seats.

**properties**

Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.

Number of intervals between resets. Defaults to 1.

Pricing for usage beyond included units. Omit for free features.

**properties**

Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.

Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Tiered pricing. Either 'amount' or 'tiers' is required.

**properties**

Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Per-unit amount for this tier in this currency.

Flat amount for this tier in this currency, if the tier uses one.

How tiers price usage. 'graduated' (default) charges each unit at the rate of the tier it falls in. 'volume' picks one tier from total usage. On usage-based items it bills only usage past the included amount, at the rate of the tier total usage reaches, plus its flat\_amount. On prepaid items it charges every unit, the included ones too, at that tier's rate plus its flat\_amount.

Billing interval. For usage-based features, should match reset.interval, unless the price has graduated tiers and reset.interval is a whole multiple of it: each invoice then bills only the newly owed usage, at the tier the reset period has reached.

Number of intervals per billing cycle. Defaults to 1.

Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).

'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.

Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.

Proration settings for prepaid features. Controls mid-cycle quantity change billing.

**properties**

Billing behavior when quantity increases mid-cycle.

Credit behavior when quantity decreases mid-cycle.

Rollover config for unused units. If set, unused included units carry over.

**properties**

Max rollover units. Omit for unlimited rollover.

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

When rolled over units expire.

Number of periods before expiry.

Purchased units expire this long after each purchase. One-off prepaid consumable items only.

**properties**

Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

**properties**

For credit system features: merges into the feature's credit\_schema by metered\_feature\_id for customers on this plan. A row with a rate overrides or adds that feature, a row with `excluded: true` removes it, and unlisted features keep the credit system's rate.

**properties**

ID of the metered feature that draws from this credit system.

Number of metered-feature units priced together. Defaults to one when omitted.

Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

**properties**

Event properties this entry applies to. Every key must equal the tracked property, compared as strings.

Multiplies the matched rate. All matching multipliers stack.

Added to the rate after every factor is applied, in credits per billing-unit group.

**properties**

Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.

Credits consumed per billing-unit group within this tier.

Credits consumed per billing-unit group.

Removes this feature from the credit system for customers on this plan. Cannot be combined with a rate.

For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

**properties**

Default percentage markup for customers on this plan. Use -100 to make usage free.

Per-provider markup percentages for customers on this plan.

**properties**

Per-model markup overrides for customers on this plan.

**properties**

Filters selecting items to remove from the plan.

**properties**

Match items linked to this feature.

Match items with this billing method (prepaid or usage\_based).

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.

Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.

Match items whose grant equals this included usage. Omitted is a wildcard.

Free trial configuration for a plan.

**properties**

Number of duration\_type periods the trial lasts.

Unit of time for the trial ('day', 'month', 'year').

If true, a payment method is required to start the trial and the customer is charged when it ends. Defaults to false.

Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.

Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.

**properties**

List of auto top-up configurations per feature.

**properties**

The ID of the feature (credit balance) to auto top-up.

Whether auto top-up is enabled.

When the balance drops below this threshold, an auto top-up will be purchased.

Amount of credits to add per auto top-up.

Optional rate limit to cap how often auto top-ups occur. Pass count or amount to set the current window's consumed top-ups or charged amount.

**properties**

What `limit` caps: the number of auto top-ups (`count`, default) or the total amount charged for them, in the customer's currency (`amount`).

The time interval for the purchase limit window.

Number of intervals in the purchase limit window.

Maximum allowed within the interval: a number of auto top-ups when limit\_type is count, or a total charge (e.g. 500 for \$500, pre-tax) when limit\_type is amount.

Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.

Set the amount already charged by auto top-ups in the current window. Omit to leave runtime state unchanged.

When true, auto top-up creates a send\_invoice invoice instead of auto-charging.

List of overage spend limits per feature (caps overage spend).

**properties**

Optional feature ID this spend limit applies to.

Whether the overage spend limit is enabled.

How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.

Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.

When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.

List of hard usage caps per feature (max units per interval).

**properties**

The feature this usage limit applies to.

Whether this usage limit is enabled.

Maximum units allowed per interval.

Interval for the cap, aligned to the customer's billing cycle.

Window alignment. 'billing\_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar.

When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.

**properties**

List of usage alert configurations per feature.

**properties**

The feature ID this alert applies to.

Whether this usage alert is enabled.

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. remaining and remaining\_percentage accept negative values with basis balance, to alert once the balance is overdrawn.

Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.

What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage\_limit: the cap of the usage limit with the same feature and filter.

Only valid with basis usage\_limit. Points the alert at the usage limit carrying the same filter.

**properties**

Optional user-defined label to distinguish multiple alerts on the same feature.

List of overage allowed controls per feature. When enabled, usage can exceed balance.

**properties**

The feature ID this overage allowed control applies to.

Whether overage is allowed for this feature.

License links to add or override for this customer, keyed by license\_plan\_id. Omitted fields inherit the plan catalog link (included defaults to 1 when the license is not in the catalog). A bare entry restores the license to pure catalog inheritance.

**properties**

**properties**

Base price configuration for a plan.

**properties**

Base price amount for the plan, in major currency units (e.g. dollars).

Billing interval (e.g. 'month', 'year').

Number of intervals per billing cycle. Defaults to 1.

Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

**properties**

Bills this many feature units when outstanding overage reaches it.

**properties**

The ID of the feature to configure.

Number of free units included. Balance resets to this each interval for consumable features.

If true, customer has unlimited access to this feature.

Whether entity-level grants contribute to a shared customer balance.

Reset configuration for consumable features. Omit for non-consumable features like seats.

**properties**

Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.

Number of intervals between resets. Defaults to 1.

Pricing for usage beyond included units. Omit for free features.

**properties**

Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.

Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Tiered pricing. Either 'amount' or 'tiers' is required.

**properties**

Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Per-unit amount for this tier in this currency.

Flat amount for this tier in this currency, if the tier uses one.

How tiers price usage. 'graduated' (default) charges each unit at the rate of the tier it falls in. 'volume' picks one tier from total usage. On usage-based items it bills only usage past the included amount, at the rate of the tier total usage reaches, plus its flat\_amount. On prepaid items it charges every unit, the included ones too, at that tier's rate plus its flat\_amount.

Billing interval. For usage-based features, should match reset.interval, unless the price has graduated tiers and reset.interval is a whole multiple of it: each invoice then bills only the newly owed usage, at the tier the reset period has reached.

Number of intervals per billing cycle. Defaults to 1.

Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).

'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.

Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.

Proration settings for prepaid features. Controls mid-cycle quantity change billing.

**properties**

Billing behavior when quantity increases mid-cycle.

Credit behavior when quantity decreases mid-cycle.

Rollover config for unused units. If set, unused included units carry over.

**properties**

Max rollover units. Omit for unlimited rollover.

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

When rolled over units expire.

Number of periods before expiry.

Purchased units expire this long after each purchase. One-off prepaid consumable items only.

**properties**

Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

**properties**

For credit system features: merges into the feature's credit\_schema by metered\_feature\_id for customers on this plan. A row with a rate overrides or adds that feature, a row with `excluded: true` removes it, and unlisted features keep the credit system's rate.

**properties**

ID of the metered feature that draws from this credit system.

Number of metered-feature units priced together. Defaults to one when omitted.

Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

**properties**

Event properties this entry applies to. Every key must equal the tracked property, compared as strings.

Multiplies the matched rate. All matching multipliers stack.

Added to the rate after every factor is applied, in credits per billing-unit group.

**properties**

Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.

Credits consumed per billing-unit group within this tier.

Credits consumed per billing-unit group.

Removes this feature from the credit system for customers on this plan. Cannot be combined with a rate.

For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

**properties**

Default percentage markup for customers on this plan. Use -100 to make usage free.

Per-provider markup percentages for customers on this plan.

**properties**

Per-model markup overrides for customers on this plan.

**properties**

**properties**

Match items linked to this feature.

Match items with this billing method (prepaid or usage\_based).

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.

Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.

Match items whose grant equals this included usage. Omitted is a wildcard.

License links to drop, keyed by license\_plan\_id. Parallel to remove\_items.

**properties**

Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send\_invoice collection method.

**properties**

When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send\_invoice collection method.

Deprecated: use the top-level enable\_plan on attach, billing.update and set\_plans. If true, enables the plan before the invoice is paid: once a draft is finalized, now when the invoice is issued straight away, or before a future starts\_at.

Deprecated: use issue\_method. true sends the invoice (issue\_method: send), false keeps it as a draft (issue\_method: draft). Defaults to true. Ignored when issue\_method is set.

How far the invoice created now advances. draft leaves it editable for manual review. finalize opens it without Stripe emailing, reminding or charging (auto\_advance off), for invoices collected outside Stripe. send opens it and lets Stripe email it. Defaults to send. Requires enabled: true. With a future starts\_at only send applies: the invoice is created and sent when the plan starts. Renewal invoices follow the customer's config.renewal\_issue\_method.

ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.

Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).

Payment method types the customer can pay the invoice with, e.g. card and us\_bank\_account. Overrides the org's allowed payment methods.

When the plan turns on. 'on\_payment' (default) waits until the invoice is paid or checkout completes. 'on\_finalize' turns it on once the invoice is finalized, before payment, and needs invoice\_mode. 'immediately' turns it on now, even while the invoice is still a draft; voiding or deleting the draft leaves the plan on. Takes precedence over the deprecated enable\_plan\_immediately flags.

How to handle proration when updating an existing subscription. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges, 'bill\_difference' bills the larger of the full-period price difference and the prorated amount (full difference on upgrades, prorated credit on downgrades) now without changing the billing cycle.

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.

A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.

List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.

**properties**

The ID of the reward to apply as a discount.

The promotion code to apply as a discount.

Discounts to remove from the subscription, by reward ID. Discounts not listed are left unchanged.

**properties**

The ID of the reward (or Stripe coupon) to remove.

Custom line items that replace the auto-generated proration invoice, or bill a standalone invoice when nothing else changes. Only valid on an existing recurring subscription.

**properties**

Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.

Description for the line item.

Lines to remove from the invoice this request creates. Never changes the subscription or later invoices.

**properties**

The plan whose lines to remove: one coming in, going out, or already on the customer and billed by this request.

The entity the lines are billed to. Omit to inherit the request's entity\_id, or pass null for customer-level.

Only remove charges or only remove refunds (credits). Omit to remove both.

Remove the base price line. Pass true, or an object to narrow by interval.

**properties**

The feature whose line to remove.

Which of the feature's prices to match: 'prepaid' or 'usage\_based'.

Only match the price billed on this interval. Needed when the same price exists on more than one interval.

Only match the price billed every this many intervals.

**properties**

The license plan linked to the parent plan.

Remove the base price line. Pass true, or an object to narrow by interval.

**properties**

The feature whose line to remove.

Which of the feature's prices to match: 'prepaid' or 'usage\_based'.

Only match the price billed on this interval. Needed when the same price exists on more than one interval.

Only match the price billed every this many intervals.

Lines to add to the invoice this request creates. Never changes the subscription or later invoices.

**properties**

Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.

Description for the line item.

Start of the period this charge covers, in milliseconds. Printed on the line only; a custom line never inherits the invoice's period.

End of the period this charge covers, in milliseconds. Given together with period\_start.

Action to perform for cancellation. 'cancel\_immediately' cancels now with prorated refund, 'cancel\_end\_of\_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.

Reset the billing cycle immediately with 'now', or schedule a reset at a future Unix timestamp in milliseconds.

If true, the subscription is updated internally without applying billing changes in Stripe.

Controls how the last payment is refunded on immediate cancellation. 'prorated' refunds the unused portion, 'full' refunds the entire last payment.

Additional parameters to pass into the Stripe subscription update or cancel call. Fields Autumn manages itself are rejected with a 400; use invoice\_mode to bill by invoice.

Controls whether balances should be recalculated during the subscription update.

**properties**

If true, recalculates balances during the subscription update. Only applicable when updating feature quantities.

Whether to carry over usages from the previous plan.

**properties**

Whether to carry over usages from the previous plan.

The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.

Total seat quantities (inclusive of the license's included count) per license plan offered by this plan. Licenses not listed keep their current paid quantity.

**properties**

The license plan to set seat quantity for.

Total seats for the license, inclusive of the plan's included amount — seats beyond it are paid.

### Response

The ID of the customer.

List of line items for the current billing period.

**properties**

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.

A detailed description of the line item.

The amount before discounts and tax for this line item.

The final amount after discounts and tax for this line item.

List of discounts applied to this line item.

**properties**

The ID of the plan that this line item belongs to.

The ID of the feature that this line item belongs to.

The period of time that this line item is being charged for.

**properties**

The start of the period in milliseconds since the Unix epoch.

The end of the period in milliseconds since the Unix epoch.

The quantity of the line item.

The total amount before discounts and tax for the current billing period.

The final amount after discounts and tax for the current billing period.

The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).

The invoice this change creates right away, if any. Renewals are described by next\_cycle.

**properties**

What the invoice created now bills. 'none' when the change creates no invoice now. 'zero\_amount' when an invoice is created but nothing was billed, such as a trial or a usage-only plan. 'charge' when something was billed, even if discounts or credits bring the amount due to zero. 'credit' when the invoice total is negative and becomes customer credit.

How the invoice is issued, matching invoice\_mode.issue\_method: 'draft', 'finalize' or 'send'. 'charge\_automatically' when the card on file is charged, or the customer pays at checkout. Null when type is 'none'.

When the change takes effect. 'now' when it applies as soon as the request succeeds, 'on\_finalize' when it waits for this draft invoice to be finalized, 'on\_payment' when it waits for the invoice to be paid or the checkout to complete.

True when this change clears the customer's usage balances, so the approver can see usage will reset.

Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.

**properties**

Unix timestamp (milliseconds) when the next billing cycle starts.

The total amount before discounts and tax for the next cycle.

The final amount after discounts and tax for the next cycle.

List of line items for the next billing cycle.

**properties**

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.

A detailed description of the line item.

The amount before discounts and tax for this line item.

The final amount after discounts and tax for this line item.

List of discounts applied to this line item.

**properties**

The ID of the plan that this line item belongs to.

The ID of the feature that this line item belongs to.

The period of time that this line item is being charged for.

**properties**

The start of the period in milliseconds since the Unix epoch.

The end of the period in milliseconds since the Unix epoch.

The quantity of the line item.

List of line items for usage-based features in the next cycle.

**properties**

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.

The ID of the plan that this line item belongs to.

The ID of the feature that this line item belongs to.

The period of time that this line item is being charged for.

**properties**

The start of the period in milliseconds since the Unix epoch.

The end of the period in milliseconds since the Unix epoch.

True when this request can't be charged automatically because the customer has no payment method. Add one, or send an invoice with invoice\_mode.

Expand the response with additional data.

Products or subscription changes being added or updated.

**properties**

The ID of the plan affected by this preview change.

The full plan object if it was expanded in the response.

**properties**

Unique identifier for the plan.

Display name of the plan.

Optional description of the plan.

Group identifier for organizing related plans. Plans in the same group are mutually exclusive.

Version number of the plan. Incremented when plan configuration changes.

User-facing version identity. Defaults to v\{n} when the version is minted.

Whether this is the active version of the plan. At most one version is active.

Whether this is an add-on plan that can be attached alongside a main plan.

If true, this plan is automatically attached when a customer is created. Used for free plans.

Base recurring price for the plan. Null for free plans or usage-only plans.

**properties**

Base price amount for the plan, in major currency units (e.g. dollars).

Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Billing interval (e.g. 'month', 'year').

Number of intervals per billing cycle. Defaults to 1.

Display text for showing this price in pricing pages.

**properties**

Main display text (e.g. '\$10' or '100 messages').

Secondary display text (e.g. 'per month' or 'then \$0.5 per 100').

Payment processors this base price is connected to. Omitted when unset.

**properties**

**properties**

Stripe price ID. For prepaid with included > 0 this is the V2 price.

Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.

**properties**

Bills this many feature units when outstanding overage reaches it.

**properties**

The ID of the feature this item configures.

The full feature object if expanded.

**properties**

The ID of the feature, used to refer to it in other API calls like /track or /check.

The name of the feature.

The type of the feature

Singular and plural display names for the feature.

**properties**

The singular display name for the feature.

The plural display name for the feature.

Credit cost schema for credit system features.

**properties**

The ID of the metered feature (should be a single\_use feature).

The credit cost of the metered feature.

Whether or not the feature is archived.

Number of free units included. For consumable features, balance resets to this number each interval.

Whether the customer has unlimited access to this feature.

Whether entity-level grants contribute to a shared customer balance.

Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.

**properties**

The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.

Number of intervals between resets. Defaults to 1.

Pricing configuration for usage beyond included units. Null if feature is entirely free.

**properties**

Price per billing\_units after included usage is consumed. Mutually exclusive with tiers.

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).

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.

**properties**

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Per-unit amount for this tier in this currency.

Flat amount for this tier in this currency, if the tier uses one.

How tiers price usage. 'graduated' (default) charges each unit at the rate of the tier it falls in. 'volume' picks one tier from total usage. On usage-based items it bills only usage past the included amount, at the rate of the tier total usage reaches, plus its flat\_amount. On prepaid items it charges every unit, the included ones too, at that tier's rate plus its flat\_amount.

Billing interval for this price. For usage-based features, should match reset.interval, unless the price has graduated tiers and reset.interval is a whole multiple of it: each invoice then bills only the newly owed usage, at the tier the reset period has reached.

Number of intervals per billing cycle. Defaults to 1.

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).

'prepaid' for features like seats where customers pay upfront, 'usage\_based' for pay-as-you-go after included usage.

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.

Payment processors this item price is connected to. Omitted when unset.

**properties**

**properties**

Stripe price ID. For prepaid with included > 0 this is the V2 price.

Display text for showing this item in pricing pages.

**properties**

Main display text (e.g. '\$10' or '100 messages').

Secondary display text (e.g. 'per month' or 'then \$0.5 per 100').

Rollover configuration for unused units. If set, unused included units roll over to the next period.

**properties**

Maximum rollover units. Null for unlimited rollover.

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

When rolled over units expire.

Number of periods before expiry.

Purchased units expire this long after each purchase. One-off prepaid consumable items only.

**properties**

Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

**properties**

For credit system features: merges into the feature's credit\_schema by metered\_feature\_id for customers on this plan. A row with a rate overrides or adds that feature, a row with `excluded: true` removes it, and unlisted features keep the credit system's rate.

**properties**

ID of the metered feature that draws from this credit system.

Number of metered-feature units priced together. Defaults to one when omitted.

Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

**properties**

Event properties this entry applies to. Every key must equal the tracked property, compared as strings.

Multiplies the matched rate. All matching multipliers stack.

Added to the rate after every factor is applied, in credits per billing-unit group.

**properties**

Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.

Credits consumed per billing-unit group within this tier.

Credits consumed per billing-unit group.

Removes this feature from the credit system for customers on this plan. Cannot be combined with a rate.

For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

**properties**

Default percentage markup for customers on this plan. Use -100 to make usage free.

Per-provider markup percentages for customers on this plan.

**properties**

Per-model markup overrides for customers on this plan.

**properties**

Payment processors this plan is connected to. Omitted when unset.

**properties**

**properties**

Stripe product ID this plan is billed under.

Extra Stripe product IDs aliased to this plan.

**properties**

Every RevenueCat product that maps to this plan. Replaces the current set.

**properties**

RevenueCat product ID that grants this plan when purchased.

Prepaid quantities granted when this specific RevenueCat product is purchased, in feature units.

**properties**

Free trial configuration. If set, new customers can try this plan before being charged.

**properties**

Number of duration\_type periods the trial lasts.

Unit of time for the trial duration ('day', 'month', 'year').

Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.

Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.

Unix timestamp (ms) when the plan was created.

Environment this plan belongs to ('sandbox' or 'live').

Whether the plan is archived. Archived plans cannot be attached to new customers.

Miscellaneous plan-level configuration flags.

**properties**

If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past\_due state.

Anchor billing and reset cycles to the 1st of the month (UTC).

Plan-level billing controls used as customer defaults.

**properties**

List of auto top-up configurations per feature.

**properties**

The ID of the feature (credit balance) to auto top-up.

Whether auto top-up is enabled.

When the balance drops below this threshold, an auto top-up will be purchased.

Amount of credits to add per auto top-up.

Optional limit on auto top-ups per window, by number of top-ups or amount charged.

**properties**

What `limit` caps: the number of auto top-ups (`count`, default) or the total amount charged for them, in the customer's currency (`amount`).

The time interval for the purchase limit window.

Number of intervals in the purchase limit window.

Maximum allowed within the interval: a number of auto top-ups when limit\_type is count, or a total charge (e.g. 500 for \$500, pre-tax) when limit\_type is amount.

When true, auto top-up creates a send\_invoice invoice instead of auto-charging.

List of overage spend limits per feature (caps overage spend).

**properties**

Optional feature ID this spend limit applies to.

Whether the overage spend limit is enabled.

How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.

Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.

When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.

List of hard usage caps per feature (max units per interval).

**properties**

The feature this usage limit applies to.

Whether this usage limit is enabled.

Maximum units allowed per interval.

Interval for the cap, aligned to the customer's billing cycle.

Window alignment. 'billing\_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar.

When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.

**properties**

List of usage alert configurations per feature.

**properties**

The feature ID this alert applies to.

Whether this usage alert is enabled.

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. remaining and remaining\_percentage accept negative values with basis balance, to alert once the balance is overdrawn.

Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.

What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage\_limit: the cap of the usage limit with the same feature and filter.

Only valid with basis usage\_limit. Points the alert at the usage limit carrying the same filter.

**properties**

Optional user-defined label to distinguish multiple alerts on the same feature.

List of overage allowed controls per feature. When enabled, usage can exceed balance.

**properties**

The feature ID this overage allowed control applies to.

Whether overage is allowed for this feature.

Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.

**properties**

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.

The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.

Whether the customer's active instance of this plan is set to cancel.

Whether the customer is currently on a free trial of this plan.

The action that would occur if this plan were attached to the customer.

Deprecated. Use variant\_details.base\_plan\_id instead. If this is a variant, the ID of the base plan it was created from.

Details about how this variant relates to its latest base plan.

**properties**

The ID of the base plan this variant was derived from.

The customization that transforms the base plan into this variant.

**properties**

Base price configuration for a plan.

**properties**

Base price amount for the plan, in major currency units (e.g. dollars).

Billing interval (e.g. 'month', 'year').

Number of intervals per billing cycle. Defaults to 1.

Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Items to add to the plan.

**properties**

Bills this many feature units when outstanding overage reaches it.

**properties**

The ID of the feature to configure.

Number of free units included. Balance resets to this each interval for consumable features.

If true, customer has unlimited access to this feature.

Whether entity-level grants contribute to a shared customer balance.

Reset configuration for consumable features. Omit for non-consumable features like seats.

**properties**

Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.

Number of intervals between resets. Defaults to 1.

Pricing for usage beyond included units. Omit for free features.

**properties**

Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.

Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Tiered pricing. Either 'amount' or 'tiers' is required.

**properties**

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Per-unit amount for this tier in this currency.

Flat amount for this tier in this currency, if the tier uses one.

How tiers price usage. 'graduated' (default) charges each unit at the rate of the tier it falls in. 'volume' picks one tier from total usage. On usage-based items it bills only usage past the included amount, at the rate of the tier total usage reaches, plus its flat\_amount. On prepaid items it charges every unit, the included ones too, at that tier's rate plus its flat\_amount.

Billing interval. For usage-based features, should match reset.interval, unless the price has graduated tiers and reset.interval is a whole multiple of it: each invoice then bills only the newly owed usage, at the tier the reset period has reached.

Number of intervals per billing cycle. Defaults to 1.

Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).

'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.

Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.

Proration settings for prepaid features. Controls mid-cycle quantity change billing.

**properties**

Billing behavior when quantity increases mid-cycle.

Credit behavior when quantity decreases mid-cycle.

Rollover config for unused units. If set, unused included units carry over.

**properties**

Max rollover units. Omit for unlimited rollover.

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

When rolled over units expire.

Number of periods before expiry.

Purchased units expire this long after each purchase. One-off prepaid consumable items only.

**properties**

Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

**properties**

For credit system features: merges into the feature's credit\_schema by metered\_feature\_id for customers on this plan. A row with a rate overrides or adds that feature, a row with `excluded: true` removes it, and unlisted features keep the credit system's rate.

**properties**

ID of the metered feature that draws from this credit system.

Number of metered-feature units priced together. Defaults to one when omitted.

Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

**properties**

Event properties this entry applies to. Every key must equal the tracked property, compared as strings.

Multiplies the matched rate. All matching multipliers stack.

Added to the rate after every factor is applied, in credits per billing-unit group.

**properties**

Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.

Credits consumed per billing-unit group within this tier.

Credits consumed per billing-unit group.

Removes this feature from the credit system for customers on this plan. Cannot be combined with a rate.

For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

**properties**

Default percentage markup for customers on this plan. Use -100 to make usage free.

Per-provider markup percentages for customers on this plan.

**properties**

Per-model markup overrides for customers on this plan.

**properties**

Filters selecting items to remove from the plan.

**properties**

Match items linked to this feature.

Match items with this billing method (prepaid or usage\_based).

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.

Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.

Match items whose grant equals this included usage. Omitted is a wildcard.

Free trial configuration for a plan.

**properties**

Number of duration\_type periods the trial lasts.

Unit of time for the trial ('day', 'month', 'year').

If true, a payment method is required to start the trial and the customer is charged when it ends. Defaults to false.

Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.

Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.

**properties**

List of auto top-up configurations per feature.

**properties**

The ID of the feature (credit balance) to auto top-up.

Whether auto top-up is enabled.

When the balance drops below this threshold, an auto top-up will be purchased.

Amount of credits to add per auto top-up.

Optional rate limit to cap how often auto top-ups occur. Pass count or amount to set the current window's consumed top-ups or charged amount.

**properties**

What `limit` caps: the number of auto top-ups (`count`, default) or the total amount charged for them, in the customer's currency (`amount`).

The time interval for the purchase limit window.

Number of intervals in the purchase limit window.

Maximum allowed within the interval: a number of auto top-ups when limit\_type is count, or a total charge (e.g. 500 for \$500, pre-tax) when limit\_type is amount.

Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.

Set the amount already charged by auto top-ups in the current window. Omit to leave runtime state unchanged.

When true, auto top-up creates a send\_invoice invoice instead of auto-charging.

List of overage spend limits per feature (caps overage spend).

**properties**

Optional feature ID this spend limit applies to.

Whether the overage spend limit is enabled.

How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.

Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.

When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.

List of hard usage caps per feature (max units per interval).

**properties**

The feature this usage limit applies to.

Whether this usage limit is enabled.

Maximum units allowed per interval.

Interval for the cap, aligned to the customer's billing cycle.

Window alignment. 'billing\_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar.

When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.

**properties**

List of usage alert configurations per feature.

**properties**

The feature ID this alert applies to.

Whether this usage alert is enabled.

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. remaining and remaining\_percentage accept negative values with basis balance, to alert once the balance is overdrawn.

Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.

What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage\_limit: the cap of the usage limit with the same feature and filter.

Only valid with basis usage\_limit. Points the alert at the usage limit carrying the same filter.

**properties**

Optional user-defined label to distinguish multiple alerts on the same feature.

List of overage allowed controls per feature. When enabled, usage can exceed balance.

**properties**

The feature ID this overage allowed control applies to.

Whether overage is allowed for this feature.

License links to add or override for this customer, keyed by license\_plan\_id. Omitted fields inherit the plan catalog link (included defaults to 1 when the license is not in the catalog). A bare entry restores the license to pure catalog inheritance.

**properties**

**properties**

Base price configuration for a plan.

**properties**

Base price amount for the plan, in major currency units (e.g. dollars).

Billing interval (e.g. 'month', 'year').

Number of intervals per billing cycle. Defaults to 1.

Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

**properties**

Bills this many feature units when outstanding overage reaches it.

**properties**

The ID of the feature to configure.

Number of free units included. Balance resets to this each interval for consumable features.

If true, customer has unlimited access to this feature.

Whether entity-level grants contribute to a shared customer balance.

Reset configuration for consumable features. Omit for non-consumable features like seats.

**properties**

Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.

Number of intervals between resets. Defaults to 1.

Pricing for usage beyond included units. Omit for free features.

**properties**

Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.

Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Tiered pricing. Either 'amount' or 'tiers' is required.

**properties**

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Per-unit amount for this tier in this currency.

Flat amount for this tier in this currency, if the tier uses one.

How tiers price usage. 'graduated' (default) charges each unit at the rate of the tier it falls in. 'volume' picks one tier from total usage. On usage-based items it bills only usage past the included amount, at the rate of the tier total usage reaches, plus its flat\_amount. On prepaid items it charges every unit, the included ones too, at that tier's rate plus its flat\_amount.

Billing interval. For usage-based features, should match reset.interval, unless the price has graduated tiers and reset.interval is a whole multiple of it: each invoice then bills only the newly owed usage, at the tier the reset period has reached.

Number of intervals per billing cycle. Defaults to 1.

Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).

'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.

Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.

Proration settings for prepaid features. Controls mid-cycle quantity change billing.

**properties**

Billing behavior when quantity increases mid-cycle.

Credit behavior when quantity decreases mid-cycle.

Rollover config for unused units. If set, unused included units carry over.

**properties**

Max rollover units. Omit for unlimited rollover.

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

When rolled over units expire.

Number of periods before expiry.

Purchased units expire this long after each purchase. One-off prepaid consumable items only.

**properties**

Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

**properties**

For credit system features: merges into the feature's credit\_schema by metered\_feature\_id for customers on this plan. A row with a rate overrides or adds that feature, a row with `excluded: true` removes it, and unlisted features keep the credit system's rate.

**properties**

ID of the metered feature that draws from this credit system.

Number of metered-feature units priced together. Defaults to one when omitted.

Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

**properties**

Event properties this entry applies to. Every key must equal the tracked property, compared as strings.

Multiplies the matched rate. All matching multipliers stack.

Added to the rate after every factor is applied, in credits per billing-unit group.

**properties**

Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.

Credits consumed per billing-unit group within this tier.

Credits consumed per billing-unit group.

Removes this feature from the credit system for customers on this plan. Cannot be combined with a rate.

For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

**properties**

Default percentage markup for customers on this plan. Use -100 to make usage free.

Per-provider markup percentages for customers on this plan.

**properties**

Per-model markup overrides for customers on this plan.

**properties**

**properties**

Match items linked to this feature.

Match items with this billing method (prepaid or usage\_based).

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.

Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.

Match items whose grant equals this included usage. Omitted is a wildcard.

License links to drop, keyed by license\_plan\_id. Parallel to remove\_items.

**properties**

The feature quantity selections associated with this plan change.

**properties**

The ID of the adjustable feature included in this change.

The quantity that will apply for this feature in the change.

When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.

When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.

When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.

Products or subscription changes being removed or ended.

**properties**

The ID of the plan affected by this preview change.

The full plan object if it was expanded in the response.

**properties**

Unique identifier for the plan.

Display name of the plan.

Optional description of the plan.

Group identifier for organizing related plans. Plans in the same group are mutually exclusive.

Version number of the plan. Incremented when plan configuration changes.

User-facing version identity. Defaults to v\{n} when the version is minted.

Whether this is the active version of the plan. At most one version is active.

Whether this is an add-on plan that can be attached alongside a main plan.

If true, this plan is automatically attached when a customer is created. Used for free plans.

Base recurring price for the plan. Null for free plans or usage-only plans.

**properties**

Base price amount for the plan, in major currency units (e.g. dollars).

Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Billing interval (e.g. 'month', 'year').

Number of intervals per billing cycle. Defaults to 1.

Display text for showing this price in pricing pages.

**properties**

Main display text (e.g. '\$10' or '100 messages').

Secondary display text (e.g. 'per month' or 'then \$0.5 per 100').

Payment processors this base price is connected to. Omitted when unset.

**properties**

**properties**

Stripe price ID. For prepaid with included > 0 this is the V2 price.

Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.

**properties**

Bills this many feature units when outstanding overage reaches it.

**properties**

The ID of the feature this item configures.

The full feature object if expanded.

**properties**

The ID of the feature, used to refer to it in other API calls like /track or /check.

The name of the feature.

The type of the feature

Singular and plural display names for the feature.

**properties**

The singular display name for the feature.

The plural display name for the feature.

Credit cost schema for credit system features.

**properties**

The ID of the metered feature (should be a single\_use feature).

The credit cost of the metered feature.

Whether or not the feature is archived.

Number of free units included. For consumable features, balance resets to this number each interval.

Whether the customer has unlimited access to this feature.

Whether entity-level grants contribute to a shared customer balance.

Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.

**properties**

The interval at which the feature balance resets (e.g. 'month', 'year'). For consumable features, usage resets to 0 and included units are restored.

Number of intervals between resets. Defaults to 1.

Pricing configuration for usage beyond included units. Null if feature is entirely free.

**properties**

Price per billing\_units after included usage is consumed. Mutually exclusive with tiers.

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).

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Tiered pricing configuration. Each tier's 'to' INCLUDES the included amount. Either 'tiers' or 'amount' is required.

**properties**

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Per-unit amount for this tier in this currency.

Flat amount for this tier in this currency, if the tier uses one.

How tiers price usage. 'graduated' (default) charges each unit at the rate of the tier it falls in. 'volume' picks one tier from total usage. On usage-based items it bills only usage past the included amount, at the rate of the tier total usage reaches, plus its flat\_amount. On prepaid items it charges every unit, the included ones too, at that tier's rate plus its flat\_amount.

Billing interval for this price. For usage-based features, should match reset.interval, unless the price has graduated tiers and reset.interval is a whole multiple of it: each invoice then bills only the newly owed usage, at the tier the reset period has reached.

Number of intervals per billing cycle. Defaults to 1.

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).

'prepaid' for features like seats where customers pay upfront, 'usage\_based' for pay-as-you-go after included usage.

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.

Payment processors this item price is connected to. Omitted when unset.

**properties**

**properties**

Stripe price ID. For prepaid with included > 0 this is the V2 price.

Display text for showing this item in pricing pages.

**properties**

Main display text (e.g. '\$10' or '100 messages').

Secondary display text (e.g. 'per month' or 'then \$0.5 per 100').

Rollover configuration for unused units. If set, unused included units roll over to the next period.

**properties**

Maximum rollover units. Null for unlimited rollover.

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

When rolled over units expire.

Number of periods before expiry.

Purchased units expire this long after each purchase. One-off prepaid consumable items only.

**properties**

Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

**properties**

For credit system features: merges into the feature's credit\_schema by metered\_feature\_id for customers on this plan. A row with a rate overrides or adds that feature, a row with `excluded: true` removes it, and unlisted features keep the credit system's rate.

**properties**

ID of the metered feature that draws from this credit system.

Number of metered-feature units priced together. Defaults to one when omitted.

Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

**properties**

Event properties this entry applies to. Every key must equal the tracked property, compared as strings.

Multiplies the matched rate. All matching multipliers stack.

Added to the rate after every factor is applied, in credits per billing-unit group.

**properties**

Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.

Credits consumed per billing-unit group within this tier.

Credits consumed per billing-unit group.

Removes this feature from the credit system for customers on this plan. Cannot be combined with a rate.

For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

**properties**

Default percentage markup for customers on this plan. Use -100 to make usage free.

Per-provider markup percentages for customers on this plan.

**properties**

Per-model markup overrides for customers on this plan.

**properties**

Payment processors this plan is connected to. Omitted when unset.

**properties**

**properties**

Stripe product ID this plan is billed under.

Extra Stripe product IDs aliased to this plan.

**properties**

Every RevenueCat product that maps to this plan. Replaces the current set.

**properties**

RevenueCat product ID that grants this plan when purchased.

Prepaid quantities granted when this specific RevenueCat product is purchased, in feature units.

**properties**

Free trial configuration. If set, new customers can try this plan before being charged.

**properties**

Number of duration\_type periods the trial lasts.

Unit of time for the trial duration ('day', 'month', 'year').

Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.

Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.

Unix timestamp (ms) when the plan was created.

Environment this plan belongs to ('sandbox' or 'live').

Whether the plan is archived. Archived plans cannot be attached to new customers.

Miscellaneous plan-level configuration flags.

**properties**

If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past\_due state.

Anchor billing and reset cycles to the 1st of the month (UTC).

Plan-level billing controls used as customer defaults.

**properties**

List of auto top-up configurations per feature.

**properties**

The ID of the feature (credit balance) to auto top-up.

Whether auto top-up is enabled.

When the balance drops below this threshold, an auto top-up will be purchased.

Amount of credits to add per auto top-up.

Optional limit on auto top-ups per window, by number of top-ups or amount charged.

**properties**

What `limit` caps: the number of auto top-ups (`count`, default) or the total amount charged for them, in the customer's currency (`amount`).

The time interval for the purchase limit window.

Number of intervals in the purchase limit window.

Maximum allowed within the interval: a number of auto top-ups when limit\_type is count, or a total charge (e.g. 500 for \$500, pre-tax) when limit\_type is amount.

When true, auto top-up creates a send\_invoice invoice instead of auto-charging.

List of overage spend limits per feature (caps overage spend).

**properties**

Optional feature ID this spend limit applies to.

Whether the overage spend limit is enabled.

How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.

Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.

When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.

List of hard usage caps per feature (max units per interval).

**properties**

The feature this usage limit applies to.

Whether this usage limit is enabled.

Maximum units allowed per interval.

Interval for the cap, aligned to the customer's billing cycle.

Window alignment. 'billing\_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar.

When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.

**properties**

List of usage alert configurations per feature.

**properties**

The feature ID this alert applies to.

Whether this usage alert is enabled.

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. remaining and remaining\_percentage accept negative values with basis balance, to alert once the balance is overdrawn.

Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.

What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage\_limit: the cap of the usage limit with the same feature and filter.

Only valid with basis usage\_limit. Points the alert at the usage limit carrying the same filter.

**properties**

Optional user-defined label to distinguish multiple alerts on the same feature.

List of overage allowed controls per feature. When enabled, usage can exceed balance.

**properties**

The feature ID this overage allowed control applies to.

Whether overage is allowed for this feature.

Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.

**properties**

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.

The customer's current status with this plan. 'active' if attached, 'scheduled' if pending activation.

Whether the customer's active instance of this plan is set to cancel.

Whether the customer is currently on a free trial of this plan.

The action that would occur if this plan were attached to the customer.

Deprecated. Use variant\_details.base\_plan\_id instead. If this is a variant, the ID of the base plan it was created from.

Details about how this variant relates to its latest base plan.

**properties**

The ID of the base plan this variant was derived from.

The customization that transforms the base plan into this variant.

**properties**

Base price configuration for a plan.

**properties**

Base price amount for the plan, in major currency units (e.g. dollars).

Billing interval (e.g. 'month', 'year').

Number of intervals per billing cycle. Defaults to 1.

Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Items to add to the plan.

**properties**

Bills this many feature units when outstanding overage reaches it.

**properties**

The ID of the feature to configure.

Number of free units included. Balance resets to this each interval for consumable features.

If true, customer has unlimited access to this feature.

Whether entity-level grants contribute to a shared customer balance.

Reset configuration for consumable features. Omit for non-consumable features like seats.

**properties**

Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.

Number of intervals between resets. Defaults to 1.

Pricing for usage beyond included units. Omit for free features.

**properties**

Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.

Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Tiered pricing. Either 'amount' or 'tiers' is required.

**properties**

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Per-unit amount for this tier in this currency.

Flat amount for this tier in this currency, if the tier uses one.

How tiers price usage. 'graduated' (default) charges each unit at the rate of the tier it falls in. 'volume' picks one tier from total usage. On usage-based items it bills only usage past the included amount, at the rate of the tier total usage reaches, plus its flat\_amount. On prepaid items it charges every unit, the included ones too, at that tier's rate plus its flat\_amount.

Billing interval. For usage-based features, should match reset.interval, unless the price has graduated tiers and reset.interval is a whole multiple of it: each invoice then bills only the newly owed usage, at the tier the reset period has reached.

Number of intervals per billing cycle. Defaults to 1.

Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).

'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.

Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.

Proration settings for prepaid features. Controls mid-cycle quantity change billing.

**properties**

Billing behavior when quantity increases mid-cycle.

Credit behavior when quantity decreases mid-cycle.

Rollover config for unused units. If set, unused included units carry over.

**properties**

Max rollover units. Omit for unlimited rollover.

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

When rolled over units expire.

Number of periods before expiry.

Purchased units expire this long after each purchase. One-off prepaid consumable items only.

**properties**

Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

**properties**

For credit system features: merges into the feature's credit\_schema by metered\_feature\_id for customers on this plan. A row with a rate overrides or adds that feature, a row with `excluded: true` removes it, and unlisted features keep the credit system's rate.

**properties**

ID of the metered feature that draws from this credit system.

Number of metered-feature units priced together. Defaults to one when omitted.

Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

**properties**

Event properties this entry applies to. Every key must equal the tracked property, compared as strings.

Multiplies the matched rate. All matching multipliers stack.

Added to the rate after every factor is applied, in credits per billing-unit group.

**properties**

Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.

Credits consumed per billing-unit group within this tier.

Credits consumed per billing-unit group.

Removes this feature from the credit system for customers on this plan. Cannot be combined with a rate.

For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

**properties**

Default percentage markup for customers on this plan. Use -100 to make usage free.

Per-provider markup percentages for customers on this plan.

**properties**

Per-model markup overrides for customers on this plan.

**properties**

Filters selecting items to remove from the plan.

**properties**

Match items linked to this feature.

Match items with this billing method (prepaid or usage\_based).

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.

Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.

Match items whose grant equals this included usage. Omitted is a wildcard.

Free trial configuration for a plan.

**properties**

Number of duration\_type periods the trial lasts.

Unit of time for the trial ('day', 'month', 'year').

If true, a payment method is required to start the trial and the customer is charged when it ends. Defaults to false.

Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.

Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.

**properties**

List of auto top-up configurations per feature.

**properties**

The ID of the feature (credit balance) to auto top-up.

Whether auto top-up is enabled.

When the balance drops below this threshold, an auto top-up will be purchased.

Amount of credits to add per auto top-up.

Optional rate limit to cap how often auto top-ups occur. Pass count or amount to set the current window's consumed top-ups or charged amount.

**properties**

What `limit` caps: the number of auto top-ups (`count`, default) or the total amount charged for them, in the customer's currency (`amount`).

The time interval for the purchase limit window.

Number of intervals in the purchase limit window.

Maximum allowed within the interval: a number of auto top-ups when limit\_type is count, or a total charge (e.g. 500 for \$500, pre-tax) when limit\_type is amount.

Set the current window's consumed auto top-up count. Omit to leave runtime state unchanged.

Set the amount already charged by auto top-ups in the current window. Omit to leave runtime state unchanged.

When true, auto top-up creates a send\_invoice invoice instead of auto-charging.

List of overage spend limits per feature (caps overage spend).

**properties**

Optional feature ID this spend limit applies to.

Whether the overage spend limit is enabled.

How overage\_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.

Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit\_type is usage\_percentage.

When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.

List of hard usage caps per feature (max units per interval).

**properties**

The feature this usage limit applies to.

Whether this usage limit is enabled.

Maximum units allowed per interval.

Interval for the cap, aligned to the customer's billing cycle.

Window alignment. 'billing\_cycle' phases the interval to the customer's renewal time; 'utc' aligns to the UTC calendar.

When set, only usage from events whose properties match counts toward this cap. Omit to count all usage of the feature.

**properties**

List of usage alert configurations per feature.

**properties**

The feature ID this alert applies to.

Whether this usage alert is enabled.

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. remaining and remaining\_percentage accept negative values with basis balance, to alert once the balance is overdrawn.

Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.

What 100% means. balance: every grant on the feature. included: the plan allowance only. recurring: grants that reset. usage\_limit: the cap of the usage limit with the same feature and filter.

Only valid with basis usage\_limit. Points the alert at the usage limit carrying the same filter.

**properties**

Optional user-defined label to distinguish multiple alerts on the same feature.

List of overage allowed controls per feature. When enabled, usage can exceed balance.

**properties**

The feature ID this overage allowed control applies to.

Whether overage is allowed for this feature.

License links to add or override for this customer, keyed by license\_plan\_id. Omitted fields inherit the plan catalog link (included defaults to 1 when the license is not in the catalog). A bare entry restores the license to pure catalog inheritance.

**properties**

**properties**

Base price configuration for a plan.

**properties**

Base price amount for the plan, in major currency units (e.g. dollars).

Billing interval (e.g. 'month', 'year').

Number of intervals per billing cycle. Defaults to 1.

Base price amounts in additional currencies. The base 'amount' is in the org's default currency.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

**properties**

Bills this many feature units when outstanding overage reaches it.

**properties**

The ID of the feature to configure.

Number of free units included. Balance resets to this each interval for consumable features.

If true, customer has unlimited access to this feature.

Whether entity-level grants contribute to a shared customer balance.

Reset configuration for consumable features. Omit for non-consumable features like seats.

**properties**

Interval at which balance resets (e.g. 'month', 'year'). For consumable features only.

Number of intervals between resets. Defaults to 1.

Pricing for usage beyond included units. Omit for free features.

**properties**

Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.

Amounts in additional currencies for this flat price. The base 'amount' is in the org's default currency. Only valid with 'amount', not 'tiers'.

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Price amount in this currency. Set explicitly per currency, not converted from the base amount.

Tiered pricing. Either 'amount' or 'tiers' is required.

**properties**

**properties**

Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').

Per-unit amount for this tier in this currency.

Flat amount for this tier in this currency, if the tier uses one.

How tiers price usage. 'graduated' (default) charges each unit at the rate of the tier it falls in. 'volume' picks one tier from total usage. On usage-based items it bills only usage past the included amount, at the rate of the tier total usage reaches, plus its flat\_amount. On prepaid items it charges every unit, the included ones too, at that tier's rate plus its flat\_amount.

Billing interval. For usage-based features, should match reset.interval, unless the price has graduated tiers and reset.interval is a whole multiple of it: each invoice then bills only the newly owed usage, at the tier the reset period has reached.

Number of intervals per billing cycle. Defaults to 1.

Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).

'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.

Max units purchasable beyond included. E.g. included=100, max\_purchase=300 allows 400 total. Null for no limit.

Proration settings for prepaid features. Controls mid-cycle quantity change billing.

**properties**

Billing behavior when quantity increases mid-cycle.

Credit behavior when quantity decreases mid-cycle.

Rollover config for unused units. If set, unused included units carry over.

**properties**

Max rollover units. Omit for unlimited rollover.

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

When rolled over units expire.

Number of periods before expiry.

Purchased units expire this long after each purchase. One-off prepaid consumable items only.

**properties**

Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).

**properties**

For credit system features: merges into the feature's credit\_schema by metered\_feature\_id for customers on this plan. A row with a rate overrides or adds that feature, a row with `excluded: true` removes it, and unlisted features keep the credit system's rate.

**properties**

ID of the metered feature that draws from this credit system.

Number of metered-feature units priced together. Defaults to one when omitted.

Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.

Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.

**properties**

Event properties this entry applies to. Every key must equal the tracked property, compared as strings.

Multiplies the matched rate. All matching multipliers stack.

Added to the rate after every factor is applied, in credits per billing-unit group.

**properties**

Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.

Credits consumed per billing-unit group within this tier.

Credits consumed per billing-unit group.

Removes this feature from the credit system for customers on this plan. Cannot be combined with a rate.

For AI credit system features: replaces the feature's markup chain entirely for customers on this plan. An unset level means no markup at that level rather than inheriting the feature's.

**properties**

Default percentage markup for customers on this plan. Use -100 to make usage free.

Per-provider markup percentages for customers on this plan.

**properties**

Per-model markup overrides for customers on this plan.

**properties**

**properties**

Match items linked to this feature.

Match items with this billing method (prepaid or usage\_based).

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.

Match items with this interval\_count. Disambiguates between items that share an interval but differ in count.

Match items whose grant equals this included usage. Omitted is a wildcard.

License links to drop, keyed by license\_plan\_id. Parallel to remove\_items.

**properties**

The feature quantity selections associated with this plan change.

**properties**

The ID of the adjustable feature included in this change.

The quantity that will apply for this feature in the change.

When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.

When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.

When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.

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.

**properties**

Total tax amount in major currency units.

Tax included in line item subtotals.

Tax added on top of subtotals.

Three-letter currency code.

Calculation status. 'complete' when tax was calculated, 'incomplete' when the calculation errored, 'requires\_location' when the customer has no billing address to tax against.

Stripe customer invoice credits preview.

**properties**

Stripe customer credit balance available, expressed as a positive number in major currency units.

How much of that balance this invoice consumes, capped at its total. The rest stays on the customer.

Three-letter currency code.

```json 200 theme={null}
{
  "customerId": "charles",
  "lineItems": [
    {
      "display_name": "Pro seed",
      "description": "Pro seed (from 18 Feb 2026 to 18 Mar 2026)",
      "subtotal": 20,
      "total": 20,
      "discounts": []
    }
  ],
  "subtotal": 20,
  "total": 20,
  "currency": "usd"
}
```


## OpenAPI

````yaml openapi POST /v1/billing.preview_update
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.6.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths:
  /v1/billing.preview_update:
    post:
      tags:
        - billing
      description: >-
        Previews the billing changes that would occur when updating a
        subscription, without actually making any changes.


        Use this endpoint to show customers prorated charges or refunds before
        confirming subscription modifications.
      operationId: previewUpdate
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            default: 2.6.0
          x-speakeasy-globals-hidden: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                  description: The ID of the customer to attach the plan to.
                entity_id:
                  type: string
                  description: The ID of the entity to attach the plan to.
                plan_id:
                  type: string
                  description: >-
                    The ID of the plan to update. Optional if subscription_id is
                    provided, or if the customer has only one product.
                feature_quantities:
                  type: array
                  items:
                    type: object
                    properties:
                      feature_id:
                        type: string
                        description: The ID of the feature to set quantity for.
                      quantity:
                        type: number
                        minimum: 0
                        description: The quantity of the feature.
                      adjustable:
                        type: boolean
                        description: Whether the customer can adjust the quantity.
                    required:
                      - feature_id
                    title: FeatureQuantity
                    description: Quantity configuration for a prepaid feature.
                  description: >-
                    If this plan contains prepaid features, use this field to
                    specify the quantity of each prepaid feature. This quantity
                    includes the included amount and billing units defined when
                    setting up the plan.
                version:
                  type: number
                  description: The version of the plan to attach.
                free_trial:
                  anyOf:
                    - type: object
                      properties:
                        duration_length:
                          type: number
                          description: Number of duration_type periods the trial lasts.
                        duration_type:
                          enum:
                            - day
                            - month
                            - year
                          type: string
                          default: month
                          description: Unit of time for the trial ('day', 'month', 'year').
                        card_required:
                          type: boolean
                          default: false
                          description: >-
                            If true, a payment method is required to start the
                            trial and the customer is charged when it ends.
                            Defaults to false.
                        on_end:
                          enum:
                            - bill
                            - revert
                          type: string
                          description: >-
                            Behavior when the trial ends. 'bill' charges the
                            customer (default). 'revert' expires the trial and
                            restores the customer's previous plan.
                          default: bill
                      required:
                        - duration_length
                      title: FreeTrialParams
                      description: Free trial configuration for a plan.
                    - type: 'null'
                  description: >-
                    Free trial for this plan. A shorthand for
                    customize.free_trial, which takes precedence when both are
                    given.
                bill_upfront:
                  type: object
                  properties:
                    duration_length:
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                      exclusiveMinimum: 0
                      description: >-
                        Number of duration_type periods to bill upfront, counted
                        from the plan's start date. Must be 1 when the plan
                        starts on a future starts_at. Set either this or until.
                    duration_type:
                      enum:
                        - day
                        - week
                        - month
                        - year
                      type: string
                      description: >-
                        Unit of duration_length ('day', 'week', 'month',
                        'year'). Defaults to the plan's billing interval.
                    until:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                      description: >-
                        Unix timestamp in milliseconds to bill upfront until.
                        With a future starts_at it must be exactly one billing
                        period after starts_at. Set either this or
                        duration_length.
                    applies_to:
                      type: array
                      minItems: 1
                      items:
                        type: object
                        properties:
                          plan_id:
                            type: string
                            description: >-
                              The plan whose price to bill upfront. Defaults to
                              the plan in the request.
                      description: >-
                        The prices to bill upfront. Omit to bill the plan's base
                        price(s) upfront.
                  description: >-
                    Charge today for billing periods that haven't started yet.
                    Only the plan's base price is billed upfront; usage, prepaid
                    quantities and seats keep billing every period.
                customize:
                  type: object
                  properties:
                    price:
                      anyOf:
                        - type: object
                          properties:
                            amount:
                              type: number
                              description: >-
                                Base price amount for the plan, in major
                                currency units (e.g. dollars).
                            interval:
                              enum:
                                - one_off
                                - week
                                - month
                                - quarter
                                - semi_annual
                                - year
                              type: string
                              description: Billing interval (e.g. 'month', 'year').
                            interval_count:
                              type: number
                              description: >-
                                Number of intervals per billing cycle. Defaults
                                to 1.
                              default: 1
                            additional_currencies:
                              type: array
                              items:
                                type: object
                                properties:
                                  currency:
                                    type: string
                                    description: >-
                                      Three-letter Stripe-supported currency
                                      code (e.g. 'eur', 'gbp').
                                  amount:
                                    type: number
                                    description: >-
                                      Price amount in this currency. Set
                                      explicitly per currency, not converted
                                      from the base amount.
                                required:
                                  - currency
                                  - amount
                              description: >-
                                Base price amounts in additional currencies. The
                                base 'amount' is in the org's default currency.
                          required:
                            - amount
                            - interval
                          title: BasePrice
                          description: Base price configuration for a plan.
                        - type: 'null'
                      description: >-
                        Override the base price of the plan. Pass null to remove
                        the base price.
                    items:
                      type: array
                      items:
                        type: object
                        properties:
                          threshold_billing:
                            anyOf:
                              - type: object
                                properties:
                                  threshold:
                                    type: number
                                    exclusiveMinimum: 0
                                required:
                                  - threshold
                              - type: 'null'
                            description: >-
                              Bills this many feature units when outstanding
                              overage reaches it.
                          feature_id:
                            type: string
                            description: The ID of the feature to configure.
                          included:
                            type: number
                            maximum: 10000000000000
                            description: >-
                              Number of free units included. Balance resets to
                              this each interval for consumable features.
                          unlimited:
                            type: boolean
                            description: >-
                              If true, customer has unlimited access to this
                              feature.
                          pooled:
                            type: boolean
                            default: false
                            description: >-
                              Whether entity-level grants contribute to a shared
                              customer balance.
                          reset:
                            type: object
                            properties:
                              interval:
                                enum:
                                  - one_off
                                  - minute
                                  - hour
                                  - day
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                                description: >-
                                  Interval at which balance resets (e.g.
                                  'month', 'year'). For consumable features
                                  only.
                              interval_count:
                                type: number
                                description: >-
                                  Number of intervals between resets. Defaults
                                  to 1.
                                default: 1
                            required:
                              - interval
                            description: >-
                              Reset configuration for consumable features. Omit
                              for non-consumable features like seats.
                          price:
                            type: object
                            properties:
                              amount:
                                type: number
                                description: >-
                                  Price per billing_units after included usage.
                                  Either 'amount' or 'tiers' is required.
                              additional_currencies:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    currency:
                                      type: string
                                      description: >-
                                        Three-letter Stripe-supported currency
                                        code (e.g. 'eur', 'gbp').
                                    amount:
                                      type: number
                                      description: >-
                                        Price amount in this currency. Set
                                        explicitly per currency, not converted
                                        from the base amount.
                                  required:
                                    - currency
                                    - amount
                                description: >-
                                  Amounts in additional currencies for this flat
                                  price. The base 'amount' is in the org's
                                  default currency. Only valid with 'amount',
                                  not 'tiers'.
                              tiers:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    to:
                                      anyOf:
                                        - type: number
                                        - const: inf
                                    amount:
                                      type: number
                                    flat_amount:
                                      type: number
                                    additional_currencies:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          currency:
                                            type: string
                                            description: >-
                                              Three-letter Stripe-supported currency
                                              code (e.g. 'eur', 'gbp').
                                          amount:
                                            type: number
                                            description: >-
                                              Per-unit amount for this tier in this
                                              currency.
                                          flat_amount:
                                            type: number
                                            description: >-
                                              Flat amount for this tier in this
                                              currency, if the tier uses one.
                                        required:
                                          - currency
                                      description: >-
                                        Per-currency amounts for this tier. Tier
                                        boundaries ('to') are shared across all
                                        currencies.
                                  required:
                                    - to
                                description: >-
                                  Tiered pricing.  Either 'amount' or 'tiers' is
                                  required.
                              tier_behavior:
                                enum:
                                  - graduated
                                  - volume
                                type: string
                                description: >-
                                  How tiers price usage. 'graduated' (default)
                                  charges each unit at the rate of the tier it
                                  falls in. 'volume' picks one tier from total
                                  usage. On usage-based items it bills only
                                  usage past the included amount, at the rate of
                                  the tier total usage reaches, plus its
                                  flat_amount. On prepaid items it charges every
                                  unit, the included ones too, at that tier's
                                  rate plus its flat_amount.
                              interval:
                                enum:
                                  - one_off
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                                description: >-
                                  Billing interval. For usage-based features,
                                  should match reset.interval, unless the price
                                  has graduated tiers and reset.interval is a
                                  whole multiple of it: each invoice then bills
                                  only the newly owed usage, at the tier the
                                  reset period has reached.
                              interval_count:
                                type: number
                                description: >-
                                  Number of intervals per billing cycle.
                                  Defaults to 1.
                                default: 1
                              billing_units:
                                type: number
                                default: 1
                                description: >-
                                  Units per price increment. Usage is rounded UP
                                  when billed (e.g. billing_units=100 means 101
                                  rounds to 200).
                              billing_method:
                                enum:
                                  - prepaid
                                  - usage_based
                                type: string
                                description: >-
                                  'prepaid' for upfront payment (seats),
                                  'usage_based' for pay-as-you-go.
                              max_purchase:
                                anyOf:
                                  - type: number
                                  - type: 'null'
                                description: >-
                                  Max units purchasable beyond included. E.g.
                                  included=100, max_purchase=300 allows 400
                                  total. Null for no limit.
                            required:
                              - interval
                              - billing_method
                            description: >-
                              Pricing for usage beyond included units. Omit for
                              free features.
                          proration:
                            type: object
                            properties:
                              on_increase:
                                enum:
                                  - bill_immediately
                                  - prorate_immediately
                                  - prorate_next_cycle
                                  - bill_next_cycle
                                type: string
                                description: >-
                                  Billing behavior when quantity increases
                                  mid-cycle.
                              on_decrease:
                                enum:
                                  - prorate
                                  - prorate_immediately
                                  - prorate_next_cycle
                                  - none
                                  - no_prorations
                                type: string
                                description: >-
                                  Credit behavior when quantity decreases
                                  mid-cycle.
                            required:
                              - on_increase
                              - on_decrease
                            description: >-
                              Proration settings for prepaid features. Controls
                              mid-cycle quantity change billing.
                          rollover:
                            type: object
                            properties:
                              max:
                                type: number
                                description: >-
                                  Max rollover units. Omit for unlimited
                                  rollover.
                              max_percentage:
                                type: number
                                description: >-
                                  Maximum rollover as a percentage (0-100) of
                                  included + prepaid grant. Mutually exclusive
                                  with max.
                              expiry_duration_type:
                                enum:
                                  - month
                                  - forever
                                type: string
                                description: When rolled over units expire.
                              expiry_duration_length:
                                type: number
                                description: Number of periods before expiry.
                            required:
                              - expiry_duration_type
                            description: >-
                              Rollover config for unused units. If set, unused
                              included units carry over.
                          expiry:
                            type: object
                            properties:
                              duration:
                                enum:
                                  - day
                                  - week
                                  - month
                                  - year
                                type: string
                              length:
                                type: number
                            required:
                              - duration
                              - length
                            description: >-
                              Purchased units expire this long after each
                              purchase. One-off prepaid consumable items only.
                          feature_override:
                            type: object
                            properties:
                              credit_schema:
                                type: array
                                items:
                                  anyOf:
                                    - type: object
                                      properties:
                                        metered_feature_id:
                                          type: string
                                          minLength: 1
                                          description: >-
                                            ID of the metered feature that draws
                                            from this credit system.
                                        billing_units:
                                          type: number
                                          exclusiveMinimum: 0
                                          description: >-
                                            Number of metered-feature units priced
                                            together. Defaults to one when omitted.
                                        dimensions:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            $ref: >-
                                              #/components/schemas/CreditDimensionInput
                                          description: >-
                                            Named rates chosen by event properties.
                                            The most specific match sets the rate;
                                            with no match the item's own rate
                                            applies.
                                        multipliers:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            type: object
                                            properties:
                                              match:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                additionalProperties:
                                                  anyOf:
                                                    - type: string
                                                    - type: number
                                                    - type: boolean
                                                description: >-
                                                  Event properties this entry applies to.
                                                  Every key must equal the tracked
                                                  property, compared as strings.
                                              factor:
                                                type: number
                                                exclusiveMinimum: 0
                                                description: >-
                                                  Multiplies the matched rate. All
                                                  matching multipliers stack.
                                              add:
                                                type: number
                                                description: >-
                                                  Added to the rate after every factor is
                                                  applied, in credits per billing-unit
                                                  group.
                                            required:
                                              - match
                                            additionalProperties: false
                                          description: >-
                                            Named adjustments chosen by event
                                            properties. Every match applies: factors
                                            multiply, then adds are summed.
                                        tier_behavior:
                                          const: graduated
                                        tiers:
                                          type: array
                                          minItems: 1
                                          items:
                                            type: object
                                            properties:
                                              to:
                                                anyOf:
                                                  - type: number
                                                    exclusiveMinimum: 0
                                                  - enum:
                                                      - inf
                                                    type: string
                                                description: >-
                                                  Inclusive upper usage boundary for this
                                                  graduated tier. The final tier must be
                                                  'inf'.
                                              credit_cost:
                                                type: number
                                                minimum: 0
                                                description: >-
                                                  Credits consumed per billing-unit group
                                                  within this tier.
                                            required:
                                              - to
                                              - credit_cost
                                      required:
                                        - metered_feature_id
                                        - tier_behavior
                                        - tiers
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        metered_feature_id:
                                          type: string
                                          minLength: 1
                                          description: >-
                                            ID of the metered feature that draws
                                            from this credit system.
                                        billing_units:
                                          type: number
                                          exclusiveMinimum: 0
                                          description: >-
                                            Number of metered-feature units priced
                                            together. Defaults to one when omitted.
                                        dimensions:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            $ref: >-
                                              #/components/schemas/CreditDimensionInput
                                          description: >-
                                            Named rates chosen by event properties.
                                            The most specific match sets the rate;
                                            with no match the item's own rate
                                            applies.
                                        multipliers:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            type: object
                                            properties:
                                              match:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                additionalProperties:
                                                  anyOf:
                                                    - type: string
                                                    - type: number
                                                    - type: boolean
                                                description: >-
                                                  Event properties this entry applies to.
                                                  Every key must equal the tracked
                                                  property, compared as strings.
                                              factor:
                                                type: number
                                                exclusiveMinimum: 0
                                                description: >-
                                                  Multiplies the matched rate. All
                                                  matching multipliers stack.
                                              add:
                                                type: number
                                                description: >-
                                                  Added to the rate after every factor is
                                                  applied, in credits per billing-unit
                                                  group.
                                            required:
                                              - match
                                            additionalProperties: false
                                          description: >-
                                            Named adjustments chosen by event
                                            properties. Every match applies: factors
                                            multiply, then adds are summed.
                                        credit_cost:
                                          type: number
                                          minimum: 0
                                          description: Credits consumed per billing-unit group.
                                      required:
                                        - metered_feature_id
                                        - credit_cost
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        metered_feature_id:
                                          type: string
                                          minLength: 1
                                          description: >-
                                            ID of the metered feature to remove from
                                            the credit system.
                                        excluded:
                                          const: true
                                          description: >-
                                            Removes this feature from the credit
                                            system for customers on this plan.
                                            Cannot be combined with a rate.
                                      required:
                                        - metered_feature_id
                                        - excluded
                                      additionalProperties: false
                                description: >-
                                  For credit system features: merges into the
                                  feature's credit_schema by metered_feature_id
                                  for customers on this plan. A row with a rate
                                  overrides or adds that feature, a row with
                                  `excluded: true` removes it, and unlisted
                                  features keep the credit system's rate.
                              markups:
                                type: object
                                properties:
                                  default_markup:
                                    type: number
                                    minimum: -100
                                    description: >-
                                      Default percentage markup for customers on
                                      this plan. Use -100 to make usage free.
                                  provider_markups:
                                    anyOf:
                                      - type: object
                                        propertyNames:
                                          type: string
                                        additionalProperties:
                                          type: object
                                          properties:
                                            markup:
                                              type: number
                                              minimum: -100
                                          required:
                                            - markup
                                      - type: 'null'
                                    description: >-
                                      Per-provider markup percentages for
                                      customers on this plan.
                                  model_markups:
                                    anyOf:
                                      - type: object
                                        propertyNames:
                                          type: string
                                          pattern: .+\/.+
                                        additionalProperties:
                                          type: object
                                          properties:
                                            markup:
                                              type: number
                                              minimum: -100
                                            input_cost:
                                              type: number
                                              minimum: 0
                                            output_cost:
                                              type: number
                                              minimum: 0
                                      - type: 'null'
                                    description: >-
                                      Per-model markup overrides for customers
                                      on this plan.
                                additionalProperties: false
                                description: >-
                                  For AI credit system features: replaces the
                                  feature's markup chain entirely for customers
                                  on this plan. An unset level means no markup
                                  at that level rather than inheriting the
                                  feature's.
                            additionalProperties: false
                            description: >-
                              Overrides fields of this item's feature for
                              customers on this plan (e.g. a credit system's
                              credit_schema).
                        required:
                          - feature_id
                        title: PlanItem
                        description: >-
                          Configuration for a feature item in a plan, including
                          usage limits, pricing, and rollover settings.
                      description: >-
                        Override the items in the plan (PUT-style — replaces all
                        existing items). Mutually exclusive with add_items /
                        remove_items / deprecated update_items.
                    add_items:
                      type: array
                      items:
                        type: object
                        properties:
                          threshold_billing:
                            anyOf:
                              - type: object
                                properties:
                                  threshold:
                                    type: number
                                    exclusiveMinimum: 0
                                required:
                                  - threshold
                              - type: 'null'
                            description: >-
                              Bills this many feature units when outstanding
                              overage reaches it.
                          feature_id:
                            type: string
                            description: The ID of the feature to configure.
                          included:
                            type: number
                            maximum: 10000000000000
                            description: >-
                              Number of free units included. Balance resets to
                              this each interval for consumable features.
                          unlimited:
                            type: boolean
                            description: >-
                              If true, customer has unlimited access to this
                              feature.
                          pooled:
                            type: boolean
                            default: false
                            description: >-
                              Whether entity-level grants contribute to a shared
                              customer balance.
                          reset:
                            type: object
                            properties:
                              interval:
                                enum:
                                  - one_off
                                  - minute
                                  - hour
                                  - day
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                                description: >-
                                  Interval at which balance resets (e.g.
                                  'month', 'year'). For consumable features
                                  only.
                              interval_count:
                                type: number
                                description: >-
                                  Number of intervals between resets. Defaults
                                  to 1.
                                default: 1
                            required:
                              - interval
                            description: >-
                              Reset configuration for consumable features. Omit
                              for non-consumable features like seats.
                          price:
                            type: object
                            properties:
                              amount:
                                type: number
                                description: >-
                                  Price per billing_units after included usage.
                                  Either 'amount' or 'tiers' is required.
                              additional_currencies:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    currency:
                                      type: string
                                      description: >-
                                        Three-letter Stripe-supported currency
                                        code (e.g. 'eur', 'gbp').
                                    amount:
                                      type: number
                                      description: >-
                                        Price amount in this currency. Set
                                        explicitly per currency, not converted
                                        from the base amount.
                                  required:
                                    - currency
                                    - amount
                                description: >-
                                  Amounts in additional currencies for this flat
                                  price. The base 'amount' is in the org's
                                  default currency. Only valid with 'amount',
                                  not 'tiers'.
                              tiers:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    to:
                                      anyOf:
                                        - type: number
                                        - const: inf
                                    amount:
                                      type: number
                                    flat_amount:
                                      type: number
                                    additional_currencies:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          currency:
                                            type: string
                                            description: >-
                                              Three-letter Stripe-supported currency
                                              code (e.g. 'eur', 'gbp').
                                          amount:
                                            type: number
                                            description: >-
                                              Per-unit amount for this tier in this
                                              currency.
                                          flat_amount:
                                            type: number
                                            description: >-
                                              Flat amount for this tier in this
                                              currency, if the tier uses one.
                                        required:
                                          - currency
                                      description: >-
                                        Per-currency amounts for this tier. Tier
                                        boundaries ('to') are shared across all
                                        currencies.
                                  required:
                                    - to
                                description: >-
                                  Tiered pricing.  Either 'amount' or 'tiers' is
                                  required.
                              tier_behavior:
                                enum:
                                  - graduated
                                  - volume
                                type: string
                                description: >-
                                  How tiers price usage. 'graduated' (default)
                                  charges each unit at the rate of the tier it
                                  falls in. 'volume' picks one tier from total
                                  usage. On usage-based items it bills only
                                  usage past the included amount, at the rate of
                                  the tier total usage reaches, plus its
                                  flat_amount. On prepaid items it charges every
                                  unit, the included ones too, at that tier's
                                  rate plus its flat_amount.
                              interval:
                                enum:
                                  - one_off
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                                description: >-
                                  Billing interval. For usage-based features,
                                  should match reset.interval, unless the price
                                  has graduated tiers and reset.interval is a
                                  whole multiple of it: each invoice then bills
                                  only the newly owed usage, at the tier the
                                  reset period has reached.
                              interval_count:
                                type: number
                                description: >-
                                  Number of intervals per billing cycle.
                                  Defaults to 1.
                                default: 1
                              billing_units:
                                type: number
                                default: 1
                                description: >-
                                  Units per price increment. Usage is rounded UP
                                  when billed (e.g. billing_units=100 means 101
                                  rounds to 200).
                              billing_method:
                                enum:
                                  - prepaid
                                  - usage_based
                                type: string
                                description: >-
                                  'prepaid' for upfront payment (seats),
                                  'usage_based' for pay-as-you-go.
                              max_purchase:
                                anyOf:
                                  - type: number
                                  - type: 'null'
                                description: >-
                                  Max units purchasable beyond included. E.g.
                                  included=100, max_purchase=300 allows 400
                                  total. Null for no limit.
                            required:
                              - interval
                              - billing_method
                            description: >-
                              Pricing for usage beyond included units. Omit for
                              free features.
                          proration:
                            type: object
                            properties:
                              on_increase:
                                enum:
                                  - bill_immediately
                                  - prorate_immediately
                                  - prorate_next_cycle
                                  - bill_next_cycle
                                type: string
                                description: >-
                                  Billing behavior when quantity increases
                                  mid-cycle.
                              on_decrease:
                                enum:
                                  - prorate
                                  - prorate_immediately
                                  - prorate_next_cycle
                                  - none
                                  - no_prorations
                                type: string
                                description: >-
                                  Credit behavior when quantity decreases
                                  mid-cycle.
                            required:
                              - on_increase
                              - on_decrease
                            description: >-
                              Proration settings for prepaid features. Controls
                              mid-cycle quantity change billing.
                          rollover:
                            type: object
                            properties:
                              max:
                                type: number
                                description: >-
                                  Max rollover units. Omit for unlimited
                                  rollover.
                              max_percentage:
                                type: number
                                description: >-
                                  Maximum rollover as a percentage (0-100) of
                                  included + prepaid grant. Mutually exclusive
                                  with max.
                              expiry_duration_type:
                                enum:
                                  - month
                                  - forever
                                type: string
                                description: When rolled over units expire.
                              expiry_duration_length:
                                type: number
                                description: Number of periods before expiry.
                            required:
                              - expiry_duration_type
                            description: >-
                              Rollover config for unused units. If set, unused
                              included units carry over.
                          expiry:
                            type: object
                            properties:
                              duration:
                                enum:
                                  - day
                                  - week
                                  - month
                                  - year
                                type: string
                              length:
                                type: number
                            required:
                              - duration
                              - length
                            description: >-
                              Purchased units expire this long after each
                              purchase. One-off prepaid consumable items only.
                          feature_override:
                            type: object
                            properties:
                              credit_schema:
                                type: array
                                items:
                                  anyOf:
                                    - type: object
                                      properties:
                                        metered_feature_id:
                                          type: string
                                          minLength: 1
                                          description: >-
                                            ID of the metered feature that draws
                                            from this credit system.
                                        billing_units:
                                          type: number
                                          exclusiveMinimum: 0
                                          description: >-
                                            Number of metered-feature units priced
                                            together. Defaults to one when omitted.
                                        dimensions:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            $ref: >-
                                              #/components/schemas/CreditDimensionInput
                                          description: >-
                                            Named rates chosen by event properties.
                                            The most specific match sets the rate;
                                            with no match the item's own rate
                                            applies.
                                        multipliers:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            type: object
                                            properties:
                                              match:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                additionalProperties:
                                                  anyOf:
                                                    - type: string
                                                    - type: number
                                                    - type: boolean
                                                description: >-
                                                  Event properties this entry applies to.
                                                  Every key must equal the tracked
                                                  property, compared as strings.
                                              factor:
                                                type: number
                                                exclusiveMinimum: 0
                                                description: >-
                                                  Multiplies the matched rate. All
                                                  matching multipliers stack.
                                              add:
                                                type: number
                                                description: >-
                                                  Added to the rate after every factor is
                                                  applied, in credits per billing-unit
                                                  group.
                                            required:
                                              - match
                                            additionalProperties: false
                                          description: >-
                                            Named adjustments chosen by event
                                            properties. Every match applies: factors
                                            multiply, then adds are summed.
                                        tier_behavior:
                                          const: graduated
                                        tiers:
                                          type: array
                                          minItems: 1
                                          items:
                                            type: object
                                            properties:
                                              to:
                                                anyOf:
                                                  - type: number
                                                    exclusiveMinimum: 0
                                                  - enum:
                                                      - inf
                                                    type: string
                                                description: >-
                                                  Inclusive upper usage boundary for this
                                                  graduated tier. The final tier must be
                                                  'inf'.
                                              credit_cost:
                                                type: number
                                                minimum: 0
                                                description: >-
                                                  Credits consumed per billing-unit group
                                                  within this tier.
                                            required:
                                              - to
                                              - credit_cost
                                      required:
                                        - metered_feature_id
                                        - tier_behavior
                                        - tiers
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        metered_feature_id:
                                          type: string
                                          minLength: 1
                                          description: >-
                                            ID of the metered feature that draws
                                            from this credit system.
                                        billing_units:
                                          type: number
                                          exclusiveMinimum: 0
                                          description: >-
                                            Number of metered-feature units priced
                                            together. Defaults to one when omitted.
                                        dimensions:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            $ref: >-
                                              #/components/schemas/CreditDimensionInput
                                          description: >-
                                            Named rates chosen by event properties.
                                            The most specific match sets the rate;
                                            with no match the item's own rate
                                            applies.
                                        multipliers:
                                          type: object
                                          propertyNames:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          additionalProperties:
                                            type: object
                                            properties:
                                              match:
                                                type: object
                                                propertyNames:
                                                  type: string
                                                additionalProperties:
                                                  anyOf:
                                                    - type: string
                                                    - type: number
                                                    - type: boolean
                                                description: >-
                                                  Event properties this entry applies to.
                                                  Every key must equal the tracked
                                                  property, compared as strings.
                                              factor:
                                                type: number
                                                exclusiveMinimum: 0
                                                description: >-
                                                  Multiplies the matched rate. All
                                                  matching multipliers stack.
                                              add:
                                                type: number
                                                description: >-
                                                  Added to the rate after every factor is
                                                  applied, in credits per billing-unit
                                                  group.
                                            required:
                                              - match
                                            additionalProperties: false
                                          description: >-
                                            Named adjustments chosen by event
                                            properties. Every match applies: factors
                                            multiply, then adds are summed.
                                        credit_cost:
                                          type: number
                                          minimum: 0
                                          description: Credits consumed per billing-unit group.
                                      required:
                                        - metered_feature_id
                                        - credit_cost
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        metered_feature_id:
                                          type: string
                                          minLength: 1
                                          description: >-
                                            ID of the metered feature to remove from
                                            the credit system.
                                        excluded:
                                          const: true
                                          description: >-
                                            Removes this feature from the credit
                                            system for customers on this plan.
                                            Cannot be combined with a rate.
                                      required:
                                        - metered_feature_id
                                        - excluded
                                      additionalProperties: false
                                description: >-
                                  For credit system features: merges into the
                                  feature's credit_schema by metered_feature_id
                                  for customers on this plan. A row with a rate
                                  overrides or adds that feature, a row with
                                  `excluded: true` removes it, and unlisted
                                  features keep the credit system's rate.
                              markups:
                                type: object
                                properties:
                                  default_markup:
                                    type: number
                                    minimum: -100
                                    description: >-
                                      Default percentage markup for customers on
                                      this plan. Use -100 to make usage free.
                                  provider_markups:
                                    anyOf:
                                      - type: object
                                        propertyNames:
                                          type: string
                                        additionalProperties:
                                          type: object
                                          properties:
                                            markup:
                                              type: number
                                              minimum: -100
                                          required:
                                            - markup
                                      - type: 'null'
                                    description: >-
                                      Per-provider markup percentages for
                                      customers on this plan.
                                  model_markups:
                                    anyOf:
                                      - type: object
                                        propertyNames:
                                          type: string
                                          pattern: .+\/.+
                                        additionalProperties:
                                          type: object
                                          properties:
                                            markup:
                                              type: number
                                              minimum: -100
                                            input_cost:
                                              type: number
                                              minimum: 0
                                            output_cost:
                                              type: number
                                              minimum: 0
                                      - type: 'null'
                                    description: >-
                                      Per-model markup overrides for customers
                                      on this plan.
                                additionalProperties: false
                                description: >-
                                  For AI credit system features: replaces the
                                  feature's markup chain entirely for customers
                                  on this plan. An unset level means no markup
                                  at that level rather than inheriting the
                                  feature's.
                            additionalProperties: false
                            description: >-
                              Overrides fields of this item's feature for
                              customers on this plan (e.g. a credit system's
                              credit_schema).
                        required:
                          - feature_id
                        title: PlanItem
                        description: >-
                          Configuration for a feature item in a plan, including
                          usage limits, pricing, and rollover settings.
                      description: Items to add to the plan.
                    remove_items:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: Match items linked to this feature.
                          billing_method:
                            enum:
                              - prepaid
                              - usage_based
                            type: string
                            description: >-
                              Match items with this billing method (prepaid or
                              usage_based).
                          interval:
                            anyOf:
                              - enum:
                                  - one_off
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                              - enum:
                                  - one_off
                                  - minute
                                  - hour
                                  - day
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                            description: >-
                              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:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                            exclusiveMinimum: 0
                            description: >-
                              Match items with this interval_count.
                              Disambiguates between items that share an interval
                              but differ in count.
                          included:
                            type: number
                            maximum: 10000000000000
                            description: >-
                              Match items whose grant equals this included
                              usage. Omitted is a wildcard.
                        title: PlanItemFilter
                        description: >-
                          Filter for matching plan items. All provided fields
                          must match (AND).
                      description: Filters selecting items to remove from the plan.
                    free_trial:
                      anyOf:
                        - type: object
                          properties:
                            duration_length:
                              type: number
                              description: Number of duration_type periods the trial lasts.
                            duration_type:
                              enum:
                                - day
                                - month
                                - year
                              type: string
                              default: month
                              description: >-
                                Unit of time for the trial ('day', 'month',
                                'year').
                            card_required:
                              type: boolean
                              default: false
                              description: >-
                                If true, a payment method is required to start
                                the trial and the customer is charged when it
                                ends. Defaults to false.
                            on_end:
                              enum:
                                - bill
                                - revert
                              type: string
                              description: >-
                                Behavior when the trial ends. 'bill' charges the
                                customer (default). 'revert' expires the trial
                                and restores the customer's previous plan.
                              default: bill
                          required:
                            - duration_length
                          title: FreeTrialParams
                          description: Free trial configuration for a plan.
                        - type: 'null'
                      description: >-
                        Override the plan's default free trial. Pass an object
                        to set a custom trial, or null to remove the trial
                        entirely.
                    billing_controls:
                      type: object
                      properties:
                        auto_topups:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: >-
                                  The ID of the feature (credit balance) to auto
                                  top-up.
                              enabled:
                                type: boolean
                                default: false
                                description: Whether auto top-up is enabled.
                              threshold:
                                type: number
                                description: >-
                                  When the balance drops below this threshold,
                                  an auto top-up will be purchased.
                              quantity:
                                type: number
                                minimum: 1
                                description: Amount of credits to add per auto top-up.
                              purchase_limit:
                                type: object
                                properties:
                                  limit_type:
                                    enum:
                                      - count
                                      - amount
                                    type: string
                                    description: >-
                                      What `limit` caps: the number of auto
                                      top-ups (`count`, default) or the total
                                      amount charged for them, in the customer's
                                      currency (`amount`).
                                  interval:
                                    enum:
                                      - hour
                                      - day
                                      - week
                                      - month
                                    type: string
                                    description: >-
                                      The time interval for the purchase limit
                                      window.
                                  interval_count:
                                    type: number
                                    minimum: 1
                                    default: 1
                                    description: >-
                                      Number of intervals in the purchase limit
                                      window.
                                  limit:
                                    type: number
                                    exclusiveMinimum: 0
                                    description: >-
                                      Maximum allowed within the interval: a
                                      number of auto top-ups when limit_type is
                                      count, or a total charge (e.g. 500 for
                                      $500, pre-tax) when limit_type is amount.
                                  count:
                                    type: number
                                    minimum: 0
                                    description: >-
                                      Set the current window's consumed auto
                                      top-up count. Omit to leave runtime state
                                      unchanged.
                                  amount:
                                    type: number
                                    minimum: 0
                                    description: >-
                                      Set the amount already charged by auto
                                      top-ups in the current window. Omit to
                                      leave runtime state unchanged.
                                required:
                                  - interval
                                  - limit
                                description: >-
                                  Optional rate limit to cap how often auto
                                  top-ups occur. Pass count or amount to set the
                                  current window's consumed top-ups or charged
                                  amount.
                              invoice_mode:
                                type: boolean
                                description: >-
                                  When true, auto top-up creates a send_invoice
                                  invoice instead of auto-charging.
                            required:
                              - feature_id
                              - threshold
                              - quantity
                          description: List of auto top-up configurations per feature.
                          default: []
                        spend_limits:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: >-
                                  Optional feature ID this spend limit applies
                                  to.
                              enabled:
                                type: boolean
                                default: false
                                description: Whether the overage spend limit is enabled.
                              limit_type:
                                enum:
                                  - absolute
                                  - usage_percentage
                                type: string
                                description: >-
                                  How overage_limit is interpreted: an absolute
                                  overage cap (default) or a percentage of the
                                  main-plan allowance.
                              overage_limit:
                                type: number
                                minimum: 0
                                description: >-
                                  Overage cap for the feature: absolute units,
                                  or a percent (e.g. 120) when limit_type is
                                  usage_percentage.
                              skip_overage_billing:
                                type: boolean
                                description: >-
                                  When true, overage for this feature is not
                                  posted to Stripe. Usage tracking and balance
                                  resets still behave normally.
                          description: >-
                            List of overage spend limits per feature (caps
                            overage spend).
                          default: []
                        usage_limits:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: The feature this usage limit applies to.
                              enabled:
                                type: boolean
                                default: true
                                description: Whether this usage limit is enabled.
                              limit:
                                type: number
                                minimum: 0
                                description: Maximum units allowed per interval.
                              interval:
                                enum:
                                  - day
                                  - week
                                  - month
                                  - year
                                type: string
                                description: >-
                                  Interval for the cap, aligned to the
                                  customer's billing cycle.
                              anchor:
                                enum:
                                  - billing_cycle
                                  - utc
                                type: string
                                description: >-
                                  Window alignment. 'billing_cycle' phases the
                                  interval to the customer's renewal time; 'utc'
                                  aligns to the UTC calendar.
                              filter:
                                type: object
                                properties:
                                  properties:
                                    type: object
                                    propertyNames:
                                      type: string
                                      minLength: 1
                                      maxLength: 64
                                    additionalProperties:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                          maxLength: 128
                                        - type: number
                                        - type: boolean
                                required:
                                  - properties
                                description: >-
                                  When set, only usage from events whose
                                  properties match counts toward this cap. Omit
                                  to count all usage of the feature.
                            required:
                              - feature_id
                              - limit
                              - interval
                          description: >-
                            List of hard usage caps per feature (max units per
                            interval).
                          default: []
                        usage_alerts:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: The feature ID this alert applies to.
                              enabled:
                                type: boolean
                                default: true
                                description: Whether this usage alert is enabled.
                              threshold:
                                type: number
                                description: >-
                                  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.
                                  remaining and remaining_percentage accept
                                  negative values with basis balance, to alert
                                  once the balance is overdrawn.
                              threshold_type:
                                enum:
                                  - usage
                                  - usage_percentage
                                  - remaining
                                  - remaining_percentage
                                type: string
                                description: >-
                                  Whether the threshold is an absolute count or
                                  a percentage of the usage allowance or
                                  remaining balance.
                              basis:
                                enum:
                                  - balance
                                  - included
                                  - recurring
                                  - usage_limit
                                type: string
                                default: balance
                                description: >-
                                  What 100% means. balance: every grant on the
                                  feature. included: the plan allowance only.
                                  recurring: grants that reset. usage_limit: the
                                  cap of the usage limit with the same feature
                                  and filter.
                              filter:
                                type: object
                                properties:
                                  properties:
                                    type: object
                                    propertyNames:
                                      type: string
                                      minLength: 1
                                      maxLength: 64
                                    additionalProperties:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                          maxLength: 128
                                        - type: number
                                        - type: boolean
                                required:
                                  - properties
                                description: >-
                                  Only valid with basis usage_limit. Points the
                                  alert at the usage limit carrying the same
                                  filter.
                              name:
                                type: string
                                description: >-
                                  Optional user-defined label to distinguish
                                  multiple alerts on the same feature.
                            required:
                              - threshold
                              - threshold_type
                          description: List of usage alert configurations per feature.
                          default: []
                        overage_allowed:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: >-
                                  The feature ID this overage allowed control
                                  applies to.
                              enabled:
                                type: boolean
                                default: false
                                description: Whether overage is allowed for this feature.
                            required:
                              - feature_id
                          description: >-
                            List of overage allowed controls per feature. When
                            enabled, usage can exceed balance.
                          default: []
                      description: >-
                        Override the plan's billing controls (auto top-ups,
                        spend limits, usage limits, usage alerts, overage
                        allowed) for this customer.
                    upsert_licenses:
                      type: array
                      items:
                        type: object
                        properties:
                          license_plan_id:
                            type: string
                          version_slug:
                            type: string
                          included:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          prepaid_only:
                            type: boolean
                          customize:
                            anyOf:
                              - type: object
                                properties:
                                  price:
                                    anyOf:
                                      - type: object
                                        properties:
                                          amount:
                                            type: number
                                            description: >-
                                              Base price amount for the plan, in major
                                              currency units (e.g. dollars).
                                          interval:
                                            enum:
                                              - one_off
                                              - week
                                              - month
                                              - quarter
                                              - semi_annual
                                              - year
                                            type: string
                                            description: Billing interval (e.g. 'month', 'year').
                                          interval_count:
                                            type: number
                                            description: >-
                                              Number of intervals per billing cycle.
                                              Defaults to 1.
                                            default: 1
                                          additional_currencies:
                                            type: array
                                            items:
                                              type: object
                                              properties:
                                                currency:
                                                  type: string
                                                  description: >-
                                                    Three-letter Stripe-supported currency
                                                    code (e.g. 'eur', 'gbp').
                                                amount:
                                                  type: number
                                                  description: >-
                                                    Price amount in this currency. Set
                                                    explicitly per currency, not converted
                                                    from the base amount.
                                              required:
                                                - currency
                                                - amount
                                            description: >-
                                              Base price amounts in additional
                                              currencies. The base 'amount' is in the
                                              org's default currency.
                                        required:
                                          - amount
                                          - interval
                                        title: BasePrice
                                        description: Base price configuration for a plan.
                                      - type: 'null'
                                  add_items:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        threshold_billing:
                                          anyOf:
                                            - type: object
                                              properties:
                                                threshold:
                                                  type: number
                                                  exclusiveMinimum: 0
                                              required:
                                                - threshold
                                            - type: 'null'
                                          description: >-
                                            Bills this many feature units when
                                            outstanding overage reaches it.
                                        feature_id:
                                          type: string
                                          description: The ID of the feature to configure.
                                        included:
                                          type: number
                                          maximum: 10000000000000
                                          description: >-
                                            Number of free units included. Balance
                                            resets to this each interval for
                                            consumable features.
                                        unlimited:
                                          type: boolean
                                          description: >-
                                            If true, customer has unlimited access
                                            to this feature.
                                        pooled:
                                          type: boolean
                                          default: false
                                          description: >-
                                            Whether entity-level grants contribute
                                            to a shared customer balance.
                                        reset:
                                          type: object
                                          properties:
                                            interval:
                                              enum:
                                                - one_off
                                                - minute
                                                - hour
                                                - day
                                                - week
                                                - month
                                                - quarter
                                                - semi_annual
                                                - year
                                              type: string
                                              description: >-
                                                Interval at which balance resets (e.g.
                                                'month', 'year'). For consumable
                                                features only.
                                            interval_count:
                                              type: number
                                              description: >-
                                                Number of intervals between resets.
                                                Defaults to 1.
                                              default: 1
                                          required:
                                            - interval
                                          description: >-
                                            Reset configuration for consumable
                                            features. Omit for non-consumable
                                            features like seats.
                                        price:
                                          type: object
                                          properties:
                                            amount:
                                              type: number
                                              description: >-
                                                Price per billing_units after included
                                                usage. Either 'amount' or 'tiers' is
                                                required.
                                            additional_currencies:
                                              type: array
                                              items:
                                                type: object
                                                properties:
                                                  currency:
                                                    type: string
                                                    description: >-
                                                      Three-letter Stripe-supported currency
                                                      code (e.g. 'eur', 'gbp').
                                                  amount:
                                                    type: number
                                                    description: >-
                                                      Price amount in this currency. Set
                                                      explicitly per currency, not converted
                                                      from the base amount.
                                                required:
                                                  - currency
                                                  - amount
                                              description: >-
                                                Amounts in additional currencies for
                                                this flat price. The base 'amount' is in
                                                the org's default currency. Only valid
                                                with 'amount', not 'tiers'.
                                            tiers:
                                              type: array
                                              items:
                                                type: object
                                                properties:
                                                  to:
                                                    anyOf:
                                                      - type: number
                                                      - const: inf
                                                  amount:
                                                    type: number
                                                  flat_amount:
                                                    type: number
                                                  additional_currencies:
                                                    type: array
                                                    items:
                                                      type: object
                                                      properties:
                                                        currency:
                                                          type: string
                                                          description: >-
                                                            Three-letter Stripe-supported currency
                                                            code (e.g. 'eur', 'gbp').
                                                        amount:
                                                          type: number
                                                          description: >-
                                                            Per-unit amount for this tier in this
                                                            currency.
                                                        flat_amount:
                                                          type: number
                                                          description: >-
                                                            Flat amount for this tier in this
                                                            currency, if the tier uses one.
                                                      required:
                                                        - currency
                                                    description: >-
                                                      Per-currency amounts for this tier. Tier
                                                      boundaries ('to') are shared across all
                                                      currencies.
                                                required:
                                                  - to
                                              description: >-
                                                Tiered pricing.  Either 'amount' or
                                                'tiers' is required.
                                            tier_behavior:
                                              enum:
                                                - graduated
                                                - volume
                                              type: string
                                              description: >-
                                                How tiers price usage. 'graduated'
                                                (default) charges each unit at the rate
                                                of the tier it falls in. 'volume' picks
                                                one tier from total usage. On
                                                usage-based items it bills only usage
                                                past the included amount, at the rate of
                                                the tier total usage reaches, plus its
                                                flat_amount. On prepaid items it charges
                                                every unit, the included ones too, at
                                                that tier's rate plus its flat_amount.
                                            interval:
                                              enum:
                                                - one_off
                                                - week
                                                - month
                                                - quarter
                                                - semi_annual
                                                - year
                                              type: string
                                              description: >-
                                                Billing interval. For usage-based
                                                features, should match reset.interval,
                                                unless the price has graduated tiers and
                                                reset.interval is a whole multiple of
                                                it: each invoice then bills only the
                                                newly owed usage, at the tier the reset
                                                period has reached.
                                            interval_count:
                                              type: number
                                              description: >-
                                                Number of intervals per billing cycle.
                                                Defaults to 1.
                                              default: 1
                                            billing_units:
                                              type: number
                                              default: 1
                                              description: >-
                                                Units per price increment. Usage is
                                                rounded UP when billed (e.g.
                                                billing_units=100 means 101 rounds to
                                                200).
                                            billing_method:
                                              enum:
                                                - prepaid
                                                - usage_based
                                              type: string
                                              description: >-
                                                'prepaid' for upfront payment (seats),
                                                'usage_based' for pay-as-you-go.
                                            max_purchase:
                                              anyOf:
                                                - type: number
                                                - type: 'null'
                                              description: >-
                                                Max units purchasable beyond included.
                                                E.g. included=100, max_purchase=300
                                                allows 400 total. Null for no limit.
                                          required:
                                            - interval
                                            - billing_method
                                          description: >-
                                            Pricing for usage beyond included units.
                                            Omit for free features.
                                        proration:
                                          type: object
                                          properties:
                                            on_increase:
                                              enum:
                                                - bill_immediately
                                                - prorate_immediately
                                                - prorate_next_cycle
                                                - bill_next_cycle
                                              type: string
                                              description: >-
                                                Billing behavior when quantity increases
                                                mid-cycle.
                                            on_decrease:
                                              enum:
                                                - prorate
                                                - prorate_immediately
                                                - prorate_next_cycle
                                                - none
                                                - no_prorations
                                              type: string
                                              description: >-
                                                Credit behavior when quantity decreases
                                                mid-cycle.
                                          required:
                                            - on_increase
                                            - on_decrease
                                          description: >-
                                            Proration settings for prepaid features.
                                            Controls mid-cycle quantity change
                                            billing.
                                        rollover:
                                          type: object
                                          properties:
                                            max:
                                              type: number
                                              description: >-
                                                Max rollover units. Omit for unlimited
                                                rollover.
                                            max_percentage:
                                              type: number
                                              description: >-
                                                Maximum rollover as a percentage (0-100)
                                                of included + prepaid grant. Mutually
                                                exclusive with max.
                                            expiry_duration_type:
                                              enum:
                                                - month
                                                - forever
                                              type: string
                                              description: When rolled over units expire.
                                            expiry_duration_length:
                                              type: number
                                              description: Number of periods before expiry.
                                          required:
                                            - expiry_duration_type
                                          description: >-
                                            Rollover config for unused units. If
                                            set, unused included units carry over.
                                        expiry:
                                          type: object
                                          properties:
                                            duration:
                                              enum:
                                                - day
                                                - week
                                                - month
                                                - year
                                              type: string
                                            length:
                                              type: number
                                          required:
                                            - duration
                                            - length
                                          description: >-
                                            Purchased units expire this long after
                                            each purchase. One-off prepaid
                                            consumable items only.
                                        feature_override:
                                          type: object
                                          properties:
                                            credit_schema:
                                              type: array
                                              items:
                                                anyOf:
                                                  - type: object
                                                    properties:
                                                      metered_feature_id:
                                                        type: string
                                                        minLength: 1
                                                        description: >-
                                                          ID of the metered feature that draws
                                                          from this credit system.
                                                      billing_units:
                                                        type: number
                                                        exclusiveMinimum: 0
                                                        description: >-
                                                          Number of metered-feature units priced
                                                          together. Defaults to one when omitted.
                                                      dimensions:
                                                        type: object
                                                        propertyNames:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 64
                                                        additionalProperties:
                                                          $ref: >-
                                                            #/components/schemas/CreditDimensionInput
                                                        description: >-
                                                          Named rates chosen by event properties.
                                                          The most specific match sets the rate;
                                                          with no match the item's own rate
                                                          applies.
                                                      multipliers:
                                                        type: object
                                                        propertyNames:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 64
                                                        additionalProperties:
                                                          type: object
                                                          properties:
                                                            match:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                              additionalProperties:
                                                                anyOf:
                                                                  - type: string
                                                                  - type: number
                                                                  - type: boolean
                                                              description: >-
                                                                Event properties this entry applies to.
                                                                Every key must equal the tracked
                                                                property, compared as strings.
                                                            factor:
                                                              type: number
                                                              exclusiveMinimum: 0
                                                              description: >-
                                                                Multiplies the matched rate. All
                                                                matching multipliers stack.
                                                            add:
                                                              type: number
                                                              description: >-
                                                                Added to the rate after every factor is
                                                                applied, in credits per billing-unit
                                                                group.
                                                          required:
                                                            - match
                                                          additionalProperties: false
                                                        description: >-
                                                          Named adjustments chosen by event
                                                          properties. Every match applies: factors
                                                          multiply, then adds are summed.
                                                      tier_behavior:
                                                        const: graduated
                                                      tiers:
                                                        type: array
                                                        minItems: 1
                                                        items:
                                                          type: object
                                                          properties:
                                                            to:
                                                              anyOf:
                                                                - type: number
                                                                  exclusiveMinimum: 0
                                                                - enum:
                                                                    - inf
                                                                  type: string
                                                              description: >-
                                                                Inclusive upper usage boundary for this
                                                                graduated tier. The final tier must be
                                                                'inf'.
                                                            credit_cost:
                                                              type: number
                                                              minimum: 0
                                                              description: >-
                                                                Credits consumed per billing-unit group
                                                                within this tier.
                                                          required:
                                                            - to
                                                            - credit_cost
                                                    required:
                                                      - metered_feature_id
                                                      - tier_behavior
                                                      - tiers
                                                    additionalProperties: false
                                                  - type: object
                                                    properties:
                                                      metered_feature_id:
                                                        type: string
                                                        minLength: 1
                                                        description: >-
                                                          ID of the metered feature that draws
                                                          from this credit system.
                                                      billing_units:
                                                        type: number
                                                        exclusiveMinimum: 0
                                                        description: >-
                                                          Number of metered-feature units priced
                                                          together. Defaults to one when omitted.
                                                      dimensions:
                                                        type: object
                                                        propertyNames:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 64
                                                        additionalProperties:
                                                          $ref: >-
                                                            #/components/schemas/CreditDimensionInput
                                                        description: >-
                                                          Named rates chosen by event properties.
                                                          The most specific match sets the rate;
                                                          with no match the item's own rate
                                                          applies.
                                                      multipliers:
                                                        type: object
                                                        propertyNames:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 64
                                                        additionalProperties:
                                                          type: object
                                                          properties:
                                                            match:
                                                              type: object
                                                              propertyNames:
                                                                type: string
                                                              additionalProperties:
                                                                anyOf:
                                                                  - type: string
                                                                  - type: number
                                                                  - type: boolean
                                                              description: >-
                                                                Event properties this entry applies to.
                                                                Every key must equal the tracked
                                                                property, compared as strings.
                                                            factor:
                                                              type: number
                                                              exclusiveMinimum: 0
                                                              description: >-
                                                                Multiplies the matched rate. All
                                                                matching multipliers stack.
                                                            add:
                                                              type: number
                                                              description: >-
                                                                Added to the rate after every factor is
                                                                applied, in credits per billing-unit
                                                                group.
                                                          required:
                                                            - match
                                                          additionalProperties: false
                                                        description: >-
                                                          Named adjustments chosen by event
                                                          properties. Every match applies: factors
                                                          multiply, then adds are summed.
                                                      credit_cost:
                                                        type: number
                                                        minimum: 0
                                                        description: Credits consumed per billing-unit group.
                                                    required:
                                                      - metered_feature_id
                                                      - credit_cost
                                                    additionalProperties: false
                                                  - type: object
                                                    properties:
                                                      metered_feature_id:
                                                        type: string
                                                        minLength: 1
                                                        description: >-
                                                          ID of the metered feature to remove from
                                                          the credit system.
                                                      excluded:
                                                        const: true
                                                        description: >-
                                                          Removes this feature from the credit
                                                          system for customers on this plan.
                                                          Cannot be combined with a rate.
                                                    required:
                                                      - metered_feature_id
                                                      - excluded
                                                    additionalProperties: false
                                              description: >-
                                                For credit system features: merges into
                                                the feature's credit_schema by
                                                metered_feature_id for customers on this
                                                plan. A row with a rate overrides or
                                                adds that feature, a row with `excluded:
                                                true` removes it, and unlisted features
                                                keep the credit system's rate.
                                            markups:
                                              type: object
                                              properties:
                                                default_markup:
                                                  type: number
                                                  minimum: -100
                                                  description: >-
                                                    Default percentage markup for customers
                                                    on this plan. Use -100 to make usage
                                                    free.
                                                provider_markups:
                                                  anyOf:
                                                    - type: object
                                                      propertyNames:
                                                        type: string
                                                      additionalProperties:
                                                        type: object
                                                        properties:
                                                          markup:
                                                            type: number
                                                            minimum: -100
                                                        required:
                                                          - markup
                                                    - type: 'null'
                                                  description: >-
                                                    Per-provider markup percentages for
                                                    customers on this plan.
                                                model_markups:
                                                  anyOf:
                                                    - type: object
                                                      propertyNames:
                                                        type: string
                                                        pattern: .+\/.+
                                                      additionalProperties:
                                                        type: object
                                                        properties:
                                                          markup:
                                                            type: number
                                                            minimum: -100
                                                          input_cost:
                                                            type: number
                                                            minimum: 0
                                                          output_cost:
                                                            type: number
                                                            minimum: 0
                                                    - type: 'null'
                                                  description: >-
                                                    Per-model markup overrides for customers
                                                    on this plan.
                                              additionalProperties: false
                                              description: >-
                                                For AI credit system features: replaces
                                                the feature's markup chain entirely for
                                                customers on this plan. An unset level
                                                means no markup at that level rather
                                                than inheriting the feature's.
                                          additionalProperties: false
                                          description: >-
                                            Overrides fields of this item's feature
                                            for customers on this plan (e.g. a
                                            credit system's credit_schema).
                                      required:
                                        - feature_id
                                      title: PlanItem
                                      description: >-
                                        Configuration for a feature item in a
                                        plan, including usage limits, pricing,
                                        and rollover settings.
                                  remove_items:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        feature_id:
                                          type: string
                                          description: Match items linked to this feature.
                                        billing_method:
                                          enum:
                                            - prepaid
                                            - usage_based
                                          type: string
                                          description: >-
                                            Match items with this billing method
                                            (prepaid or usage_based).
                                        interval:
                                          anyOf:
                                            - enum:
                                                - one_off
                                                - week
                                                - month
                                                - quarter
                                                - semi_annual
                                                - year
                                              type: string
                                            - enum:
                                                - one_off
                                                - minute
                                                - hour
                                                - day
                                                - week
                                                - month
                                                - quarter
                                                - semi_annual
                                                - year
                                              type: string
                                          description: >-
                                            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:
                                          type: integer
                                          minimum: -9007199254740991
                                          maximum: 9007199254740991
                                          exclusiveMinimum: 0
                                          description: >-
                                            Match items with this interval_count.
                                            Disambiguates between items that share
                                            an interval but differ in count.
                                        included:
                                          type: number
                                          maximum: 10000000000000
                                          description: >-
                                            Match items whose grant equals this
                                            included usage. Omitted is a wildcard.
                                      title: PlanItemFilter
                                      description: >-
                                        Filter for matching plan items. All
                                        provided fields must match (AND).
                              - type: 'null'
                          metadata:
                            type: object
                            propertyNames:
                              type: string
                            additionalProperties: {}
                        required:
                          - license_plan_id
                      description: >-
                        License links to add or override for this customer,
                        keyed by license_plan_id. Omitted fields inherit the
                        plan catalog link (included defaults to 1 when the
                        license is not in the catalog). A bare entry restores
                        the license to pure catalog inheritance.
                    remove_licenses:
                      type: array
                      items:
                        type: object
                        properties:
                          license_plan_id:
                            type: string
                        required:
                          - license_plan_id
                      description: >-
                        License links to drop, keyed by license_plan_id.
                        Parallel to remove_items.
                  description: >-
                    Customize the plan to attach. Can override the price, items,
                    licenses, free trial, or a combination.
                invoice_mode:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                      description: >-
                        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:
                      type: boolean
                      default: false
                      description: >-
                        Deprecated: use the top-level enable_plan on attach,
                        billing.update and set_plans. If true, enables the plan
                        before the invoice is paid: once a draft is finalized,
                        now when the invoice is issued straight away, or before
                        a future starts_at.
                    finalize:
                      type: boolean
                      description: >-
                        Deprecated: use issue_method. true sends the invoice
                        (issue_method: send), false keeps it as a draft
                        (issue_method: draft). Defaults to true. Ignored when
                        issue_method is set.
                    issue_method:
                      enum:
                        - draft
                        - finalize
                        - send
                      type: string
                      description: >-
                        How far the invoice created now advances. draft leaves
                        it editable for manual review. finalize opens it without
                        Stripe emailing, reminding or charging (auto_advance
                        off), for invoices collected outside Stripe. send opens
                        it and lets Stripe email it. Defaults to send. Requires
                        enabled: true. With a future starts_at only send
                        applies: the invoice is created and sent when the plan
                        starts. Renewal invoices follow the customer's
                        config.renewal_issue_method.
                    invoice_template_id:
                      type: string
                      description: >-
                        ID of an invoice template (configured in billing
                        settings) whose footer (e.g. bank details) is applied to
                        the invoice.
                    net_terms_days:
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                      exclusiveMinimum: 0
                      description: >-
                        Number of days the customer has to pay the invoice
                        before it is due (Stripe days_until_due).
                    payment_method_types:
                      type: array
                      minItems: 1
                      items:
                        enum:
                          - card
                          - customer_balance
                          - us_bank_account
                          - sepa_debit
                          - bacs_debit
                          - acss_debit
                          - link
                        type: string
                      description: >-
                        Payment method types the customer can pay the invoice
                        with, e.g. card and us_bank_account. Overrides the org's
                        allowed payment methods.
                  required:
                    - enabled
                  description: >-
                    Invoice mode creates a draft or open invoice and sends it to
                    the customer, instead of charging their card immediately.
                    This uses Stripe's send_invoice collection method.
                enable_plan:
                  enum:
                    - on_payment
                    - on_finalize
                    - immediately
                  type: string
                  title: EnablePlan
                  description: >-
                    When the plan turns on. 'on_payment' (default) waits until
                    the invoice is paid or checkout completes. 'on_finalize'
                    turns it on once the invoice is finalized, before payment,
                    and needs invoice_mode. 'immediately' turns it on now, even
                    while the invoice is still a draft; voiding or deleting the
                    draft leaves the plan on. Takes precedence over the
                    deprecated enable_plan_immediately flags.
                proration_behavior:
                  enum:
                    - prorate_immediately
                    - none
                    - bill_difference
                  type: string
                  description: >-
                    How to handle proration when updating an existing
                    subscription. 'prorate_immediately' charges/credits prorated
                    amounts now, 'none' skips creating any charges,
                    'bill_difference' bills the larger of the full-period price
                    difference and the prorated amount (full difference on
                    upgrades, prorated credit on downgrades) now without
                    changing the billing cycle.
                redirect_mode:
                  enum:
                    - always
                    - if_required
                    - never
                  type: string
                  description: >-
                    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.
                  default: if_required
                subscription_id:
                  type: string
                  description: >-
                    A unique ID to identify this subscription. Can be used to
                    target specific subscriptions in update operations when a
                    customer has multiple products with the same plan.
                discounts:
                  type: array
                  items:
                    type: object
                    properties:
                      reward_id:
                        type: string
                        description: The ID of the reward to apply as a discount.
                      promotion_code:
                        type: string
                        description: The promotion code to apply as a discount.
                    title: AttachDiscount
                    description: >-
                      A discount to apply. Can be either a reward ID or a
                      promotion code.
                  description: >-
                    List of discounts to apply. Each discount can be an Autumn
                    reward ID, Stripe coupon ID, or Stripe promotion code.
                remove_discounts:
                  type: array
                  items:
                    type: object
                    properties:
                      reward_id:
                        type: string
                        description: The ID of the reward (or Stripe coupon) to remove.
                    required:
                      - reward_id
                    additionalProperties: false
                    title: RemoveDiscount
                    description: >-
                      A discount to remove from the subscription. Discounts that
                      are no longer applied are ignored.
                  description: >-
                    Discounts to remove from the subscription, by reward ID.
                    Discounts not listed are left unchanged.
                custom_line_items:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    properties:
                      amount:
                        type: number
                        description: >-
                          Amount in dollars for this line item (e.g. 10.50). Can
                          be negative for credits.
                      description:
                        type: string
                        description: Description for the line item.
                    required:
                      - amount
                      - description
                  description: >-
                    Custom line items that replace the auto-generated proration
                    invoice, or bill a standalone invoice when nothing else
                    changes. Only valid on an existing recurring subscription.
                remove_lines:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    properties:
                      plan_id:
                        type: string
                        description: >-
                          The plan whose lines to remove: one coming in, going
                          out, or already on the customer and billed by this
                          request.
                      entity_id:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: 'null'
                        description: >-
                          The entity the lines are billed to. Omit to inherit
                          the request's entity_id, or pass null for
                          customer-level.
                      direction:
                        enum:
                          - charge
                          - refund
                        type: string
                        description: >-
                          Only remove charges or only remove refunds (credits).
                          Omit to remove both.
                      price:
                        anyOf:
                          - const: true
                          - type: object
                            properties:
                              interval:
                                enum:
                                  - one_off
                                  - week
                                  - month
                                  - quarter
                                  - semi_annual
                                  - year
                                type: string
                                description: >-
                                  Only match the price billed on this interval.
                                  Needed when the same price exists on more than
                                  one interval.
                              interval_count:
                                type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                                exclusiveMinimum: 0
                                description: >-
                                  Only match the price billed every this many
                                  intervals.
                            additionalProperties: false
                        description: >-
                          Remove the base price line. Pass true, or an object to
                          narrow by interval.
                      feature_quantities:
                        type: array
                        items:
                          type: object
                          properties:
                            feature_id:
                              type: string
                              description: The feature whose line to remove.
                            billing_behavior:
                              enum:
                                - prepaid
                                - usage_based
                              type: string
                              description: >-
                                Which of the feature's prices to match:
                                'prepaid' or 'usage_based'.
                            interval:
                              enum:
                                - one_off
                                - week
                                - month
                                - quarter
                                - semi_annual
                                - year
                              type: string
                              description: >-
                                Only match the price billed on this interval.
                                Needed when the same price exists on more than
                                one interval.
                            interval_count:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                              exclusiveMinimum: 0
                              description: >-
                                Only match the price billed every this many
                                intervals.
                          required:
                            - feature_id
                            - billing_behavior
                          additionalProperties: false
                      license_quantities:
                        type: array
                        items:
                          type: object
                          properties:
                            license_plan_id:
                              type: string
                              description: The license plan linked to the parent plan.
                            price:
                              anyOf:
                                - const: true
                                - type: object
                                  properties:
                                    interval:
                                      enum:
                                        - one_off
                                        - week
                                        - month
                                        - quarter
                                        - semi_annual
                                        - year
                                      type: string
                                      description: >-
                                        Only match the price billed on this
                                        interval. Needed when the same price
                                        exists on more than one interval.
                                    interval_count:
                                      type: integer
                                      minimum: -9007199254740991
                                      maximum: 9007199254740991
                                      exclusiveMinimum: 0
                                      description: >-
                                        Only match the price billed every this
                                        many intervals.
                                  additionalProperties: false
                              description: >-
                                Remove the base price line. Pass true, or an
                                object to narrow by interval.
                            feature_quantities:
                              type: array
                              items:
                                type: object
                                properties:
                                  feature_id:
                                    type: string
                                    description: The feature whose line to remove.
                                  billing_behavior:
                                    enum:
                                      - prepaid
                                      - usage_based
                                    type: string
                                    description: >-
                                      Which of the feature's prices to match:
                                      'prepaid' or 'usage_based'.
                                  interval:
                                    enum:
                                      - one_off
                                      - week
                                      - month
                                      - quarter
                                      - semi_annual
                                      - year
                                    type: string
                                    description: >-
                                      Only match the price billed on this
                                      interval. Needed when the same price
                                      exists on more than one interval.
                                  interval_count:
                                    type: integer
                                    minimum: -9007199254740991
                                    maximum: 9007199254740991
                                    exclusiveMinimum: 0
                                    description: >-
                                      Only match the price billed every this
                                      many intervals.
                                required:
                                  - feature_id
                                  - billing_behavior
                                additionalProperties: false
                          required:
                            - license_plan_id
                          additionalProperties: false
                    required:
                      - plan_id
                    additionalProperties: false
                    title: RemoveLine
                    description: >-
                      Removes lines Autumn generated for this invoice. With no
                      price, feature_quantities or license_quantities, every
                      line of the plan is removed.
                  description: >-
                    Lines to remove from the invoice this request creates. Never
                    changes the subscription or later invoices.
                add_lines:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    properties:
                      amount:
                        type: number
                        description: >-
                          Amount in dollars for this line item (e.g. 10.50). Can
                          be negative for credits.
                      description:
                        type: string
                        description: Description for the line item.
                      period_start:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                        description: >-
                          Start of the period this charge covers, in
                          milliseconds. Printed on the line only; a custom line
                          never inherits the invoice's period.
                      period_end:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                        description: >-
                          End of the period this charge covers, in milliseconds.
                          Given together with period_start.
                    required:
                      - amount
                      - description
                    title: AddLine
                    description: >-
                      A line added to this invoice. The amount is billed as
                      passed; the period is only printed on the line.
                  description: >-
                    Lines to add to the invoice this request creates. Never
                    changes the subscription or later invoices.
                cancel_action:
                  enum:
                    - cancel_immediately
                    - cancel_end_of_cycle
                    - uncancel
                  type: string
                  description: >-
                    Action to perform for cancellation. 'cancel_immediately'
                    cancels now with prorated refund, 'cancel_end_of_cycle'
                    cancels at period end, 'uncancel' reverses a pending
                    cancellation.
                billing_cycle_anchor:
                  anyOf:
                    - const: now
                    - type: integer
                      minimum: 0
                      maximum: 9007199254740991
                  description: >-
                    Reset the billing cycle immediately with 'now', or schedule
                    a reset at a future Unix timestamp in milliseconds.
                no_billing_changes:
                  type: boolean
                  description: >-
                    If true, the subscription is updated internally without
                    applying billing changes in Stripe.
                refund_last_payment:
                  enum:
                    - prorated
                    - full
                  type: string
                  title: RefundLastPayment
                  description: >-
                    Controls how the last payment is refunded on immediate
                    cancellation. 'prorated' refunds the unused portion, 'full'
                    refunds the entire last payment.
                subscription_params:
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                  title: SubscriptionParams
                  description: >-
                    Additional parameters to pass into the Stripe subscription
                    update or cancel call. Fields Autumn manages itself are
                    rejected with a 400; use invoice_mode to bill by invoice.
                recalculate_balances:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                      description: >-
                        If true, recalculates balances during the subscription
                        update. Only applicable when updating feature
                        quantities.
                  required:
                    - enabled
                  description: >-
                    Controls whether balances should be recalculated during the
                    subscription update.
                carry_over_usages:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                      description: Whether to carry over usages from the previous plan.
                    feature_ids:
                      type: array
                      items:
                        type: string
                      description: >-
                        The IDs of the features to carry over usages for. If
                        left undefined, all consumable features will be carried
                        over.
                  required:
                    - enabled
                  description: Whether to carry over usages from the previous plan.
                license_quantities:
                  type: array
                  items:
                    type: object
                    properties:
                      license_plan_id:
                        type: string
                        description: The license plan to set seat quantity for.
                      quantity:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                        description: >-
                          Total seats for the license, inclusive of the plan's
                          included amount — seats beyond it are paid.
                    required:
                      - license_plan_id
                      - quantity
                  description: >-
                    Total seat quantities (inclusive of the license's included
                    count) per license plan offered by this plan. Licenses not
                    listed keep their current paid quantity.
              required:
                - customer_id
              title: PreviewUpdateParams
              examples:
                - customer_id: cus_123
                  plan_id: pro_plan
                  feature_quantities:
                    - feature_id: seats
                      quantity: 15
            example:
              customer_id: cus_123
              plan_id: pro_plan
              feature_quantities:
                - feature_id: seats
                  quantity: 15
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_id:
                    type: string
                    description: The ID of the customer.
                  line_items:
                    type: array
                    items:
                      type: object
                      properties:
                        display_name:
                          type: string
                          description: >-
                            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:
                          type: string
                          description: A detailed description of the line item.
                        subtotal:
                          type: number
                          description: >-
                            The amount before discounts and tax for this line
                            item.
                        total:
                          type: number
                          description: >-
                            The final amount after discounts and tax for this
                            line item.
                        discounts:
                          type: array
                          items:
                            type: object
                            properties:
                              amount_off:
                                type: number
                              percent_off:
                                type: number
                              reward_id:
                                type: string
                              reward_name:
                                type: string
                            required:
                              - amount_off
                          default: []
                          description: List of discounts applied to this line item.
                        plan_id:
                          type: string
                          description: The ID of the plan that this line item belongs to.
                        feature_id:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: >-
                            The ID of the feature that this line item belongs
                            to.
                        period:
                          type: object
                          properties:
                            start:
                              type: number
                              description: >-
                                The start of the period in milliseconds since
                                the Unix epoch.
                            end:
                              type: number
                              description: >-
                                The end of the period in milliseconds since the
                                Unix epoch.
                          required:
                            - start
                            - end
                          description: >-
                            The period of time that this line item is being
                            charged for.
                        quantity:
                          type: number
                          description: The quantity of the line item.
                      required:
                        - display_name
                        - description
                        - subtotal
                        - total
                        - plan_id
                        - feature_id
                        - quantity
                    description: List of line items for the current billing period.
                  subtotal:
                    type: number
                    description: >-
                      The total amount before discounts and tax for the current
                      billing period.
                  total:
                    type: number
                    description: >-
                      The final amount after discounts and tax for the current
                      billing period.
                  currency:
                    type: string
                    description: >-
                      The three-letter ISO currency code. All amounts are in the
                      currency's major unit (e.g., dollars for USD).
                  immediate_invoice:
                    type: object
                    properties:
                      type:
                        enum:
                          - none
                          - zero_amount
                          - charge
                          - credit
                        type: string
                        description: >-
                          What the invoice created now bills. 'none' when the
                          change creates no invoice now. 'zero_amount' when an
                          invoice is created but nothing was billed, such as a
                          trial or a usage-only plan. 'charge' when something
                          was billed, even if discounts or credits bring the
                          amount due to zero. 'credit' when the invoice total is
                          negative and becomes customer credit.
                      issue_method:
                        anyOf:
                          - enum:
                              - draft
                              - finalize
                              - send
                              - charge_automatically
                            type: string
                          - type: 'null'
                        description: >-
                          How the invoice is issued, matching
                          invoice_mode.issue_method: 'draft', 'finalize' or
                          'send'. 'charge_automatically' when the card on file
                          is charged, or the customer pays at checkout. Null
                          when type is 'none'.
                      plan_activates:
                        enum:
                          - now
                          - on_finalize
                          - on_payment
                        type: string
                        description: >-
                          When the change takes effect. 'now' when it applies as
                          soon as the request succeeds, 'on_finalize' when it
                          waits for this draft invoice to be finalized,
                          'on_payment' when it waits for the invoice to be paid
                          or the checkout to complete.
                    required:
                      - type
                      - issue_method
                      - plan_activates
                    title: PreviewImmediateInvoice
                    description: >-
                      The invoice this change creates right away, if any.
                      Renewals are described by next_cycle.
                  resets_usage:
                    type: boolean
                    description: >-
                      True when this change clears the customer's usage
                      balances, so the approver can see usage will reset.
                  next_cycle:
                    type: object
                    properties:
                      starts_at:
                        type: number
                        description: >-
                          Unix timestamp (milliseconds) when the next billing
                          cycle starts.
                      subtotal:
                        type: number
                        description: >-
                          The total amount before discounts and tax for the next
                          cycle.
                      total:
                        type: number
                        description: >-
                          The final amount after discounts and tax for the next
                          cycle.
                      line_items:
                        type: array
                        items:
                          type: object
                          properties:
                            display_name:
                              type: string
                              description: >-
                                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:
                              type: string
                              description: A detailed description of the line item.
                            subtotal:
                              type: number
                              description: >-
                                The amount before discounts and tax for this
                                line item.
                            total:
                              type: number
                              description: >-
                                The final amount after discounts and tax for
                                this line item.
                            discounts:
                              type: array
                              items:
                                type: object
                                properties:
                                  amount_off:
                                    type: number
                                  percent_off:
                                    type: number
                                  reward_id:
                                    type: string
                                  reward_name:
                                    type: string
                                required:
                                  - amount_off
                              default: []
                              description: List of discounts applied to this line item.
                            plan_id:
                              type: string
                              description: >-
                                The ID of the plan that this line item belongs
                                to.
                            feature_id:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                The ID of the feature that this line item
                                belongs to.
                            period:
                              type: object
                              properties:
                                start:
                                  type: number
                                  description: >-
                                    The start of the period in milliseconds
                                    since the Unix epoch.
                                end:
                                  type: number
                                  description: >-
                                    The end of the period in milliseconds since
                                    the Unix epoch.
                              required:
                                - start
                                - end
                              description: >-
                                The period of time that this line item is being
                                charged for.
                            quantity:
                              type: number
                              description: The quantity of the line item.
                          required:
                            - display_name
                            - description
                            - subtotal
                            - total
                            - plan_id
                            - feature_id
                            - quantity
                        description: List of line items for the next billing cycle.
                      usage_line_items:
                        type: array
                        items:
                          type: object
                          properties:
                            display_name:
                              type: string
                              description: >-
                                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:
                              type: string
                              description: >-
                                The ID of the plan that this line item belongs
                                to.
                            feature_id:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: >-
                                The ID of the feature that this line item
                                belongs to.
                            period:
                              type: object
                              properties:
                                start:
                                  type: number
                                  description: >-
                                    The start of the period in milliseconds
                                    since the Unix epoch.
                                end:
                                  type: number
                                  description: >-
                                    The end of the period in milliseconds since
                                    the Unix epoch.
                              required:
                                - start
                                - end
                              description: >-
                                The period of time that this line item is being
                                charged for.
                          required:
                            - display_name
                            - plan_id
                            - feature_id
                        description: >-
                          List of line items for usage-based features in the
                          next cycle.
                    required:
                      - starts_at
                      - subtotal
                      - total
                      - line_items
                      - usage_line_items
                    description: >-
                      Preview of the next billing cycle, if applicable. This
                      shows what the customer will be charged in subsequent
                      cycles.
                  requires_payment_method:
                    type: boolean
                    description: >-
                      True when this request can't be charged automatically
                      because the customer has no payment method. Add one, or
                      send an invoice with invoice_mode.
                  expand:
                    type: array
                    items:
                      type: string
                    description: Expand the response with additional data.
                  incoming:
                    type: array
                    items:
                      type: object
                      properties:
                        plan_id:
                          type: string
                          description: The ID of the plan affected by this preview change.
                        plan:
                          $ref: '#/components/schemas/Plan'
                          description: >-
                            The full plan object if it was expanded in the
                            response.
                        feature_quantities:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: >-
                                  The ID of the adjustable feature included in
                                  this change.
                              quantity:
                                type: number
                                description: >-
                                  The quantity that will apply for this feature
                                  in the change.
                            required:
                              - feature_id
                              - quantity
                          description: >-
                            The feature quantity selections associated with this
                            plan change.
                        effective_at:
                          anyOf:
                            - type: number
                            - type: 'null'
                          description: >-
                            When this change takes effect, in milliseconds since
                            the Unix epoch, or null if it applies immediately.
                        canceled_at:
                          anyOf:
                            - type: number
                            - type: 'null'
                          description: >-
                            When this plan was canceled, in milliseconds since
                            the Unix epoch, or null if it is not canceled.
                        expires_at:
                          anyOf:
                            - type: number
                            - type: 'null'
                          description: >-
                            When this plan expires, in milliseconds since the
                            Unix epoch, or null if it does not expire.
                      required:
                        - plan_id
                        - feature_quantities
                        - effective_at
                        - canceled_at
                        - expires_at
                    description: Products or subscription changes being added or updated.
                  outgoing:
                    type: array
                    items:
                      type: object
                      properties:
                        plan_id:
                          type: string
                          description: The ID of the plan affected by this preview change.
                        plan:
                          $ref: '#/components/schemas/Plan'
                          description: >-
                            The full plan object if it was expanded in the
                            response.
                        feature_quantities:
                          type: array
                          items:
                            type: object
                            properties:
                              feature_id:
                                type: string
                                description: >-
                                  The ID of the adjustable feature included in
                                  this change.
                              quantity:
                                type: number
                                description: >-
                                  The quantity that will apply for this feature
                                  in the change.
                            required:
                              - feature_id
                              - quantity
                          description: >-
                            The feature quantity selections associated with this
                            plan change.
                        effective_at:
                          anyOf:
                            - type: number
                            - type: 'null'
                          description: >-
                            When this change takes effect, in milliseconds since
                            the Unix epoch, or null if it applies immediately.
                        canceled_at:
                          anyOf:
                            - type: number
                            - type: 'null'
                          description: >-
                            When this plan was canceled, in milliseconds since
                            the Unix epoch, or null if it is not canceled.
                        expires_at:
                          anyOf:
                            - type: number
                            - type: 'null'
                          description: >-
                            When this plan expires, in milliseconds since the
                            Unix epoch, or null if it does not expire.
                      required:
                        - plan_id
                        - feature_quantities
                        - effective_at
                        - canceled_at
                        - expires_at
                    description: Products or subscription changes being removed or ended.
                  intent:
                    enum:
                      - update_plan
                      - update_quantity
                      - cancel_immediately
                      - cancel_end_of_cycle
                      - uncancel
                      - none
                    type: string
                  tax:
                    type: object
                    properties:
                      total:
                        type: number
                        description: Total tax amount in major currency units.
                      amount_inclusive:
                        type: number
                        description: Tax included in line item subtotals.
                      amount_exclusive:
                        type: number
                        description: Tax added on top of subtotals.
                      currency:
                        type: string
                        description: Three-letter currency code.
                      status:
                        enum:
                          - complete
                          - incomplete
                          - requires_location
                        type: string
                        description: >-
                          Calculation status. 'complete' when tax was
                          calculated, 'incomplete' when the calculation errored,
                          'requires_location' when the customer has no billing
                          address to tax against.
                    required:
                      - total
                      - amount_inclusive
                      - amount_exclusive
                      - currency
                      - status
                    description: >-
                      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.
                  invoice_credits:
                    type: object
                    properties:
                      balance:
                        type: number
                        description: >-
                          Stripe customer credit balance available, expressed as
                          a positive number in major currency units.
                      applied:
                        type: number
                        description: >-
                          How much of that balance this invoice consumes, capped
                          at its total. The rest stays on the customer.
                      currency:
                        type: string
                        description: Three-letter currency code.
                    required:
                      - balance
                      - currency
                    description: Stripe customer invoice credits preview.
                required:
                  - customer_id
                  - line_items
                  - subtotal
                  - total
                  - currency
                  - immediate_invoice
                  - incoming
                  - outgoing
                  - intent
                examples:
                  - customerId: charles
                    lineItems:
                      - display_name: Pro seed
                        description: Pro seed (from 18 Feb 2026 to 18 Mar 2026)
                        subtotal: 20
                        total: 20
                        discounts: []
                    subtotal: 20
                    total: 20
                    currency: usd
              example:
                customerId: charles
                lineItems:
                  - display_name: Pro seed
                    description: Pro seed (from 18 Feb 2026 to 18 Mar 2026)
                    subtotal: 20
                    total: 20
                    discounts: []
                subtotal: 20
                total: 20
                currency: usd
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.billing.previewUpdate({
              customerId: "cus_123",
              planId: "pro_plan",
              featureQuantities: [
                {
                  featureId: "seats",
                  quantity: 15,
                },
              ],
            });
        - lang: python
          label: Python (SDK)
          source: |-
            from autumn_sdk import Autumn

            autumn = Autumn(secret_key="am_sk_test...")

            res = autumn.billing.preview_update(
                customer_id="cus_123",
                plan_id="pro_plan",
                feature_quantities=[
                    {
                        "feature_id": "seats",
                        "quantity": 15,
                    },
                ],
                redirect_mode="if_required",
            )
components:
  schemas:
    CreditDimensionInput:
      anyOf:
        - type: object
          properties:
            match:
              type: object
              propertyNames:
                type: string
              additionalProperties:
                anyOf:
                  - type: string
                  - type: number
                  - type: boolean
              description: >-
                Event properties this entry applies to. Every key must equal the
                tracked property, compared as strings.
            priority:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: >-
                Breaks ties between dimensions that match the same number of
                keys. Higher wins.
            tier_behavior:
              const: graduated
            tiers:
              type: array
              minItems: 1
              items:
                type: object
                properties:
                  to:
                    anyOf:
                      - type: number
                        exclusiveMinimum: 0
                      - enum:
                          - inf
                        type: string
                    description: >-
                      Inclusive upper usage boundary for this graduated tier.
                      The final tier must be 'inf'.
                  credit_cost:
                    type: number
                    minimum: 0
                    description: Credits consumed per billing-unit group within this tier.
                required:
                  - to
                  - credit_cost
          required:
            - match
            - tier_behavior
            - tiers
          additionalProperties: false
        - type: object
          properties:
            match:
              type: object
              propertyNames:
                type: string
              additionalProperties:
                anyOf:
                  - type: string
                  - type: number
                  - type: boolean
              description: >-
                Event properties this entry applies to. Every key must equal the
                tracked property, compared as strings.
            priority:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: >-
                Breaks ties between dimensions that match the same number of
                keys. Higher wins.
            credit_cost:
              type: number
              minimum: 0
              description: >-
                Credits consumed per billing-unit group when this dimension
                matches.
          required:
            - match
            - credit_cost
          additionalProperties: false
    Plan:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the plan.
        name:
          type: string
          description: Display name of the plan.
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional description of the plan.
        group:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Group identifier for organizing related plans. Plans in the same
            group are mutually exclusive.
        version:
          type: number
          description: >-
            Version number of the plan. Incremented when plan configuration
            changes.
        version_slug:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            User-facing version identity. Defaults to v{n} when the version is
            minted.
        active:
          type: boolean
          description: >-
            Whether this is the active version of the plan. At most one version
            is active.
        add_on:
          type: boolean
          description: >-
            Whether this is an add-on plan that can be attached alongside a main
            plan.
        auto_enable:
          type: boolean
          description: >-
            If true, this plan is automatically attached when a customer is
            created. Used for free plans.
        price:
          anyOf:
            - type: object
              properties:
                amount:
                  type: number
                  description: >-
                    Base price amount for the plan, in major currency units
                    (e.g. dollars).
                additional_currencies:
                  type: array
                  items:
                    type: object
                    properties:
                      currency:
                        type: string
                        description: >-
                          Three-letter Stripe-supported currency code (e.g.
                          'eur', 'gbp').
                      amount:
                        type: number
                        description: >-
                          Price amount in this currency. Set explicitly per
                          currency, not converted from the base amount.
                    required:
                      - currency
                      - amount
                  description: >-
                    Base price amounts in additional currencies. The base
                    'amount' is in the org's default currency.
                interval:
                  enum:
                    - one_off
                    - week
                    - month
                    - quarter
                    - semi_annual
                    - year
                  type: string
                  description: Billing interval (e.g. 'month', 'year').
                interval_count:
                  type: number
                  description: Number of intervals per billing cycle. Defaults to 1.
                display:
                  type: object
                  properties:
                    primary_text:
                      type: string
                      description: Main display text (e.g. '$10' or '100 messages').
                    secondary_text:
                      type: string
                      description: >-
                        Secondary display text (e.g. 'per month' or 'then $0.5
                        per 100').
                  required:
                    - primary_text
                  description: Display text for showing this price in pricing pages.
                processors:
                  type: object
                  properties:
                    stripe:
                      anyOf:
                        - type: object
                          properties:
                            price_id:
                              type: string
                              description: >-
                                Stripe price ID. For prepaid with included > 0
                                this is the V2 price.
                          required:
                            - price_id
                        - type: 'null'
                  x-atmn-mapping: true
                  description: >-
                    Payment processors this base price is connected to. Omitted
                    when unset.
              required:
                - amount
                - interval
            - type: 'null'
          description: >-
            Base recurring price for the plan. Null for free plans or usage-only
            plans.
        items:
          type: array
          items:
            type: object
            properties:
              threshold_billing:
                anyOf:
                  - type: object
                    properties:
                      threshold:
                        type: number
                        exclusiveMinimum: 0
                    required:
                      - threshold
                  - type: 'null'
                description: >-
                  Bills this many feature units when outstanding overage reaches
                  it.
              feature_id:
                type: string
                description: The ID of the feature this item configures.
              feature:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      The ID of the feature, used to refer to it in other API
                      calls like /track or /check.
                  name:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: The name of the feature.
                  type:
                    enum:
                      - static
                      - boolean
                      - single_use
                      - continuous_use
                      - credit_system
                      - ai_credit_system
                    type: string
                    description: The type of the feature
                  display:
                    anyOf:
                      - type: object
                        properties:
                          singular:
                            type: string
                            description: The singular display name for the feature.
                          plural:
                            type: string
                            description: The plural display name for the feature.
                        required:
                          - singular
                          - plural
                      - type: 'null'
                    description: Singular and plural display names for the feature.
                  credit_schema:
                    anyOf:
                      - type: array
                        items:
                          type: object
                          properties:
                            metered_feature_id:
                              type: string
                              description: >-
                                The ID of the metered feature (should be a
                                single_use feature).
                            credit_cost:
                              type: number
                              description: The credit cost of the metered feature.
                          required:
                            - metered_feature_id
                            - credit_cost
                      - type: 'null'
                    description: Credit cost schema for credit system features.
                  archived:
                    anyOf:
                      - type: boolean
                      - type: 'null'
                    description: Whether or not the feature is archived.
                required:
                  - id
                  - type
                description: The full feature object if expanded.
              included:
                type: number
                description: >-
                  Number of free units included. For consumable features,
                  balance resets to this number each interval.
              unlimited:
                type: boolean
                description: Whether the customer has unlimited access to this feature.
              pooled:
                type: boolean
                default: false
                description: >-
                  Whether entity-level grants contribute to a shared customer
                  balance.
              reset:
                anyOf:
                  - type: object
                    properties:
                      interval:
                        enum:
                          - one_off
                          - minute
                          - hour
                          - day
                          - week
                          - month
                          - quarter
                          - semi_annual
                          - year
                        type: string
                        description: >-
                          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:
                        type: number
                        description: Number of intervals between resets. Defaults to 1.
                    required:
                      - interval
                  - type: 'null'
                description: >-
                  Reset configuration for consumable features. Null for
                  non-consumable features like seats where usage persists across
                  billing cycles.
              price:
                anyOf:
                  - type: object
                    properties:
                      amount:
                        type: number
                        description: >-
                          Price per billing_units after included usage is
                          consumed. Mutually exclusive with tiers.
                      additional_currencies:
                        type: array
                        items:
                          type: object
                          properties:
                            currency:
                              type: string
                              description: >-
                                Three-letter Stripe-supported currency code
                                (e.g. 'eur', 'gbp').
                            amount:
                              type: number
                              description: >-
                                Price amount in this currency. Set explicitly
                                per currency, not converted from the base
                                amount.
                          required:
                            - currency
                            - amount
                        description: >-
                          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).
                      tiers:
                        type: array
                        items:
                          type: object
                          properties:
                            to:
                              anyOf:
                                - type: number
                                - const: inf
                            amount:
                              type: number
                            flat_amount:
                              type: number
                            additional_currencies:
                              type: array
                              items:
                                type: object
                                properties:
                                  currency:
                                    type: string
                                    description: >-
                                      Three-letter Stripe-supported currency
                                      code (e.g. 'eur', 'gbp').
                                  amount:
                                    type: number
                                    description: >-
                                      Per-unit amount for this tier in this
                                      currency.
                                  flat_amount:
                                    type: number
                                    description: >-
                                      Flat amount for this tier in this
                                      currency, if the tier uses one.
                                required:
                                  - currency
                          required:
                            - to
                            - amount
                        description: >-
                          Tiered pricing configuration. Each tier's 'to'
                          INCLUDES the included amount. Either 'tiers' or
                          'amount' is required.
                      tier_behavior:
                        enum:
                          - graduated
                          - volume
                        type: string
                        description: >-
                          How tiers price usage. 'graduated' (default) charges
                          each unit at the rate of the tier it falls in.
                          'volume' picks one tier from total usage. On
                          usage-based items it bills only usage past the
                          included amount, at the rate of the tier total usage
                          reaches, plus its flat_amount. On prepaid items it
                          charges every unit, the included ones too, at that
                          tier's rate plus its flat_amount.
                      interval:
                        enum:
                          - one_off
                          - week
                          - month
                          - quarter
                          - semi_annual
                          - year
                        type: string
                        description: >-
                          Billing interval for this price. For usage-based
                          features, should match reset.interval, unless the
                          price has graduated tiers and reset.interval is a
                          whole multiple of it: each invoice then bills only the
                          newly owed usage, at the tier the reset period has
                          reached.
                      interval_count:
                        type: number
                        description: Number of intervals per billing cycle. Defaults to 1.
                      billing_units:
                        type: number
                        description: >-
                          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:
                        enum:
                          - prepaid
                          - usage_based
                        type: string
                        description: >-
                          'prepaid' for features like seats where customers pay
                          upfront, 'usage_based' for pay-as-you-go after
                          included usage.
                      max_purchase:
                        anyOf:
                          - type: number
                          - type: 'null'
                        description: >-
                          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.
                      processors:
                        type: object
                        properties:
                          stripe:
                            anyOf:
                              - type: object
                                properties:
                                  price_id:
                                    type: string
                                    description: >-
                                      Stripe price ID. For prepaid with included
                                      > 0 this is the V2 price.
                                required:
                                  - price_id
                              - type: 'null'
                        x-atmn-mapping: true
                        description: >-
                          Payment processors this item price is connected to.
                          Omitted when unset.
                    required:
                      - interval
                      - billing_units
                      - billing_method
                      - max_purchase
                  - type: 'null'
                description: >-
                  Pricing configuration for usage beyond included units. Null if
                  feature is entirely free.
              display:
                type: object
                properties:
                  primary_text:
                    type: string
                    description: Main display text (e.g. '$10' or '100 messages').
                  secondary_text:
                    type: string
                    description: >-
                      Secondary display text (e.g. 'per month' or 'then $0.5 per
                      100').
                required:
                  - primary_text
                description: Display text for showing this item in pricing pages.
              rollover:
                type: object
                properties:
                  max:
                    anyOf:
                      - type: number
                      - type: 'null'
                    description: Maximum rollover units. Null for unlimited rollover.
                  max_percentage:
                    anyOf:
                      - type: number
                      - type: 'null'
                    description: >-
                      Maximum rollover as a percentage (0-100) of included +
                      prepaid grant. Mutually exclusive with max.
                  expiry_duration_type:
                    enum:
                      - month
                      - forever
                    type: string
                    description: When rolled over units expire.
                  expiry_duration_length:
                    type: number
                    description: Number of periods before expiry.
                required:
                  - max
                  - expiry_duration_type
                description: >-
                  Rollover configuration for unused units. If set, unused
                  included units roll over to the next period.
              expiry:
                anyOf:
                  - type: object
                    properties:
                      duration:
                        enum:
                          - day
                          - week
                          - month
                          - year
                        type: string
                      length:
                        type: number
                    required:
                      - duration
                      - length
                  - type: 'null'
                description: >-
                  Purchased units expire this long after each purchase. One-off
                  prepaid consumable items only.
              feature_override:
                type: object
                properties:
                  credit_schema:
                    type: array
                    items:
                      anyOf:
                        - type: object
                          properties:
                            metered_feature_id:
                              type: string
                              minLength: 1
                              description: >-
                                ID of the metered feature that draws from this
                                credit system.
                            billing_units:
                              type: number
                              exclusiveMinimum: 0
                              description: >-
                                Number of metered-feature units priced together.
                                Defaults to one when omitted.
                            dimensions:
                              type: object
                              propertyNames:
                                type: string
                                minLength: 1
                                maxLength: 64
                              additionalProperties:
                                $ref: '#/components/schemas/CreditDimension'
                              description: >-
                                Named rates chosen by event properties. The most
                                specific match sets the rate; with no match the
                                item's own rate applies.
                            multipliers:
                              type: object
                              propertyNames:
                                type: string
                                minLength: 1
                                maxLength: 64
                              additionalProperties:
                                type: object
                                properties:
                                  match:
                                    type: object
                                    propertyNames:
                                      type: string
                                    additionalProperties:
                                      type: string
                                    description: >-
                                      Event properties this entry applies to.
                                      Every key must equal the tracked property,
                                      compared as strings.
                                  factor:
                                    type: number
                                    exclusiveMinimum: 0
                                    description: >-
                                      Multiplies the matched rate. All matching
                                      multipliers stack.
                                  add:
                                    type: number
                                    description: >-
                                      Added to the rate after every factor is
                                      applied, in credits per billing-unit
                                      group.
                                required:
                                  - match
                                additionalProperties: false
                              description: >-
                                Named adjustments chosen by event properties.
                                Every match applies: factors multiply, then adds
                                are summed.
                            tier_behavior:
                              const: graduated
                            tiers:
                              type: array
                              minItems: 1
                              items:
                                type: object
                                properties:
                                  to:
                                    anyOf:
                                      - type: number
                                        exclusiveMinimum: 0
                                      - enum:
                                          - inf
                                        type: string
                                    description: >-
                                      Inclusive upper usage boundary for this
                                      graduated tier. The final tier must be
                                      'inf'.
                                  credit_cost:
                                    type: number
                                    minimum: 0
                                    description: >-
                                      Credits consumed per billing-unit group
                                      within this tier.
                                required:
                                  - to
                                  - credit_cost
                          required:
                            - metered_feature_id
                            - tier_behavior
                            - tiers
                          additionalProperties: false
                        - type: object
                          properties:
                            metered_feature_id:
                              type: string
                              minLength: 1
                              description: >-
                                ID of the metered feature that draws from this
                                credit system.
                            billing_units:
                              type: number
                              exclusiveMinimum: 0
                              description: >-
                                Number of metered-feature units priced together.
                                Defaults to one when omitted.
                            dimensions:
                              type: object
                              propertyNames:
                                type: string
                                minLength: 1
                                maxLength: 64
                              additionalProperties:
                                $ref: '#/components/schemas/CreditDimension'
                              description: >-
                                Named rates chosen by event properties. The most
                                specific match sets the rate; with no match the
                                item's own rate applies.
                            multipliers:
                              type: object
                              propertyNames:
                                type: string
                                minLength: 1
                                maxLength: 64
                              additionalProperties:
                                type: object
                                properties:
                                  match:
                                    type: object
                                    propertyNames:
                                      type: string
                                    additionalProperties:
                                      type: string
                                    description: >-
                                      Event properties this entry applies to.
                                      Every key must equal the tracked property,
                                      compared as strings.
                                  factor:
                                    type: number
                                    exclusiveMinimum: 0
                                    description: >-
                                      Multiplies the matched rate. All matching
                                      multipliers stack.
                                  add:
                                    type: number
                                    description: >-
                                      Added to the rate after every factor is
                                      applied, in credits per billing-unit
                                      group.
                                required:
                                  - match
                                additionalProperties: false
                              description: >-
                                Named adjustments chosen by event properties.
                                Every match applies: factors multiply, then adds
                                are summed.
                            credit_cost:
                              type: number
                              minimum: 0
                              description: Credits consumed per billing-unit group.
                          required:
                            - metered_feature_id
                            - credit_cost
                          additionalProperties: false
                        - type: object
                          properties:
                            metered_feature_id:
                              type: string
                              minLength: 1
                              description: >-
                                ID of the metered feature to remove from the
                                credit system.
                            excluded:
                              const: true
                              description: >-
                                Removes this feature from the credit system for
                                customers on this plan. Cannot be combined with
                                a rate.
                          required:
                            - metered_feature_id
                            - excluded
                          additionalProperties: false
                    description: >-
                      For credit system features: merges into the feature's
                      credit_schema by metered_feature_id for customers on this
                      plan. A row with a rate overrides or adds that feature, a
                      row with `excluded: true` removes it, and unlisted
                      features keep the credit system's rate.
                  markups:
                    type: object
                    properties:
                      default_markup:
                        type: number
                        minimum: -100
                        description: >-
                          Default percentage markup for customers on this plan.
                          Use -100 to make usage free.
                      provider_markups:
                        anyOf:
                          - type: object
                            propertyNames:
                              type: string
                            additionalProperties:
                              type: object
                              properties:
                                markup:
                                  type: number
                                  minimum: -100
                              required:
                                - markup
                          - type: 'null'
                        description: >-
                          Per-provider markup percentages for customers on this
                          plan.
                      model_markups:
                        anyOf:
                          - type: object
                            propertyNames:
                              type: string
                              pattern: .+\/.+
                            additionalProperties:
                              type: object
                              properties:
                                markup:
                                  type: number
                                  minimum: -100
                                input_cost:
                                  type: number
                                  minimum: 0
                                output_cost:
                                  type: number
                                  minimum: 0
                          - type: 'null'
                        description: Per-model markup overrides for customers on this plan.
                    additionalProperties: false
                    description: >-
                      For AI credit system features: replaces the feature's
                      markup chain entirely for customers on this plan. An unset
                      level means no markup at that level rather than inheriting
                      the feature's.
                additionalProperties: false
                description: >-
                  Overrides fields of this item's feature for customers on this
                  plan (e.g. a credit system's credit_schema).
            required:
              - feature_id
              - included
              - unlimited
              - reset
              - price
          description: >-
            Feature configurations included in this plan. Each item defines
            included units, pricing, and reset behavior for a feature.
        processors:
          type: object
          properties:
            stripe:
              anyOf:
                - type: object
                  properties:
                    product_id:
                      type: string
                      description: Stripe product ID this plan is billed under.
                    additional_product_ids:
                      type: array
                      items:
                        type: string
                      description: Extra Stripe product IDs aliased to this plan.
                  required:
                    - product_id
                - type: 'null'
            revenuecat:
              anyOf:
                - type: object
                  properties:
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          product_id:
                            type: string
                            description: >-
                              RevenueCat product ID that grants this plan when
                              purchased.
                          feature_quantities:
                            type: array
                            items:
                              type: object
                              properties:
                                feature_id:
                                  type: string
                                quantity:
                                  type: number
                                  minimum: 0
                              required:
                                - feature_id
                            description: >-
                              Prepaid quantities granted when this specific
                              RevenueCat product is purchased, in feature units.
                        required:
                          - product_id
                      description: >-
                        Every RevenueCat product that maps to this plan.
                        Replaces the current set.
                  required:
                    - products
                - type: 'null'
          x-atmn-mapping: true
          description: Payment processors this plan is connected to. Omitted when unset.
        free_trial:
          type: object
          properties:
            duration_length:
              type: number
              description: Number of duration_type periods the trial lasts.
            duration_type:
              enum:
                - day
                - month
                - year
              type: string
              description: Unit of time for the trial duration ('day', 'month', 'year').
            card_required:
              type: boolean
              description: >-
                Whether a payment method is required to start the trial. If
                true, customer will be charged after trial ends.
            on_end:
              anyOf:
                - enum:
                    - bill
                    - revert
                  type: string
                - type: 'null'
              description: >-
                Behavior when the trial ends. 'bill' charges the customer
                (default). 'revert' expires the trial and restores the
                customer's previous plan.
          required:
            - duration_length
            - duration_type
            - card_required
          description: >-
            Free trial configuration. If set, new customers can try this plan
            before being charged.
        created_at:
          type: number
          description: Unix timestamp (ms) when the plan was created.
        env:
          enum:
            - sandbox
            - live
          type: string
          description: Environment this plan belongs to ('sandbox' or 'live').
        archived:
          type: boolean
          description: >-
            Whether the plan is archived. Archived plans cannot be attached to
            new customers.
        config:
          type: object
          properties:
            ignore_past_due:
              type: boolean
              default: false
              description: >-
                If true, entitlements attached to this plan will still reset on
                schedule even when the customer's product is in a past_due
                state.
            anchor_to_month_start:
              type: boolean
              description: Anchor billing and reset cycles to the 1st of the month (UTC).
              default: false
          description: Miscellaneous plan-level configuration flags.
        billing_controls:
          type: object
          properties:
            auto_topups:
              type: array
              items:
                type: object
                properties:
                  feature_id:
                    type: string
                    description: The ID of the feature (credit balance) to auto top-up.
                  enabled:
                    type: boolean
                    default: false
                    description: Whether auto top-up is enabled.
                  threshold:
                    type: number
                    description: >-
                      When the balance drops below this threshold, an auto
                      top-up will be purchased.
                  quantity:
                    type: number
                    minimum: 1
                    description: Amount of credits to add per auto top-up.
                  purchase_limit:
                    type: object
                    properties:
                      limit_type:
                        enum:
                          - count
                          - amount
                        type: string
                        description: >-
                          What `limit` caps: the number of auto top-ups
                          (`count`, default) or the total amount charged for
                          them, in the customer's currency (`amount`).
                      interval:
                        enum:
                          - hour
                          - day
                          - week
                          - month
                        type: string
                        description: The time interval for the purchase limit window.
                      interval_count:
                        type: number
                        minimum: 1
                        default: 1
                        description: Number of intervals in the purchase limit window.
                      limit:
                        type: number
                        exclusiveMinimum: 0
                        description: >-
                          Maximum allowed within the interval: a number of auto
                          top-ups when limit_type is count, or a total charge
                          (e.g. 500 for $500, pre-tax) when limit_type is
                          amount.
                    required:
                      - interval
                      - limit
                    description: >-
                      Optional limit on auto top-ups per window, by number of
                      top-ups or amount charged.
                  invoice_mode:
                    type: boolean
                    description: >-
                      When true, auto top-up creates a send_invoice invoice
                      instead of auto-charging.
                required:
                  - feature_id
                  - threshold
                  - quantity
              description: List of auto top-up configurations per feature.
            spend_limits:
              type: array
              items:
                type: object
                properties:
                  feature_id:
                    type: string
                    description: Optional feature ID this spend limit applies to.
                  enabled:
                    type: boolean
                    default: false
                    description: Whether the overage spend limit is enabled.
                  limit_type:
                    enum:
                      - absolute
                      - usage_percentage
                    type: string
                    description: >-
                      How overage_limit is interpreted: an absolute overage cap
                      (default) or a percentage of the main-plan allowance.
                  overage_limit:
                    type: number
                    minimum: 0
                    description: >-
                      Overage cap for the feature: absolute units, or a percent
                      (e.g. 120) when limit_type is usage_percentage.
                  skip_overage_billing:
                    type: boolean
                    description: >-
                      When true, overage for this feature is not posted to
                      Stripe. Usage tracking and balance resets still behave
                      normally.
              description: List of overage spend limits per feature (caps overage spend).
            usage_limits:
              type: array
              items:
                type: object
                properties:
                  feature_id:
                    type: string
                    description: The feature this usage limit applies to.
                  enabled:
                    type: boolean
                    default: true
                    description: Whether this usage limit is enabled.
                  limit:
                    type: number
                    minimum: 0
                    description: Maximum units allowed per interval.
                  interval:
                    enum:
                      - day
                      - week
                      - month
                      - year
                    type: string
                    description: >-
                      Interval for the cap, aligned to the customer's billing
                      cycle.
                  anchor:
                    enum:
                      - billing_cycle
                      - utc
                    type: string
                    description: >-
                      Window alignment. 'billing_cycle' phases the interval to
                      the customer's renewal time; 'utc' aligns to the UTC
                      calendar.
                  filter:
                    type: object
                    properties:
                      properties:
                        type: object
                        propertyNames:
                          type: string
                          minLength: 1
                          maxLength: 64
                        additionalProperties:
                          type: string
                    required:
                      - properties
                    description: >-
                      When set, only usage from events whose properties match
                      counts toward this cap. Omit to count all usage of the
                      feature.
                required:
                  - feature_id
                  - limit
                  - interval
              description: List of hard usage caps per feature (max units per interval).
            usage_alerts:
              type: array
              items:
                type: object
                properties:
                  feature_id:
                    type: string
                    description: The feature ID this alert applies to.
                  enabled:
                    type: boolean
                    default: true
                    description: Whether this usage alert is enabled.
                  threshold:
                    type: number
                    description: >-
                      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. remaining
                      and remaining_percentage accept negative values with basis
                      balance, to alert once the balance is overdrawn.
                  threshold_type:
                    enum:
                      - usage
                      - usage_percentage
                      - remaining
                      - remaining_percentage
                    type: string
                    description: >-
                      Whether the threshold is an absolute count or a percentage
                      of the usage allowance or remaining balance.
                  basis:
                    enum:
                      - balance
                      - included
                      - recurring
                      - usage_limit
                    type: string
                    default: balance
                    description: >-
                      What 100% means. balance: every grant on the feature.
                      included: the plan allowance only. recurring: grants that
                      reset. usage_limit: the cap of the usage limit with the
                      same feature and filter.
                  filter:
                    type: object
                    properties:
                      properties:
                        type: object
                        propertyNames:
                          type: string
                          minLength: 1
                          maxLength: 64
                        additionalProperties:
                          type: string
                    required:
                      - properties
                    description: >-
                      Only valid with basis usage_limit. Points the alert at the
                      usage limit carrying the same filter.
                  name:
                    type: string
                    description: >-
                      Optional user-defined label to distinguish multiple alerts
                      on the same feature.
                required:
                  - threshold
                  - threshold_type
              description: List of usage alert configurations per feature.
            overage_allowed:
              type: array
              items:
                type: object
                properties:
                  feature_id:
                    type: string
                    description: The feature ID this overage allowed control applies to.
                  enabled:
                    type: boolean
                    default: false
                    description: Whether overage is allowed for this feature.
                required:
                  - feature_id
              description: >-
                List of overage allowed controls per feature. When enabled,
                usage can exceed balance.
          description: Plan-level billing controls used as customer defaults.
        metadata:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
          description: >-
            Arbitrary key-value metadata defined by you for your own use. Shared
            across all versions of the plan.
        customer_eligibility:
          type: object
          properties:
            trial_available:
              type: boolean
              description: >-
                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:
              enum:
                - active
                - scheduled
              type: string
              description: >-
                The customer's current status with this plan. 'active' if
                attached, 'scheduled' if pending activation.
            canceling:
              type: boolean
              description: >-
                Whether the customer's active instance of this plan is set to
                cancel.
            trialing:
              type: boolean
              description: Whether the customer is currently on a free trial of this plan.
            attach_action:
              enum:
                - activate
                - upgrade
                - downgrade
                - none
                - purchase
              type: string
              description: >-
                The action that would occur if this plan were attached to the
                customer.
          required:
            - attach_action
        base_variant_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            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:
          type: object
          properties:
            base_plan_id:
              type: string
              description: The ID of the base plan this variant was derived from.
            customize:
              type: object
              properties:
                price:
                  anyOf:
                    - type: object
                      properties:
                        amount:
                          type: number
                          description: >-
                            Base price amount for the plan, in major currency
                            units (e.g. dollars).
                        interval:
                          enum:
                            - one_off
                            - week
                            - month
                            - quarter
                            - semi_annual
                            - year
                          type: string
                          description: Billing interval (e.g. 'month', 'year').
                        interval_count:
                          type: number
                          description: >-
                            Number of intervals per billing cycle. Defaults to
                            1.
                          default: 1
                        additional_currencies:
                          type: array
                          items:
                            type: object
                            properties:
                              currency:
                                type: string
                                description: >-
                                  Three-letter Stripe-supported currency code
                                  (e.g. 'eur', 'gbp').
                              amount:
                                type: number
                                description: >-
                                  Price amount in this currency. Set explicitly
                                  per currency, not converted from the base
                                  amount.
                            required:
                              - currency
                              - amount
                          description: >-
                            Base price amounts in additional currencies. The
                            base 'amount' is in the org's default currency.
                      required:
                        - amount
                        - interval
                      title: BasePrice
                      description: Base price configuration for a plan.
                    - type: 'null'
                  description: >-
                    Override the base price of the plan. Pass null to remove the
                    base price.
                add_items:
                  type: array
                  items:
                    type: object
                    properties:
                      threshold_billing:
                        anyOf:
                          - type: object
                            properties:
                              threshold:
                                type: number
                                exclusiveMinimum: 0
                            required:
                              - threshold
                          - type: 'null'
                        description: >-
                          Bills this many feature units when outstanding overage
                          reaches it.
                      feature_id:
                        type: string
                        description: The ID of the feature to configure.
                      included:
                        type: number
                        maximum: 10000000000000
                        description: >-
                          Number of free units included. Balance resets to this
                          each interval for consumable features.
                      unlimited:
                        type: boolean
                        description: >-
                          If true, customer has unlimited access to this
                          feature.
                      pooled:
                        type: boolean
                        default: false
                        description: >-
                          Whether entity-level grants contribute to a shared
                          customer balance.
                      reset:
                        type: object
                        properties:
                          interval:
                            enum:
                              - one_off
                              - minute
                              - hour
                              - day
                              - week
                              - month
                              - quarter
                              - semi_annual
                              - year
                            type: string
                            description: >-
                              Interval at which balance resets (e.g. 'month',
                              'year'). For consumable features only.
                          interval_count:
                            type: number
                            description: Number of intervals between resets. Defaults to 1.
                            default: 1
                        required:
                          - interval
                        description: >-
                          Reset configuration for consumable features. Omit for
                          non-consumable features like seats.
                      price:
                        type: object
                        properties:
                          amount:
                            type: number
                            description: >-
                              Price per billing_units after included usage.
                              Either 'amount' or 'tiers' is required.
                          additional_currencies:
                            type: array
                            items:
                              type: object
                              properties:
                                currency:
                                  type: string
                                  description: >-
                                    Three-letter Stripe-supported currency code
                                    (e.g. 'eur', 'gbp').
                                amount:
                                  type: number
                                  description: >-
                                    Price amount in this currency. Set
                                    explicitly per currency, not converted from
                                    the base amount.
                              required:
                                - currency
                                - amount
                            description: >-
                              Amounts in additional currencies for this flat
                              price. The base 'amount' is in the org's default
                              currency. Only valid with 'amount', not 'tiers'.
                          tiers:
                            type: array
                            items:
                              type: object
                              properties:
                                to:
                                  anyOf:
                                    - type: number
                                    - const: inf
                                amount:
                                  type: number
                                flat_amount:
                                  type: number
                                additional_currencies:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      currency:
                                        type: string
                                        description: >-
                                          Three-letter Stripe-supported currency
                                          code (e.g. 'eur', 'gbp').
                                      amount:
                                        type: number
                                        description: >-
                                          Per-unit amount for this tier in this
                                          currency.
                                      flat_amount:
                                        type: number
                                        description: >-
                                          Flat amount for this tier in this
                                          currency, if the tier uses one.
                                    required:
                                      - currency
                              required:
                                - to
                                - amount
                            description: >-
                              Tiered pricing.  Either 'amount' or 'tiers' is
                              required.
                          tier_behavior:
                            enum:
                              - graduated
                              - volume
                            type: string
                            description: >-
                              How tiers price usage. 'graduated' (default)
                              charges each unit at the rate of the tier it falls
                              in. 'volume' picks one tier from total usage. On
                              usage-based items it bills only usage past the
                              included amount, at the rate of the tier total
                              usage reaches, plus its flat_amount. On prepaid
                              items it charges every unit, the included ones
                              too, at that tier's rate plus its flat_amount.
                          interval:
                            enum:
                              - one_off
                              - week
                              - month
                              - quarter
                              - semi_annual
                              - year
                            type: string
                            description: >-
                              Billing interval. For usage-based features, should
                              match reset.interval, unless the price has
                              graduated tiers and reset.interval is a whole
                              multiple of it: each invoice then bills only the
                              newly owed usage, at the tier the reset period has
                              reached.
                          interval_count:
                            type: number
                            description: >-
                              Number of intervals per billing cycle. Defaults to
                              1.
                            default: 1
                          billing_units:
                            type: number
                            default: 1
                            description: >-
                              Units per price increment. Usage is rounded UP
                              when billed (e.g. billing_units=100 means 101
                              rounds to 200).
                          billing_method:
                            enum:
                              - prepaid
                              - usage_based
                            type: string
                            description: >-
                              'prepaid' for upfront payment (seats),
                              'usage_based' for pay-as-you-go.
                          max_purchase:
                            anyOf:
                              - type: number
                              - type: 'null'
                            description: >-
                              Max units purchasable beyond included. E.g.
                              included=100, max_purchase=300 allows 400 total.
                              Null for no limit.
                        required:
                          - interval
                          - billing_method
                        description: >-
                          Pricing for usage beyond included units. Omit for free
                          features.
                      proration:
                        type: object
                        properties:
                          on_increase:
                            enum:
                              - bill_immediately
                              - prorate_immediately
                              - prorate_next_cycle
                              - bill_next_cycle
                            type: string
                            description: >-
                              Billing behavior when quantity increases
                              mid-cycle.
                          on_decrease:
                            enum:
                              - prorate
                              - prorate_immediately
                              - prorate_next_cycle
                              - none
                              - no_prorations
                            type: string
                            description: Credit behavior when quantity decreases mid-cycle.
                        required:
                          - on_increase
                          - on_decrease
                        description: >-
                          Proration settings for prepaid features. Controls
                          mid-cycle quantity change billing.
                      rollover:
                        type: object
                        properties:
                          max:
                            type: number
                            description: Max rollover units. Omit for unlimited rollover.
                          max_percentage:
                            type: number
                            description: >-
                              Maximum rollover as a percentage (0-100) of
                              included + prepaid grant. Mutually exclusive with
                              max.
                          expiry_duration_type:
                            enum:
                              - month
                              - forever
                            type: string
                            description: When rolled over units expire.
                          expiry_duration_length:
                            type: number
                            description: Number of periods before expiry.
                        required:
                          - expiry_duration_type
                        description: >-
                          Rollover config for unused units. If set, unused
                          included units carry over.
                      expiry:
                        type: object
                        properties:
                          duration:
                            enum:
                              - day
                              - week
                              - month
                              - year
                            type: string
                          length:
                            type: number
                        required:
                          - duration
                          - length
                        description: >-
                          Purchased units expire this long after each purchase.
                          One-off prepaid consumable items only.
                      feature_override:
                        type: object
                        properties:
                          credit_schema:
                            type: array
                            items:
                              anyOf:
                                - type: object
                                  properties:
                                    metered_feature_id:
                                      type: string
                                      minLength: 1
                                      description: >-
                                        ID of the metered feature that draws
                                        from this credit system.
                                    billing_units:
                                      type: number
                                      exclusiveMinimum: 0
                                      description: >-
                                        Number of metered-feature units priced
                                        together. Defaults to one when omitted.
                                    dimensions:
                                      type: object
                                      propertyNames:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      additionalProperties:
                                        $ref: '#/components/schemas/CreditDimension'
                                      description: >-
                                        Named rates chosen by event properties.
                                        The most specific match sets the rate;
                                        with no match the item's own rate
                                        applies.
                                    multipliers:
                                      type: object
                                      propertyNames:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      additionalProperties:
                                        type: object
                                        properties:
                                          match:
                                            type: object
                                            propertyNames:
                                              type: string
                                            additionalProperties:
                                              type: string
                                            description: >-
                                              Event properties this entry applies to.
                                              Every key must equal the tracked
                                              property, compared as strings.
                                          factor:
                                            type: number
                                            exclusiveMinimum: 0
                                            description: >-
                                              Multiplies the matched rate. All
                                              matching multipliers stack.
                                          add:
                                            type: number
                                            description: >-
                                              Added to the rate after every factor is
                                              applied, in credits per billing-unit
                                              group.
                                        required:
                                          - match
                                        additionalProperties: false
                                      description: >-
                                        Named adjustments chosen by event
                                        properties. Every match applies: factors
                                        multiply, then adds are summed.
                                    tier_behavior:
                                      const: graduated
                                    tiers:
                                      type: array
                                      minItems: 1
                                      items:
                                        type: object
                                        properties:
                                          to:
                                            anyOf:
                                              - type: number
                                                exclusiveMinimum: 0
                                              - enum:
                                                  - inf
                                                type: string
                                            description: >-
                                              Inclusive upper usage boundary for this
                                              graduated tier. The final tier must be
                                              'inf'.
                                          credit_cost:
                                            type: number
                                            minimum: 0
                                            description: >-
                                              Credits consumed per billing-unit group
                                              within this tier.
                                        required:
                                          - to
                                          - credit_cost
                                  required:
                                    - metered_feature_id
                                    - tier_behavior
                                    - tiers
                                  additionalProperties: false
                                - type: object
                                  properties:
                                    metered_feature_id:
                                      type: string
                                      minLength: 1
                                      description: >-
                                        ID of the metered feature that draws
                                        from this credit system.
                                    billing_units:
                                      type: number
                                      exclusiveMinimum: 0
                                      description: >-
                                        Number of metered-feature units priced
                                        together. Defaults to one when omitted.
                                    dimensions:
                                      type: object
                                      propertyNames:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      additionalProperties:
                                        $ref: '#/components/schemas/CreditDimension'
                                      description: >-
                                        Named rates chosen by event properties.
                                        The most specific match sets the rate;
                                        with no match the item's own rate
                                        applies.
                                    multipliers:
                                      type: object
                                      propertyNames:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      additionalProperties:
                                        type: object
                                        properties:
                                          match:
                                            type: object
                                            propertyNames:
                                              type: string
                                            additionalProperties:
                                              type: string
                                            description: >-
                                              Event properties this entry applies to.
                                              Every key must equal the tracked
                                              property, compared as strings.
                                          factor:
                                            type: number
                                            exclusiveMinimum: 0
                                            description: >-
                                              Multiplies the matched rate. All
                                              matching multipliers stack.
                                          add:
                                            type: number
                                            description: >-
                                              Added to the rate after every factor is
                                              applied, in credits per billing-unit
                                              group.
                                        required:
                                          - match
                                        additionalProperties: false
                                      description: >-
                                        Named adjustments chosen by event
                                        properties. Every match applies: factors
                                        multiply, then adds are summed.
                                    credit_cost:
                                      type: number
                                      minimum: 0
                                      description: Credits consumed per billing-unit group.
                                  required:
                                    - metered_feature_id
                                    - credit_cost
                                  additionalProperties: false
                                - type: object
                                  properties:
                                    metered_feature_id:
                                      type: string
                                      minLength: 1
                                      description: >-
                                        ID of the metered feature to remove from
                                        the credit system.
                                    excluded:
                                      const: true
                                      description: >-
                                        Removes this feature from the credit
                                        system for customers on this plan.
                                        Cannot be combined with a rate.
                                  required:
                                    - metered_feature_id
                                    - excluded
                                  additionalProperties: false
                            description: >-
                              For credit system features: merges into the
                              feature's credit_schema by metered_feature_id for
                              customers on this plan. A row with a rate
                              overrides or adds that feature, a row with
                              `excluded: true` removes it, and unlisted features
                              keep the credit system's rate.
                          markups:
                            type: object
                            properties:
                              default_markup:
                                type: number
                                minimum: -100
                                description: >-
                                  Default percentage markup for customers on
                                  this plan. Use -100 to make usage free.
                              provider_markups:
                                anyOf:
                                  - type: object
                                    propertyNames:
                                      type: string
                                    additionalProperties:
                                      type: object
                                      properties:
                                        markup:
                                          type: number
                                          minimum: -100
                                      required:
                                        - markup
                                  - type: 'null'
                                description: >-
                                  Per-provider markup percentages for customers
                                  on this plan.
                              model_markups:
                                anyOf:
                                  - type: object
                                    propertyNames:
                                      type: string
                                      pattern: .+\/.+
                                    additionalProperties:
                                      type: object
                                      properties:
                                        markup:
                                          type: number
                                          minimum: -100
                                        input_cost:
                                          type: number
                                          minimum: 0
                                        output_cost:
                                          type: number
                                          minimum: 0
                                  - type: 'null'
                                description: >-
                                  Per-model markup overrides for customers on
                                  this plan.
                            additionalProperties: false
                            description: >-
                              For AI credit system features: replaces the
                              feature's markup chain entirely for customers on
                              this plan. An unset level means no markup at that
                              level rather than inheriting the feature's.
                        additionalProperties: false
                        description: >-
                          Overrides fields of this item's feature for customers
                          on this plan (e.g. a credit system's credit_schema).
                    required:
                      - feature_id
                    title: PlanItem
                    description: >-
                      Configuration for a feature item in a plan, including
                      usage limits, pricing, and rollover settings.
                  description: Items to add to the plan.
                remove_items:
                  type: array
                  items:
                    type: object
                    properties:
                      feature_id:
                        type: string
                        description: Match items linked to this feature.
                      billing_method:
                        enum:
                          - prepaid
                          - usage_based
                        type: string
                        description: >-
                          Match items with this billing method (prepaid or
                          usage_based).
                      interval:
                        anyOf:
                          - enum:
                              - one_off
                              - week
                              - month
                              - quarter
                              - semi_annual
                              - year
                            type: string
                          - enum:
                              - one_off
                              - minute
                              - hour
                              - day
                              - week
                              - month
                              - quarter
                              - semi_annual
                              - year
                            type: string
                        description: >-
                          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:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                        exclusiveMinimum: 0
                        description: >-
                          Match items with this interval_count. Disambiguates
                          between items that share an interval but differ in
                          count.
                      included:
                        type: number
                        maximum: 10000000000000
                        description: >-
                          Match items whose grant equals this included usage.
                          Omitted is a wildcard.
                    title: PlanItemFilter
                    description: >-
                      Filter for matching plan items. All provided fields must
                      match (AND).
                  description: Filters selecting items to remove from the plan.
                free_trial:
                  anyOf:
                    - type: object
                      properties:
                        duration_length:
                          type: number
                          description: Number of duration_type periods the trial lasts.
                        duration_type:
                          enum:
                            - day
                            - month
                            - year
                          type: string
                          default: month
                          description: Unit of time for the trial ('day', 'month', 'year').
                        card_required:
                          type: boolean
                          default: false
                          description: >-
                            If true, a payment method is required to start the
                            trial and the customer is charged when it ends.
                            Defaults to false.
                        on_end:
                          enum:
                            - bill
                            - revert
                          type: string
                          description: >-
                            Behavior when the trial ends. 'bill' charges the
                            customer (default). 'revert' expires the trial and
                            restores the customer's previous plan.
                          default: bill
                      required:
                        - duration_length
                      title: FreeTrialParams
                      description: Free trial configuration for a plan.
                    - type: 'null'
                  description: >-
                    Override the plan's default free trial. Pass an object to
                    set a custom trial, or null to remove the trial entirely.
                billing_controls:
                  type: object
                  properties:
                    auto_topups:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: >-
                              The ID of the feature (credit balance) to auto
                              top-up.
                          enabled:
                            type: boolean
                            default: false
                            description: Whether auto top-up is enabled.
                          threshold:
                            type: number
                            description: >-
                              When the balance drops below this threshold, an
                              auto top-up will be purchased.
                          quantity:
                            type: number
                            minimum: 1
                            description: Amount of credits to add per auto top-up.
                          purchase_limit:
                            type: object
                            properties:
                              limit_type:
                                enum:
                                  - count
                                  - amount
                                type: string
                                description: >-
                                  What `limit` caps: the number of auto top-ups
                                  (`count`, default) or the total amount charged
                                  for them, in the customer's currency
                                  (`amount`).
                              interval:
                                enum:
                                  - hour
                                  - day
                                  - week
                                  - month
                                type: string
                                description: >-
                                  The time interval for the purchase limit
                                  window.
                              interval_count:
                                type: number
                                minimum: 1
                                default: 1
                                description: >-
                                  Number of intervals in the purchase limit
                                  window.
                              limit:
                                type: number
                                exclusiveMinimum: 0
                                description: >-
                                  Maximum allowed within the interval: a number
                                  of auto top-ups when limit_type is count, or a
                                  total charge (e.g. 500 for $500, pre-tax) when
                                  limit_type is amount.
                              count:
                                type: number
                                minimum: 0
                                description: >-
                                  Set the current window's consumed auto top-up
                                  count. Omit to leave runtime state unchanged.
                              amount:
                                type: number
                                minimum: 0
                                description: >-
                                  Set the amount already charged by auto top-ups
                                  in the current window. Omit to leave runtime
                                  state unchanged.
                            required:
                              - interval
                              - limit
                            description: >-
                              Optional rate limit to cap how often auto top-ups
                              occur. Pass count or amount to set the current
                              window's consumed top-ups or charged amount.
                          invoice_mode:
                            type: boolean
                            description: >-
                              When true, auto top-up creates a send_invoice
                              invoice instead of auto-charging.
                        required:
                          - feature_id
                          - threshold
                          - quantity
                      description: List of auto top-up configurations per feature.
                      default: []
                    spend_limits:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: Optional feature ID this spend limit applies to.
                          enabled:
                            type: boolean
                            default: false
                            description: Whether the overage spend limit is enabled.
                          limit_type:
                            enum:
                              - absolute
                              - usage_percentage
                            type: string
                            description: >-
                              How overage_limit is interpreted: an absolute
                              overage cap (default) or a percentage of the
                              main-plan allowance.
                          overage_limit:
                            type: number
                            minimum: 0
                            description: >-
                              Overage cap for the feature: absolute units, or a
                              percent (e.g. 120) when limit_type is
                              usage_percentage.
                          skip_overage_billing:
                            type: boolean
                            description: >-
                              When true, overage for this feature is not posted
                              to Stripe. Usage tracking and balance resets still
                              behave normally.
                      description: >-
                        List of overage spend limits per feature (caps overage
                        spend).
                      default: []
                    usage_limits:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: The feature this usage limit applies to.
                          enabled:
                            type: boolean
                            default: true
                            description: Whether this usage limit is enabled.
                          limit:
                            type: number
                            minimum: 0
                            description: Maximum units allowed per interval.
                          interval:
                            enum:
                              - day
                              - week
                              - month
                              - year
                            type: string
                            description: >-
                              Interval for the cap, aligned to the customer's
                              billing cycle.
                          anchor:
                            enum:
                              - billing_cycle
                              - utc
                            type: string
                            description: >-
                              Window alignment. 'billing_cycle' phases the
                              interval to the customer's renewal time; 'utc'
                              aligns to the UTC calendar.
                          filter:
                            type: object
                            properties:
                              properties:
                                type: object
                                propertyNames:
                                  type: string
                                  minLength: 1
                                  maxLength: 64
                                additionalProperties:
                                  type: string
                            required:
                              - properties
                            description: >-
                              When set, only usage from events whose properties
                              match counts toward this cap. Omit to count all
                              usage of the feature.
                        required:
                          - feature_id
                          - limit
                          - interval
                      description: >-
                        List of hard usage caps per feature (max units per
                        interval).
                      default: []
                    usage_alerts:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: The feature ID this alert applies to.
                          enabled:
                            type: boolean
                            default: true
                            description: Whether this usage alert is enabled.
                          threshold:
                            type: number
                            description: >-
                              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. remaining and remaining_percentage
                              accept negative values with basis balance, to
                              alert once the balance is overdrawn.
                          threshold_type:
                            enum:
                              - usage
                              - usage_percentage
                              - remaining
                              - remaining_percentage
                            type: string
                            description: >-
                              Whether the threshold is an absolute count or a
                              percentage of the usage allowance or remaining
                              balance.
                          basis:
                            enum:
                              - balance
                              - included
                              - recurring
                              - usage_limit
                            type: string
                            default: balance
                            description: >-
                              What 100% means. balance: every grant on the
                              feature. included: the plan allowance only.
                              recurring: grants that reset. usage_limit: the cap
                              of the usage limit with the same feature and
                              filter.
                          filter:
                            type: object
                            properties:
                              properties:
                                type: object
                                propertyNames:
                                  type: string
                                  minLength: 1
                                  maxLength: 64
                                additionalProperties:
                                  type: string
                            required:
                              - properties
                            description: >-
                              Only valid with basis usage_limit. Points the
                              alert at the usage limit carrying the same filter.
                          name:
                            type: string
                            description: >-
                              Optional user-defined label to distinguish
                              multiple alerts on the same feature.
                        required:
                          - threshold
                          - threshold_type
                      description: List of usage alert configurations per feature.
                      default: []
                    overage_allowed:
                      type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                            description: >-
                              The feature ID this overage allowed control
                              applies to.
                          enabled:
                            type: boolean
                            default: false
                            description: Whether overage is allowed for this feature.
                        required:
                          - feature_id
                      description: >-
                        List of overage allowed controls per feature. When
                        enabled, usage can exceed balance.
                      default: []
                  description: >-
                    Override the plan's billing controls (auto top-ups, spend
                    limits, usage limits, usage alerts, overage allowed) for
                    this customer.
                upsert_licenses:
                  type: array
                  items:
                    type: object
                    properties:
                      license_plan_id:
                        type: string
                      version_slug:
                        type: string
                      included:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      prepaid_only:
                        type: boolean
                      customize:
                        anyOf:
                          - type: object
                            properties:
                              price:
                                anyOf:
                                  - type: object
                                    properties:
                                      amount:
                                        type: number
                                        description: >-
                                          Base price amount for the plan, in major
                                          currency units (e.g. dollars).
                                      interval:
                                        enum:
                                          - one_off
                                          - week
                                          - month
                                          - quarter
                                          - semi_annual
                                          - year
                                        type: string
                                        description: Billing interval (e.g. 'month', 'year').
                                      interval_count:
                                        type: number
                                        description: >-
                                          Number of intervals per billing cycle.
                                          Defaults to 1.
                                        default: 1
                                      additional_currencies:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            currency:
                                              type: string
                                              description: >-
                                                Three-letter Stripe-supported currency
                                                code (e.g. 'eur', 'gbp').
                                            amount:
                                              type: number
                                              description: >-
                                                Price amount in this currency. Set
                                                explicitly per currency, not converted
                                                from the base amount.
                                          required:
                                            - currency
                                            - amount
                                        description: >-
                                          Base price amounts in additional
                                          currencies. The base 'amount' is in the
                                          org's default currency.
                                    required:
                                      - amount
                                      - interval
                                    title: BasePrice
                                    description: Base price configuration for a plan.
                                  - type: 'null'
                              add_items:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    threshold_billing:
                                      anyOf:
                                        - type: object
                                          properties:
                                            threshold:
                                              type: number
                                              exclusiveMinimum: 0
                                          required:
                                            - threshold
                                        - type: 'null'
                                      description: >-
                                        Bills this many feature units when
                                        outstanding overage reaches it.
                                    feature_id:
                                      type: string
                                      description: The ID of the feature to configure.
                                    included:
                                      type: number
                                      maximum: 10000000000000
                                      description: >-
                                        Number of free units included. Balance
                                        resets to this each interval for
                                        consumable features.
                                    unlimited:
                                      type: boolean
                                      description: >-
                                        If true, customer has unlimited access
                                        to this feature.
                                    pooled:
                                      type: boolean
                                      default: false
                                      description: >-
                                        Whether entity-level grants contribute
                                        to a shared customer balance.
                                    reset:
                                      type: object
                                      properties:
                                        interval:
                                          enum:
                                            - one_off
                                            - minute
                                            - hour
                                            - day
                                            - week
                                            - month
                                            - quarter
                                            - semi_annual
                                            - year
                                          type: string
                                          description: >-
                                            Interval at which balance resets (e.g.
                                            'month', 'year'). For consumable
                                            features only.
                                        interval_count:
                                          type: number
                                          description: >-
                                            Number of intervals between resets.
                                            Defaults to 1.
                                          default: 1
                                      required:
                                        - interval
                                      description: >-
                                        Reset configuration for consumable
                                        features. Omit for non-consumable
                                        features like seats.
                                    price:
                                      type: object
                                      properties:
                                        amount:
                                          type: number
                                          description: >-
                                            Price per billing_units after included
                                            usage. Either 'amount' or 'tiers' is
                                            required.
                                        additional_currencies:
                                          type: array
                                          items:
                                            type: object
                                            properties:
                                              currency:
                                                type: string
                                                description: >-
                                                  Three-letter Stripe-supported currency
                                                  code (e.g. 'eur', 'gbp').
                                              amount:
                                                type: number
                                                description: >-
                                                  Price amount in this currency. Set
                                                  explicitly per currency, not converted
                                                  from the base amount.
                                            required:
                                              - currency
                                              - amount
                                          description: >-
                                            Amounts in additional currencies for
                                            this flat price. The base 'amount' is in
                                            the org's default currency. Only valid
                                            with 'amount', not 'tiers'.
                                        tiers:
                                          type: array
                                          items:
                                            type: object
                                            properties:
                                              to:
                                                anyOf:
                                                  - type: number
                                                  - const: inf
                                              amount:
                                                type: number
                                              flat_amount:
                                                type: number
                                              additional_currencies:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    currency:
                                                      type: string
                                                      description: >-
                                                        Three-letter Stripe-supported currency
                                                        code (e.g. 'eur', 'gbp').
                                                    amount:
                                                      type: number
                                                      description: >-
                                                        Per-unit amount for this tier in this
                                                        currency.
                                                    flat_amount:
                                                      type: number
                                                      description: >-
                                                        Flat amount for this tier in this
                                                        currency, if the tier uses one.
                                                  required:
                                                    - currency
                                            required:
                                              - to
                                              - amount
                                          description: >-
                                            Tiered pricing.  Either 'amount' or
                                            'tiers' is required.
                                        tier_behavior:
                                          enum:
                                            - graduated
                                            - volume
                                          type: string
                                          description: >-
                                            How tiers price usage. 'graduated'
                                            (default) charges each unit at the rate
                                            of the tier it falls in. 'volume' picks
                                            one tier from total usage. On
                                            usage-based items it bills only usage
                                            past the included amount, at the rate of
                                            the tier total usage reaches, plus its
                                            flat_amount. On prepaid items it charges
                                            every unit, the included ones too, at
                                            that tier's rate plus its flat_amount.
                                        interval:
                                          enum:
                                            - one_off
                                            - week
                                            - month
                                            - quarter
                                            - semi_annual
                                            - year
                                          type: string
                                          description: >-
                                            Billing interval. For usage-based
                                            features, should match reset.interval,
                                            unless the price has graduated tiers and
                                            reset.interval is a whole multiple of
                                            it: each invoice then bills only the
                                            newly owed usage, at the tier the reset
                                            period has reached.
                                        interval_count:
                                          type: number
                                          description: >-
                                            Number of intervals per billing cycle.
                                            Defaults to 1.
                                          default: 1
                                        billing_units:
                                          type: number
                                          default: 1
                                          description: >-
                                            Units per price increment. Usage is
                                            rounded UP when billed (e.g.
                                            billing_units=100 means 101 rounds to
                                            200).
                                        billing_method:
                                          enum:
                                            - prepaid
                                            - usage_based
                                          type: string
                                          description: >-
                                            'prepaid' for upfront payment (seats),
                                            'usage_based' for pay-as-you-go.
                                        max_purchase:
                                          anyOf:
                                            - type: number
                                            - type: 'null'
                                          description: >-
                                            Max units purchasable beyond included.
                                            E.g. included=100, max_purchase=300
                                            allows 400 total. Null for no limit.
                                      required:
                                        - interval
                                        - billing_method
                                      description: >-
                                        Pricing for usage beyond included units.
                                        Omit for free features.
                                    proration:
                                      type: object
                                      properties:
                                        on_increase:
                                          enum:
                                            - bill_immediately
                                            - prorate_immediately
                                            - prorate_next_cycle
                                            - bill_next_cycle
                                          type: string
                                          description: >-
                                            Billing behavior when quantity increases
                                            mid-cycle.
                                        on_decrease:
                                          enum:
                                            - prorate
                                            - prorate_immediately
                                            - prorate_next_cycle
                                            - none
                                            - no_prorations
                                          type: string
                                          description: >-
                                            Credit behavior when quantity decreases
                                            mid-cycle.
                                      required:
                                        - on_increase
                                        - on_decrease
                                      description: >-
                                        Proration settings for prepaid features.
                                        Controls mid-cycle quantity change
                                        billing.
                                    rollover:
                                      type: object
                                      properties:
                                        max:
                                          type: number
                                          description: >-
                                            Max rollover units. Omit for unlimited
                                            rollover.
                                        max_percentage:
                                          type: number
                                          description: >-
                                            Maximum rollover as a percentage (0-100)
                                            of included + prepaid grant. Mutually
                                            exclusive with max.
                                        expiry_duration_type:
                                          enum:
                                            - month
                                            - forever
                                          type: string
                                          description: When rolled over units expire.
                                        expiry_duration_length:
                                          type: number
                                          description: Number of periods before expiry.
                                      required:
                                        - expiry_duration_type
                                      description: >-
                                        Rollover config for unused units. If
                                        set, unused included units carry over.
                                    expiry:
                                      type: object
                                      properties:
                                        duration:
                                          enum:
                                            - day
                                            - week
                                            - month
                                            - year
                                          type: string
                                        length:
                                          type: number
                                      required:
                                        - duration
                                        - length
                                      description: >-
                                        Purchased units expire this long after
                                        each purchase. One-off prepaid
                                        consumable items only.
                                    feature_override:
                                      type: object
                                      properties:
                                        credit_schema:
                                          type: array
                                          items:
                                            anyOf:
                                              - type: object
                                                properties:
                                                  metered_feature_id:
                                                    type: string
                                                    minLength: 1
                                                    description: >-
                                                      ID of the metered feature that draws
                                                      from this credit system.
                                                  billing_units:
                                                    type: number
                                                    exclusiveMinimum: 0
                                                    description: >-
                                                      Number of metered-feature units priced
                                                      together. Defaults to one when omitted.
                                                  dimensions:
                                                    type: object
                                                    propertyNames:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 64
                                                    additionalProperties:
                                                      $ref: '#/components/schemas/CreditDimension'
                                                    description: >-
                                                      Named rates chosen by event properties.
                                                      The most specific match sets the rate;
                                                      with no match the item's own rate
                                                      applies.
                                                  multipliers:
                                                    type: object
                                                    propertyNames:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 64
                                                    additionalProperties:
                                                      type: object
                                                      properties:
                                                        match:
                                                          type: object
                                                          propertyNames:
                                                            type: string
                                                          additionalProperties:
                                                            type: string
                                                          description: >-
                                                            Event properties this entry applies to.
                                                            Every key must equal the tracked
                                                            property, compared as strings.
                                                        factor:
                                                          type: number
                                                          exclusiveMinimum: 0
                                                          description: >-
                                                            Multiplies the matched rate. All
                                                            matching multipliers stack.
                                                        add:
                                                          type: number
                                                          description: >-
                                                            Added to the rate after every factor is
                                                            applied, in credits per billing-unit
                                                            group.
                                                      required:
                                                        - match
                                                      additionalProperties: false
                                                    description: >-
                                                      Named adjustments chosen by event
                                                      properties. Every match applies: factors
                                                      multiply, then adds are summed.
                                                  tier_behavior:
                                                    const: graduated
                                                  tiers:
                                                    type: array
                                                    minItems: 1
                                                    items:
                                                      type: object
                                                      properties:
                                                        to:
                                                          anyOf:
                                                            - type: number
                                                              exclusiveMinimum: 0
                                                            - enum:
                                                                - inf
                                                              type: string
                                                          description: >-
                                                            Inclusive upper usage boundary for this
                                                            graduated tier. The final tier must be
                                                            'inf'.
                                                        credit_cost:
                                                          type: number
                                                          minimum: 0
                                                          description: >-
                                                            Credits consumed per billing-unit group
                                                            within this tier.
                                                      required:
                                                        - to
                                                        - credit_cost
                                                required:
                                                  - metered_feature_id
                                                  - tier_behavior
                                                  - tiers
                                                additionalProperties: false
                                              - type: object
                                                properties:
                                                  metered_feature_id:
                                                    type: string
                                                    minLength: 1
                                                    description: >-
                                                      ID of the metered feature that draws
                                                      from this credit system.
                                                  billing_units:
                                                    type: number
                                                    exclusiveMinimum: 0
                                                    description: >-
                                                      Number of metered-feature units priced
                                                      together. Defaults to one when omitted.
                                                  dimensions:
                                                    type: object
                                                    propertyNames:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 64
                                                    additionalProperties:
                                                      $ref: '#/components/schemas/CreditDimension'
                                                    description: >-
                                                      Named rates chosen by event properties.
                                                      The most specific match sets the rate;
                                                      with no match the item's own rate
                                                      applies.
                                                  multipliers:
                                                    type: object
                                                    propertyNames:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 64
                                                    additionalProperties:
                                                      type: object
                                                      properties:
                                                        match:
                                                          type: object
                                                          propertyNames:
                                                            type: string
                                                          additionalProperties:
                                                            type: string
                                                          description: >-
                                                            Event properties this entry applies to.
                                                            Every key must equal the tracked
                                                            property, compared as strings.
                                                        factor:
                                                          type: number
                                                          exclusiveMinimum: 0
                                                          description: >-
                                                            Multiplies the matched rate. All
                                                            matching multipliers stack.
                                                        add:
                                                          type: number
                                                          description: >-
                                                            Added to the rate after every factor is
                                                            applied, in credits per billing-unit
                                                            group.
                                                      required:
                                                        - match
                                                      additionalProperties: false
                                                    description: >-
                                                      Named adjustments chosen by event
                                                      properties. Every match applies: factors
                                                      multiply, then adds are summed.
                                                  credit_cost:
                                                    type: number
                                                    minimum: 0
                                                    description: Credits consumed per billing-unit group.
                                                required:
                                                  - metered_feature_id
                                                  - credit_cost
                                                additionalProperties: false
                                              - type: object
                                                properties:
                                                  metered_feature_id:
                                                    type: string
                                                    minLength: 1
                                                    description: >-
                                                      ID of the metered feature to remove from
                                                      the credit system.
                                                  excluded:
                                                    const: true
                                                    description: >-
                                                      Removes this feature from the credit
                                                      system for customers on this plan.
                                                      Cannot be combined with a rate.
                                                required:
                                                  - metered_feature_id
                                                  - excluded
                                                additionalProperties: false
                                          description: >-
                                            For credit system features: merges into
                                            the feature's credit_schema by
                                            metered_feature_id for customers on this
                                            plan. A row with a rate overrides or
                                            adds that feature, a row with `excluded:
                                            true` removes it, and unlisted features
                                            keep the credit system's rate.
                                        markups:
                                          type: object
                                          properties:
                                            default_markup:
                                              type: number
                                              minimum: -100
                                              description: >-
                                                Default percentage markup for customers
                                                on this plan. Use -100 to make usage
                                                free.
                                            provider_markups:
                                              anyOf:
                                                - type: object
                                                  propertyNames:
                                                    type: string
                                                  additionalProperties:
                                                    type: object
                                                    properties:
                                                      markup:
                                                        type: number
                                                        minimum: -100
                                                    required:
                                                      - markup
                                                - type: 'null'
                                              description: >-
                                                Per-provider markup percentages for
                                                customers on this plan.
                                            model_markups:
                                              anyOf:
                                                - type: object
                                                  propertyNames:
                                                    type: string
                                                    pattern: .+\/.+
                                                  additionalProperties:
                                                    type: object
                                                    properties:
                                                      markup:
                                                        type: number
                                                        minimum: -100
                                                      input_cost:
                                                        type: number
                                                        minimum: 0
                                                      output_cost:
                                                        type: number
                                                        minimum: 0
                                                - type: 'null'
                                              description: >-
                                                Per-model markup overrides for customers
                                                on this plan.
                                          additionalProperties: false
                                          description: >-
                                            For AI credit system features: replaces
                                            the feature's markup chain entirely for
                                            customers on this plan. An unset level
                                            means no markup at that level rather
                                            than inheriting the feature's.
                                      additionalProperties: false
                                      description: >-
                                        Overrides fields of this item's feature
                                        for customers on this plan (e.g. a
                                        credit system's credit_schema).
                                  required:
                                    - feature_id
                                  title: PlanItem
                                  description: >-
                                    Configuration for a feature item in a plan,
                                    including usage limits, pricing, and
                                    rollover settings.
                              remove_items:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    feature_id:
                                      type: string
                                      description: Match items linked to this feature.
                                    billing_method:
                                      enum:
                                        - prepaid
                                        - usage_based
                                      type: string
                                      description: >-
                                        Match items with this billing method
                                        (prepaid or usage_based).
                                    interval:
                                      anyOf:
                                        - enum:
                                            - one_off
                                            - week
                                            - month
                                            - quarter
                                            - semi_annual
                                            - year
                                          type: string
                                        - enum:
                                            - one_off
                                            - minute
                                            - hour
                                            - day
                                            - week
                                            - month
                                            - quarter
                                            - semi_annual
                                            - year
                                          type: string
                                      description: >-
                                        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:
                                      type: integer
                                      minimum: -9007199254740991
                                      maximum: 9007199254740991
                                      exclusiveMinimum: 0
                                      description: >-
                                        Match items with this interval_count.
                                        Disambiguates between items that share
                                        an interval but differ in count.
                                    included:
                                      type: number
                                      maximum: 10000000000000
                                      description: >-
                                        Match items whose grant equals this
                                        included usage. Omitted is a wildcard.
                                  title: PlanItemFilter
                                  description: >-
                                    Filter for matching plan items. All provided
                                    fields must match (AND).
                          - type: 'null'
                      metadata:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                    required:
                      - license_plan_id
                  description: >-
                    License links to add or override for this customer, keyed by
                    license_plan_id. Omitted fields inherit the plan catalog
                    link (included defaults to 1 when the license is not in the
                    catalog). A bare entry restores the license to pure catalog
                    inheritance.
                remove_licenses:
                  type: array
                  items:
                    type: object
                    properties:
                      license_plan_id:
                        type: string
                    required:
                      - license_plan_id
                  description: >-
                    License links to drop, keyed by license_plan_id. Parallel to
                    remove_items.
              additionalProperties: false
              description: >-
                The customization that transforms the base plan into this
                variant.
          required:
            - base_plan_id
          description: Details about how this variant relates to its latest base plan.
      required:
        - id
        - name
        - description
        - group
        - version
        - add_on
        - auto_enable
        - price
        - items
        - created_at
        - env
        - archived
        - config
        - metadata
        - base_variant_id
    CreditDimension:
      anyOf:
        - type: object
          properties:
            match:
              type: object
              propertyNames:
                type: string
              additionalProperties:
                type: string
              description: >-
                Event properties this entry applies to. Every key must equal the
                tracked property, compared as strings.
            priority:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: >-
                Breaks ties between dimensions that match the same number of
                keys. Higher wins.
            tier_behavior:
              const: graduated
            tiers:
              type: array
              minItems: 1
              items:
                type: object
                properties:
                  to:
                    anyOf:
                      - type: number
                        exclusiveMinimum: 0
                      - enum:
                          - inf
                        type: string
                    description: >-
                      Inclusive upper usage boundary for this graduated tier.
                      The final tier must be 'inf'.
                  credit_cost:
                    type: number
                    minimum: 0
                    description: Credits consumed per billing-unit group within this tier.
                required:
                  - to
                  - credit_cost
          required:
            - match
            - tier_behavior
            - tiers
          additionalProperties: false
        - type: object
          properties:
            match:
              type: object
              propertyNames:
                type: string
              additionalProperties:
                type: string
              description: >-
                Event properties this entry applies to. Every key must equal the
                tracked property, compared as strings.
            priority:
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
              description: >-
                Breaks ties between dimensions that match the same number of
                keys. Higher wins.
            credit_cost:
              type: number
              minimum: 0
              description: >-
                Credits consumed per billing-unit group when this dimension
                matches.
          required:
            - match
            - credit_cost
          additionalProperties: false
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.