> ## Documentation Index
> Fetch the complete documentation index at: https://autumn-b9b4c0fb-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# List all plans
> Lists all plans in the current environment.
Use this to retrieve all plans for displaying pricing pages or managing plan configurations.
Lists all plans in the current environment.
Pass a `customer_id` to include customer-specific eligibility info like whether a free trial is available and the attach scenario (new, upgrade, downgrade).
### Common Use Cases
```typescript List all plans theme={null}
const plans = await autumn.plans.list();
```
```typescript List plans with customer eligibility theme={null}
const plans = await autumn.plans.list({
customerId: "cus_123"
});
// Each plan will include customerEligibility:
// - trialAvailable: whether customer can use the trial
// - scenario: 'new', 'upgrade', 'downgrade', etc.
```
```typescript Include archived plans theme={null}
const plans = await autumn.plans.list({
includeArchived: true
});
```
### Body Parameters
Customer ID to include eligibility info (trial availability, attach scenario).
Entity ID for entity-scoped plans.
If true, includes archived plans in the response.
If true, includes all plan versions.
### Response
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.
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.
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.
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.
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.
The ID of the feature this item configures.
The full feature object if expanded.
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.
The singular display name for the feature.
The plural display name for the feature.
Credit cost schema for credit system features.
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.
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.
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).
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.
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.
Billing interval for this price. For consumable features, should match reset.interval.
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.
Stripe price ID. For prepaid with included > 0 this is the V2 price.
Display text for showing this item in pricing pages.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
Payment processors this plan is connected to. Omitted when unset.
Stripe product ID this plan is billed under.
Extra Stripe product IDs aliased to this plan.
Every RevenueCat product that maps to this plan. Replaces the current set.
RevenueCat product ID that grants this plan when purchased.
Prepaid quantities granted when this specific RevenueCat product is purchased, in feature units.
Free trial configuration. If set, new customers can try this plan before being charged.
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.
If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past\_due state.
Plan-level billing controls used as customer defaults.
List of auto top-up configurations per feature.
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.
The time interval for the purchase limit window.
Number of intervals in the purchase limit window.
Maximum number of auto top-ups allowed within the interval.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
List of overage spend limits per feature (caps overage spend).
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).
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.
List of usage alert configurations per feature.
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 (0-100).
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.
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.
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.
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.
The ID of the base plan this variant was derived from.
The customization that transforms the base plan into this variant.
Base price configuration for a plan.
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.
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.
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.
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.
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'.
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.
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.
Billing interval. For consumable features, should match reset.interval.
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.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
Filters selecting items to remove from the plan.
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.
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.
List of auto top-up configurations per feature.
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 to set the current window's consumed top-ups.
The time interval for the purchase limit window.
Number of intervals in the purchase limit window.
Maximum number of auto top-ups allowed within the interval.
Set the current window's consumed auto top-up count. 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).
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).
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.
List of usage alert configurations per feature.
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 (0-100).
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.
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.
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.
Base price configuration for a plan.
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.
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.
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.
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.
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'.
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.
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.
Billing interval. For consumable features, should match reset.interval.
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.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
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.
Plans offered as assignable licenses under this plan. Omitted when the plan has none.
The plan offered as a license under this plan.
The exact license-plan version pinned by this link.
Version slug of the license-plan row this link points at.
Number of license assignments included with this plan for free.
Assignments are capped at the included quantity. Must be true for now; overflow billing (false) is not yet available.
The item and price diff applied to this parent-plan link.
Base price configuration for a plan.
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.
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.
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.
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.
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'.
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.
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.
Billing interval. For consumable features, should match reset.interval.
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.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
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.
Arbitrary key-value metadata defined by you on this link.
The effective plan for this license link — the pinned version, with the link's customize applied. Present when license plans are expanded.
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.
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.
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.
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.
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.
The ID of the feature this item configures.
The full feature object if expanded.
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.
The singular display name for the feature.
The plural display name for the feature.
Credit cost schema for credit system features.
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.
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.
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).
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.
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.
Billing interval for this price. For consumable features, should match reset.interval.
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.
Stripe price ID. For prepaid with included > 0 this is the V2 price.
Display text for showing this item in pricing pages.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
Payment processors this plan is connected to. Omitted when unset.
Stripe product ID this plan is billed under.
Extra Stripe product IDs aliased to this plan.
Every RevenueCat product that maps to this plan. Replaces the current set.
RevenueCat product ID that grants this plan when purchased.
Prepaid quantities granted when this specific RevenueCat product is purchased, in feature units.
Free trial configuration. If set, new customers can try this plan before being charged.
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.
If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past\_due state.
Plan-level billing controls used as customer defaults.
List of auto top-up configurations per feature.
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.
The time interval for the purchase limit window.
Number of intervals in the purchase limit window.
Maximum number of auto top-ups allowed within the interval.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
List of overage spend limits per feature (caps overage spend).
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).
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.
List of usage alert configurations per feature.
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 (0-100).
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.
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.
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.
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.
The ID of the base plan this variant was derived from.
The customization that transforms the base plan into this variant.
Base price configuration for a plan.
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.
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.
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.
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.
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'.
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.
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.
Billing interval. For consumable features, should match reset.interval.
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.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
Filters selecting items to remove from the plan.
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.
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.
List of auto top-up configurations per feature.
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 to set the current window's consumed top-ups.
The time interval for the purchase limit window.
Number of intervals in the purchase limit window.
Maximum number of auto top-ups allowed within the interval.
Set the current window's consumed auto top-up count. 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).
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).
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.
List of usage alert configurations per feature.
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 (0-100).
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.
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.
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.
Base price configuration for a plan.
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.
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.
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.
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.
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'.
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.
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.
Billing interval. For consumable features, should match reset.interval.
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.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
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.
Variant plans derived from this base plan. Omitted when the plan has none.
The plan ID of the variant derived from this base plan.
Display name of the variant plan.
The variant's declared divergence from its base plan — exactly what you would re-submit to recreate it.
Base price configuration for a plan.
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.
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.
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.
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.
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'.
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.
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.
Billing interval. For consumable features, should match reset.interval.
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.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
Filters selecting items to remove from the plan.
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.
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.
List of auto top-up configurations per feature.
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 to set the current window's consumed top-ups.
The time interval for the purchase limit window.
Number of intervals in the purchase limit window.
Maximum number of auto top-ups allowed within the interval.
Set the current window's consumed auto top-up count. 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).
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).
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.
List of usage alert configurations per feature.
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 (0-100).
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.
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.
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.
Base price configuration for a plan.
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.
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.
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.
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.
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'.
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.
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.
Billing interval. For consumable features, should match reset.interval.
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.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
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.
The variant's fully resolved plan (base + customize applied). Present when variants are expanded.
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.
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.
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.
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.
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.
The ID of the feature this item configures.
The full feature object if expanded.
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.
The singular display name for the feature.
The plural display name for the feature.
Credit cost schema for credit system features.
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.
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.
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).
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.
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.
Billing interval for this price. For consumable features, should match reset.interval.
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.
Stripe price ID. For prepaid with included > 0 this is the V2 price.
Display text for showing this item in pricing pages.
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.
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.
Overrides fields of this item's feature for customers on this plan (e.g. a credit system's credit\_schema).
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
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.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
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.
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.
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.
Default percentage markup for customers on this plan. Use -100 to make usage free.
Per-provider markup percentages for customers on this plan.
Per-model markup overrides for customers on this plan.
Payment processors this plan is connected to. Omitted when unset.
Stripe product ID this plan is billed under.
Extra Stripe product IDs aliased to this plan.
Every RevenueCat product that maps to this plan. Replaces the current set.
RevenueCat product ID that grants this plan when purchased.
Prepaid quantities granted when this specific RevenueCat product is purchased, in feature units.
Free trial configuration. If set, new customers can try this plan before being charged.
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.
If true, entitlements attached to this plan will still reset on schedule even when the customer's product is in a past\_due state.
Plan-level billing controls used as customer defaults.
List of auto top-up configurations per feature.
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.
The time interval for the purchase limit window.
Number of intervals in the purchase limit window.
Maximum number of auto top-ups allowed within the interval.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
List of overage spend limits per feature (caps overage spend).
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).
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.
List of usage alert configurations per feature.
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 (0-100).
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.
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.
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.
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.
```json 200 theme={null}
{
"list": [
{
"id": "pro",
"name": "Pro Plan",
"description": null,
"group": null,
"version": 1,
"version_slug": "v1",
"active": true,
"addOn": false,
"autoEnable": false,
"price": {
"amount": 10,
"interval": "month",
"display": {
"primaryText": "$10",
"secondaryText": "per month"
}
},
"items": [
{
"featureId": "messages",
"included": 100,
"unlimited": false,
"reset": {
"interval": "month"
},
"price": {
"amount": 0.5,
"interval": "month",
"billingUnits": 100,
"billingMethod": "usage_based",
"maxPurchase": null
},
"display": {
"primaryText": "100 messages",
"secondaryText": "then $0.5 per 100 messages"
}
},
{
"featureId": "users",
"included": 0,
"unlimited": false,
"reset": null,
"price": {
"amount": 10,
"interval": "month",
"billingUnits": 1,
"billingMethod": "prepaid",
"maxPurchase": null
},
"display": {
"primaryText": "$10 per Users"
}
}
],
"createdAt": 1771513979217,
"env": "sandbox",
"archived": false,
"baseVariantId": null,
"config": {
"ignore_past_due": false
},
"billing_controls": {},
"metadata": {},
"licenses": [
{
"license_plan_id": "seat",
"version": 1,
"version_slug": "v1",
"included": 3
}
]
}
]
}
```
## OpenAPI
````yaml openapi POST /v1/plans.list
openapi: 3.1.0
info:
title: Autumn API
version: 2.4.0
servers:
- url: https://api.useautumn.com
description: Production server
security:
- secretKey: []
paths:
/v1/plans.list:
post:
tags:
- plans
summary: List all plans
description: >-
Lists all plans in the current environment.
Use this to retrieve all plans for displaying pricing pages or managing
plan configurations.
operationId: listPlans
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
default: 2.4.0
x-speakeasy-globals-hidden: true
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
customer_id:
type: string
description: >-
Customer ID to include eligibility info (trial availability,
attach scenario).
entity_id:
type: string
description: Entity ID for entity-scoped plans.
include_archived:
type: boolean
description: If true, includes archived plans in the response.
all_versions:
type: boolean
description: If true, includes all plan versions.
title: ListPlansParams
examples:
- {}
- customer_id: cus_123
- include_archived: true
example: {}
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
list:
type: array
items:
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'
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:
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
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval for this price. For
consumable features, should match
reset.interval.
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'
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.
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:
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
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:
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
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
description: >-
For credit system features: replaces the
feature's credit_schema entirely for
customers on this plan.
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'
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.
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:
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
minimum: 1
description: >-
Maximum number of auto top-ups allowed
within the interval.
required:
- interval
- limit
description: >-
Optional rate limit to cap how often auto
top-ups occur.
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
minimum: 0
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
(0-100).
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.
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:
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.
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
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable
features, should match reset.interval.
interval_count:
type: number
default: 1
description: >-
Number of intervals per billing cycle.
Defaults to 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.
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:
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: {}
description: {}
credit_cost:
type: {}
minimum: {}
description: {}
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
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:
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: {}
description: {}
credit_cost:
type: {}
minimum: {}
description: {}
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
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
description: >-
For credit system features: replaces the
feature's credit_schema entirely for
customers on this plan.
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.
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:
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
minimum: 1
description: >-
Maximum number of auto top-ups allowed
within the interval.
count:
type: number
minimum: 0
description: >-
Set the current window's consumed auto
top-up count. Omit to leave runtime
state unchanged.
required:
- interval
- limit
description: >-
Optional rate limit to cap how often
auto top-ups occur. Pass count to set
the current window's consumed top-ups.
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
minimum: 0
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 (0-100).
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: >-
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.
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:
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.
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: {}
description: {}
amount:
type: {}
description: {}
flat_amount:
type: {}
description: {}
required:
- currency
required:
- to
- amount
description: >-
Tiered pricing. Either 'amount' or
'tiers' is required.
tier_behavior:
enum:
- graduated
- volume
type: string
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable
features, should match reset.interval.
interval_count:
type: number
default: 1
description: >-
Number of intervals per billing cycle.
Defaults to 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.
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:
anyOf: {}
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: {}
properties: {}
required: {}
additionalProperties: {}
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: {}
properties: {}
required: {}
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:
anyOf: {}
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: {}
properties: {}
required: {}
additionalProperties: {}
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
description: >-
For credit system features: replaces the
feature's credit_schema entirely for
customers on this plan.
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: {}
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: {}
input_cost: {}
output_cost: {}
- 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.
licenses:
type: array
items:
type: object
properties:
license_plan_id:
type: string
description: The plan offered as a license under this plan.
version:
type: integer
minimum: 1
maximum: 9007199254740991
description: >-
The exact license-plan version pinned by this
link.
version_slug:
type: string
description: >-
Version slug of the license-plan row this link
points at.
included:
type: number
description: >-
Number of license assignments included with
this plan for free.
prepaid_only:
type: boolean
description: >-
Assignments are capped at the included
quantity. Must be true for now; overflow
billing (false) is not yet available.
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.
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:
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.
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
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable
features, should match reset.interval.
interval_count:
type: number
default: 1
description: >-
Number of intervals per billing cycle.
Defaults to 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.
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:
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: {}
credit_cost: {}
required:
- {}
- {}
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
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:
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: {}
credit_cost: {}
required:
- {}
- {}
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
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
description: >-
For credit system features: replaces the
feature's credit_schema entirely for
customers on this plan.
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).
description: >-
The item and price diff applied to this
parent-plan link.
metadata:
type: object
propertyNames:
type: string
additionalProperties: {}
description: >-
Arbitrary key-value metadata defined by you on
this link.
plan:
$ref: '#/components/schemas/Plan'
description: >-
The effective plan for this license link — the
pinned version, with the link's customize
applied. Present when license plans are
expanded.
required:
- license_plan_id
- version
- included
- prepaid_only
description: >-
Plans offered as assignable licenses under this
plan. Omitted when the plan has none.
variants:
type: array
items:
type: object
properties:
variant_plan_id:
type: string
description: >-
The plan ID of the variant derived from this
base plan.
name:
type: string
description: Display name of the variant plan.
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.
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:
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.
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
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable
features, should match reset.interval.
interval_count:
type: number
default: 1
description: >-
Number of intervals per billing cycle.
Defaults to 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.
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:
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: {}
credit_cost: {}
required:
- {}
- {}
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
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:
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: {}
credit_cost: {}
required:
- {}
- {}
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
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
description: >-
For credit system features: replaces the
feature's credit_schema entirely for
customers on this plan.
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.
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:
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
minimum: 1
description: >-
Maximum number of auto top-ups allowed
within the interval.
count:
type: number
minimum: 0
description: >-
Set the current window's consumed auto
top-up count. Omit to leave runtime
state unchanged.
required:
- interval
- limit
description: >-
Optional rate limit to cap how often
auto top-ups occur. Pass count to set
the current window's consumed top-ups.
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
minimum: 0
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 (0-100).
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: >-
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.
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:
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.
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: {}
- const: {}
amount:
type: number
flat_amount:
type: number
additional_currencies:
type: array
items:
type: object
properties:
currency: {}
amount: {}
flat_amount: {}
required:
- {}
required:
- to
- amount
description: >-
Tiered pricing. Either 'amount' or
'tiers' is required.
tier_behavior:
enum:
- graduated
- volume
type: string
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable
features, should match reset.interval.
interval_count:
type: number
default: 1
description: >-
Number of intervals per billing cycle.
Defaults to 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.
feature_override:
type: object
properties:
credit_schema:
type: array
items:
anyOf:
- type: object
properties:
metered_feature_id:
type: {}
minLength: {}
description: {}
billing_units:
type: {}
exclusiveMinimum: {}
description: {}
dimensions:
type: {}
propertyNames: {}
additionalProperties: {}
description: {}
multipliers:
type: {}
propertyNames: {}
additionalProperties: {}
description: {}
tier_behavior:
const: {}
tiers:
type: {}
minItems: {}
items: {}
required:
- metered_feature_id
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
metered_feature_id:
type: {}
minLength: {}
description: {}
billing_units:
type: {}
exclusiveMinimum: {}
description: {}
dimensions:
type: {}
propertyNames: {}
additionalProperties: {}
description: {}
multipliers:
type: {}
propertyNames: {}
additionalProperties: {}
description: {}
credit_cost:
type: {}
minimum: {}
description: {}
required:
- metered_feature_id
- credit_cost
additionalProperties: false
description: >-
For credit system features: replaces the
feature's credit_schema entirely for
customers on this plan.
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: {}
properties: {}
required: {}
- type: 'null'
description: >-
Per-provider markup percentages for
customers on this plan.
model_markups:
anyOf:
- type: object
propertyNames:
type: string
pattern: .+\/.+
additionalProperties:
type: {}
properties: {}
- 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 variant's declared divergence from its
base plan — exactly what you would re-submit
to recreate it.
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'
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:
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
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval for this price. For
consumable features, should match
reset.interval.
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'
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.
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:
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: {}
credit_cost: {}
required:
- {}
- {}
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
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:
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: {}
credit_cost: {}
required:
- {}
- {}
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
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
description: >-
For credit system features: replaces the
feature's credit_schema entirely for
customers on this plan.
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'
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.
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:
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
minimum: 1
description: >-
Maximum number of auto top-ups allowed
within the interval.
required:
- interval
- limit
description: >-
Optional rate limit to cap how often
auto top-ups occur.
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
minimum: 0
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 (0-100).
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.
required:
- id
- name
- description
- group
- version
- add_on
- auto_enable
- price
- items
- created_at
- env
- archived
- config
- metadata
- base_variant_id
description: >-
The variant's fully resolved plan (base +
customize applied). Present when variants are
expanded.
required:
- variant_plan_id
- name
description: >-
Variant plans derived from this base plan. Omitted
when the plan has none.
required:
- id
- name
- description
- group
- version
- add_on
- auto_enable
- price
- items
- created_at
- env
- archived
- config
- metadata
- base_variant_id
description: >-
A plan defines features, pricing, entitlements,
assignable licenses, and derived variants.
required:
- list
examples:
- list:
- id: pro
name: Pro Plan
description: null
group: null
version: 1
version_slug: v1
active: true
addOn: false
autoEnable: false
price:
amount: 10
interval: month
display:
primaryText: $10
secondaryText: per month
items:
- featureId: messages
included: 100
unlimited: false
reset:
interval: month
price:
amount: 0.5
interval: month
billingUnits: 100
billingMethod: usage_based
maxPurchase: null
display:
primaryText: 100 messages
secondaryText: then $0.5 per 100 messages
- featureId: users
included: 0
unlimited: false
reset: null
price:
amount: 10
interval: month
billingUnits: 1
billingMethod: prepaid
maxPurchase: null
display:
primaryText: $10 per Users
createdAt: 1771513979217
env: sandbox
archived: false
baseVariantId: null
config:
ignore_past_due: false
billing_controls: {}
metadata: {}
licenses:
- license_plan_id: seat
version: 1
version_slug: v1
included: 3
example:
list:
- id: pro
name: Pro Plan
description: null
group: null
version: 1
version_slug: v1
active: true
addOn: false
autoEnable: false
price:
amount: 10
interval: month
display:
primaryText: $10
secondaryText: per month
items:
- featureId: messages
included: 100
unlimited: false
reset:
interval: month
price:
amount: 0.5
interval: month
billingUnits: 100
billingMethod: usage_based
maxPurchase: null
display:
primaryText: 100 messages
secondaryText: then $0.5 per 100 messages
- featureId: users
included: 0
unlimited: false
reset: null
price:
amount: 10
interval: month
billingUnits: 1
billingMethod: prepaid
maxPurchase: null
display:
primaryText: $10 per Users
createdAt: 1771513979217
env: sandbox
archived: false
baseVariantId: null
config:
ignore_past_due: false
billing_controls: {}
metadata: {}
licenses:
- license_plan_id: seat
version: 1
version_slug: v1
included: 3
x-codeSamples:
- lang: typescript
label: Typescript (SDK)
source: |-
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.plans.list({});
- lang: python
label: Python (SDK)
source: |-
from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.plans.list(
request={},
)
components:
schemas:
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'
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:
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
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval for this price. For consumable
features, should match reset.interval.
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'
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.
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:
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
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:
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
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
description: >-
For credit system features: replaces the feature's
credit_schema entirely for customers on this plan.
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'
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.
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:
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
minimum: 1
description: >-
Maximum number of auto top-ups allowed within the
interval.
required:
- interval
- limit
description: Optional rate limit to cap how often auto top-ups occur.
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
minimum: 0
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 (0-100).
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.
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:
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.
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
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable features, should
match reset.interval.
interval_count:
type: number
default: 1
description: >-
Number of intervals per billing cycle. Defaults to
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.
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:
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
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:
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
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
description: >-
For credit system features: replaces the feature's
credit_schema entirely for customers on this plan.
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.
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:
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
minimum: 1
description: >-
Maximum number of auto top-ups allowed within
the interval.
count:
type: number
minimum: 0
description: >-
Set the current window's consumed auto top-up
count. Omit to leave runtime state unchanged.
required:
- interval
- limit
description: >-
Optional rate limit to cap how often auto top-ups
occur. Pass count to set the current window's
consumed top-ups.
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
minimum: 0
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 (0-100).
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: >-
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.
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:
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.
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
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable
features, should match reset.interval.
interval_count:
type: number
default: 1
description: >-
Number of intervals per billing cycle.
Defaults to 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.
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:
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:
- {}
- {}
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
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:
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:
- {}
- {}
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
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
description: >-
For credit system features: replaces the
feature's credit_schema entirely for
customers on this plan.
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
securitySchemes:
secretKey:
type: http
scheme: bearer
bearerFormat: JWT
````