# Create Balance
Source: https://docs.useautumn.com/api-reference/balances/createBalance
openapi POST /v1/balances.create
Create a balance for a customer feature.
### Body Parameters
The ID of the customer.
The ID of the feature.
The ID of the entity for entity-scoped balances (e.g., per-seat limits).
The initial balance amount to grant. For metered features, this is the number of units the customer can use.
If true, the balance has unlimited usage. Cannot be combined with 'included\_grant'.
Reset configuration for the balance. If not provided, the balance is a one-time grant that never resets.
The interval at which the balance resets (e.g., 'month', 'day', 'year').
Number of intervals between resets. Defaults to 1 (e.g., interval\_count: 2 with interval: 'month' resets every 2 months).
Rollover configuration for the balance.
Unix timestamp (milliseconds) when the balance expires. Mutually exclusive with reset.
Unix timestamp (milliseconds) for the first reset boundary, allowing a custom (e.g. shorter) first period. Requires 'reset', and must occur before 'expires\_at' if both are provided. Subsequent resets advance by one reset interval from this boundary.
A unique identifier for this balance. Use this to target the balance in future update / delete calls.
### Response
# Delete Balance
Source: https://docs.useautumn.com/api-reference/balances/deleteBalance
openapi POST /v1/balances.delete
Delete a balance for a customer feature. Can only delete a balance that is not attached to a price (eg. you cannot delete messages that have an overage price).
### Body Parameters
The ID of the customer.
The ID of the entity.
The ID of the feature.
The ID of the balance to delete.
If true, deduct the deleted balance's remaining amount from the customer's other balances for the same feature after deletion.
Target a specific balance by its reset interval. Use when the customer has multiple balances for the same feature with different reset intervals.
### Response
# Finalize Lock
Source: https://docs.useautumn.com/api-reference/balances/finalizeLock
openapi POST /v1/balances.finalize
Finalize a previously locked balance. Use 'confirm' to commit the deduction, or 'release' to return the held balance.
### Body Parameters
The lock ID that was passed into the previous check call.
Use 'confirm' to commit the deduction, or 'release' to return the held balance.
Additional properties to attach to this finalize lock event.
Additional properties to attach to this finalize lock event.
### Response
# Track Token Usage
Source: https://docs.useautumn.com/api-reference/balances/trackTokens
openapi POST /v1/balances.track_tokens
Records AI token usage for a customer and returns the updated AI credit balance.
Use this after an LLM request when you have input and output token counts. Autumn converts token usage to a dollar amount using the configured model pricing and markup, then tracks that value against the customer's AI credit system.
Track AI token usage against a customer's AI credit system balance. Converts token counts to a dollar cost using [Models.dev](https://models.dev) pricing and your configured markup, then deducts from the customer's credit balance.
The `model_id` must use `provider/model` format, matching the provider and model keys from [Models.dev](https://models.dev). For providers with nested model paths (like OpenRouter), include the full path: `openrouter/anthropic/claude-opus-4.6`. The first path segment is the provider key used for provider-level markup lookup.
### Common Use Cases
```typescript Anthropic theme={null}
await autumn.balances.trackTokens({
customerId: "cus_123",
modelId: "anthropic/claude-opus-4-6",
inputTokens: 1000,
outputTokens: 500
});
```
```typescript With cache + reasoning theme={null}
await autumn.balances.trackTokens({
customerId: "cus_123",
modelId: "anthropic/claude-opus-4-6",
inputTokens: 800, // excludes the cached tokens below
outputTokens: 350, // excludes the reasoning tokens below
cacheReadTokens: 1000,
cacheWriteTokens: 200,
reasoningTokens: 150
});
```
```typescript OpenRouter (nested path) theme={null}
await autumn.balances.trackTokens({
customerId: "cus_123",
modelId: "openrouter/anthropic/claude-opus-4.6",
inputTokens: 2000,
outputTokens: 1000
});
```
```typescript With explicit feature theme={null}
await autumn.balances.trackTokens({
customerId: "cus_123",
featureId: "ai_credits",
modelId: "anthropic/claude-haiku-4-5",
inputTokens: 2000,
outputTokens: 1000
});
```
### Token Pools
Each token parameter is an exclusive pool — no token should be counted in more than one. Each pool is billed at the model's published rate for that pool, falling back to the text input/output rate when the model has none.
If you pass a provider's raw totals (e.g. OpenAI's `prompt_tokens` and `completion_tokens`), subtract the cache and reasoning counts first — otherwise those tokens are billed twice. The `@useautumn/gateway` wrappers ([AI SDK](/documentation/external-providers/ai-sdk), [OpenRouter](/documentation/external-providers/openrouter)) do this normalization for you.
### Markup Resolution
Markups are optional — the credit system's default markup applies unless overridden per provider or per model. With no markups set, the Models.dev base cost is charged as-is. A markup of `-100` makes the model free — the usage event is still recorded, but nothing is deducted. See [AI Credit Systems](/documentation/modelling-pricing/credit-systems#ai-credit-systems) for configuration.
`feature_id` is auto-detected when the customer has exactly one AI credit system. The request fails if the customer has none, or has more than one and `feature_id` is omitted.
### Body Parameters
The ID of the customer.
The AI model in `provider/model` format, matching keys from [Models.dev](https://models.dev) (e.g., `anthropic/claude-opus-4-6`, `openai/gpt-4o`, `openrouter/anthropic/claude-opus-4.6`).
Number of non-cached text input tokens consumed. Exclusive of the cache and audio token pools.
Number of text output tokens consumed. Exclusive of the reasoning and audio output pools.
Number of cached input tokens read, billed at the model's cache read rate.
Number of input tokens written to the cache, billed at the model's cache write rate.
Number of reasoning tokens generated, billed at the model's reasoning rate (falls back to the output rate).
Number of audio input tokens consumed, billed at the model's audio input rate (falls back to the input rate).
Number of audio output tokens generated, billed at the model's audio output rate (falls back to the output rate).
The ID of the AI credit system feature. If omitted, automatically detects the customer's AI credit system feature. Required when the customer has more than one.
The ID of the entity for entity-scoped balances.
Additional properties to attach to this usage event. The token counts and a pricing breakdown (`cost`, `base_cost`, `markup`, `markup_source`, `tier_applied`, `rates`) are automatically included.
### Response
The ID of the customer whose token usage was tracked.
The dollar cost that was deducted from the customer's AI credit balance.
The updated balance for the AI credit system feature.
The feature ID this balance is for.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed.
Timestamp when the balance will reset, or null for no reset.
```json 200 theme={null}
{
"customer_id": "cus_123",
"value": 0.06,
"balance": {
"feature_id": "ai_credits",
"granted": 10.00,
"remaining": 9.94,
"usage": 0.06,
"unlimited": false,
"overage_allowed": false,
"next_reset_at": 1773851121437,
"breakdown": [
{
"id": "cus_ent_abc123",
"plan_id": "pro_plan",
"included_grant": 10.00,
"prepaid_grant": 0,
"remaining": 9.94,
"usage": 0.06,
"unlimited": false,
"reset": {
"interval": "month",
"resets_at": 1773851121437
},
"price": null,
"expires_at": null
}
]
}
}
```
# Update Balance
Source: https://docs.useautumn.com/api-reference/balances/updateBalance
openapi POST /v1/balances.update
Update a customer balance.
### Body Parameters
The ID of the customer.
The ID of the feature.
The ID of the entity for entity-scoped balances (e.g., per-seat limits).
Set the remaining balance to this exact value. Cannot be combined with add\_to\_balance.
Add this amount to the current balance. Use negative values to subtract. Cannot be combined with current\_balance.
The usage amount to update. Cannot be combined with remaining or add\_to\_balance.
Target a specific balance by its reset interval. Use when the customer has multiple balances for the same feature with different reset intervals.
Set the granted balance to this exact value.
Target a specific balance by its ID (set on create). Use when the customer has multiple balances for the same feature.
The next reset time for the balance. If there are multiple breakdowns, this will update the breakdown with the next reset time.
Unix timestamp (milliseconds) when the balance expires. Targets a specific balance via balance\_id / interval when the customer has multiple balances for the same feature.
### Response
# Attach
Source: https://docs.useautumn.com/api-reference/billing/attach
openapi POST /v1/billing.attach
Attaches a plan to a customer. Handles new subscriptions, upgrades and downgrades.
Use this endpoint to subscribe a customer to a plan, upgrade/downgrade between plans, or add an add-on product.
The attach endpoint subscribes a customer to a plan. It handles new
subscriptions, upgrades, and downgrades automatically. For modifying an
existing subscription (like changing quantities or canceling), use
[update](/api-reference/billing/billingUpdate) instead.
### Common Use Cases
```typescript Subscribe to a plan theme={null}
const response = await autumn.billing.attach({
customerId: "cus_123",
planId: "pro_plan",
});
if (response.paymentUrl) {
// Redirect customer to checkout
window.location.href = response.paymentUrl;
}
```
```typescript Custom pricing theme={null}
const response = await autumn.billing.attach({
customerId: "cus_123",
planId: "enterprise_plan",
customize: {
price: {
amount: 999, // $999
interval: "month",
},
},
});
```
```typescript Attach plan with prepaid quantities theme={null}
const response = await autumn.billing.attach({
customerId: "cus_123",
planId: "team_plan",
featureQuantities: [{ featureId: "seats", quantity: 5 }],
});
```
```typescript Pass metadata to Stripe subscription theme={null}
const response = await autumn.billing.attach({
customerId: "cus_123",
planId: "pro_plan",
checkoutSessionParams: {
subscriptionData: {
metadata: {
userId: "internal-user-id",
source: "upgrade-flow",
},
},
},
});
```
### Stripe checkout session params
Use `checkoutSessionParams` to pass additional data to the Stripe checkout session. Values you provide are deep-merged with Autumn's internal parameters, so your fields are preserved alongside ones Autumn sets automatically (like `trial_end` or internal metadata).
This is useful for attaching custom metadata to the Stripe subscription created during checkout — for example, linking subscriptions to internal user IDs or tracking the source of the purchase.
### Currency
Pass `currency` to bill the attach in a specific currency the plan offers via [`additional_currencies`](/documentation/concepts/plans#multiple-currencies). If omitted, Autumn uses the customer's currency, falling back to your organization's default.
A customer who has paid is locked to their currency: passing a different one, or attaching a plan that doesn't offer a paid price in their currency, fails with a `currency_mismatch` error before any billing happens.
### Body Parameters
The ID of the customer to attach the plan to.
The ID of the entity to attach the plan to.
The ID of the plan.
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
The version of the plan to attach.
Free trial configuration for a plan.
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.
Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.
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.
Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add\_items / remove\_items / deprecated update\_items.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Items to add to the plan.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send\_invoice collection method.
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send\_invoice collection method.
If true, enables the plan immediately even though the invoice is not paid yet.
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).
How to handle proration when updating an existing subscription. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if\_required' only when payment action is needed, 'never' disables redirects.
A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
URL to redirect to after successful checkout.
Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
Reset the billing cycle immediately with 'now', or schedule a reset at a future Unix timestamp in milliseconds.
When the plan change should take effect. 'immediate' applies now, 'end\_of\_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription.
Unix timestamp in milliseconds for when the attached plan should end.
Additional parameters to pass into the creation of the Stripe checkout session.
If true, returns an Autumn-hosted checkout link that can create a fresh Stripe checkout session when opened.
Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans).
Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
Description for the line item.
The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.
Whether to carry over balances from the previous plan.
Whether to carry over balances from the previous plan.
The IDs of the features to carry over balances from. If left undefined, all features will be carried over.
Whether to carry over usages from the previous plan.
Whether to carry over usages from the previous plan.
The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.
Seat quantities for the plan's licenses, keyed by license plan.
The license plan to set seat quantity for.
Total seats for the license, inclusive of the plan's included amount — seats beyond it are paid.
Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn\_' are reserved and will be stripped.
If true, skips any billing changes for the attach operation.
If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer\_product is inserted before the customer completes the hosted form. Set it here rather than on `invoice_mode`, which only covers the invoice-unpaid case.
Stripe tax rate ID (txr\_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items.
Currency to bill this attach in (e.g. usd, eur). Must match the customer's currency if they are already locked to one, and the plan must offer a paid price in it. Defaults to the customer's currency, then the org default.
Plan IDs to expire on the customer as part of this attach. Each must be an active plan billed on the same subscription as the attach (or a free plan); plans on a separate subscription are rejected.
### Response
The ID of the customer.
The ID of the entity, if the plan was attached to an entity.
Invoice details if an invoice was created. Only present when a charge was made.
The status of the invoice (e.g., 'paid', 'open', 'draft').
The Stripe invoice ID.
The total amount of the invoice in cents.
The three-letter ISO currency code (e.g., 'usd').
URL to the hosted invoice page where the customer can view and pay the invoice.
URL to redirect the customer to complete payment. Null if no payment action is required.
Details about any action required to complete the payment. Present when the payment could not be processed automatically.
The type of action required to complete the payment.
A human-readable explanation of why this action is required.
```json 200 theme={null}
{
"customer_id": "cus_123",
"payment_url": "https://checkout.stripe.com/..."
}
```
# Update Subscription
Source: https://docs.useautumn.com/api-reference/billing/billingUpdate
openapi POST /v1/billing.update
Updates an existing subscription. Use to modify feature quantities, cancel, or change plan configuration.
Use this endpoint to update prepaid quantities, cancel a subscription (immediately or at end of cycle), or modify subscription settings.
The update endpoint modifies an existing subscription. Use this to change prepaid quantities, cancel subscriptions, or modify plan configuration. For subscribing to a new plan, use [attach](/api-reference/billing/attach) instead.
### Common Use Cases
```typescript Update prepaid quantity theme={null}
const response = await autumn.billing.update({
customerId: "cus_123",
planId: "pro_plan",
featureQuantities: [{ featureId: "seats", quantity: 10 }]
});
```
```typescript Cancel at end of cycle theme={null}
const response = await autumn.billing.update({
customerId: "cus_123",
planId: "pro_plan",
cancelAction: "cancel_end_of_cycle"
});
```
```typescript Uncancel subscription theme={null}
const response = await autumn.billing.update({
customerId: "cus_123",
planId: "pro_plan",
cancelAction: "uncancel"
});
```
### Body Parameters
The ID of the customer to attach the plan to.
The ID of the entity to attach the plan to.
The ID of the plan to update. Optional if subscription\_id is provided, or if the customer has only one product.
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
The version of the plan to attach.
Free trial configuration for a plan.
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.
Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.
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.
Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add\_items / remove\_items / deprecated update\_items.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Items to add to the plan.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send\_invoice collection method.
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send\_invoice collection method.
If true, enables the plan immediately even though the invoice is not paid yet.
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).
How to handle proration when updating an existing subscription. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if\_required' only when payment action is needed, 'never' disables redirects.
A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
Action to perform for cancellation. 'cancel\_immediately' cancels now with prorated refund, 'cancel\_end\_of\_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.
Reset the billing cycle immediately with 'now', or schedule a reset at a future Unix timestamp in milliseconds.
If true, the subscription is updated internally without applying billing changes in Stripe.
Controls how the last payment is refunded on immediate cancellation. 'prorated' refunds the unused portion, 'full' refunds the entire last payment.
Additional parameters to pass into the Stripe subscription update or cancel call.
Controls whether balances should be recalculated during the subscription update.
If true, recalculates balances during the subscription update. Only applicable when updating feature quantities.
Whether to carry over usages from the previous plan.
Whether to carry over usages from the previous plan.
The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.
Total seat quantities (inclusive of the license's included count) per license plan offered by this plan. Licenses not listed keep their current paid quantity.
The license plan to set seat quantity for.
Total seats for the license, inclusive of the plan's included amount — seats beyond it are paid.
Custom line items that replace the auto-generated proration invoice, or bill a standalone invoice when nothing else changes. Only valid on an existing recurring subscription.
Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
Description for the line item.
### Response
The ID of the customer.
The ID of the entity, if the plan was attached to an entity.
Invoice details if an invoice was created. Only present when a charge was made.
The status of the invoice (e.g., 'paid', 'open', 'draft').
The Stripe invoice ID.
The total amount of the invoice in cents.
The three-letter ISO currency code (e.g., 'usd').
URL to the hosted invoice page where the customer can view and pay the invoice.
URL to redirect the customer to complete payment. Null if no payment action is required.
Details about any action required to complete the payment. Present when the payment could not be processed automatically.
The type of action required to complete the payment.
A human-readable explanation of why this action is required.
```json 200 theme={null}
{
"customer_id": "cus_123",
"invoice": {
"status": "paid",
"stripe_id": "in_1234",
"total": 1500,
"currency": "usd",
"hosted_invoice_url": "https://invoice.stripe.com/..."
},
"payment_url": null
}
```
# Create Schedule
Source: https://docs.useautumn.com/api-reference/billing/createSchedule
openapi POST /v1/billing.create_schedule
Creates a multi-phase subscription schedule for a customer. The first phase starts immediately and subsequent phases automatically transition at their scheduled start times.
Use this endpoint to schedule future plan changes (e.g. switch from a trial plan to a paid plan on a specific date) or to define a sequence of plans that should activate over time.
### Body Parameters
The ID of the customer to create the schedule for.
Optional entity ID for an entity-scoped schedule.
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.
Three-letter Stripe-supported currency code used to bill the immediate phase (for example, 'usd').
Invoice mode creates and sends an invoice instead of charging the customer's payment method immediately for the first phase.
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send\_invoice collection method.
If true, enables the plan immediately even though the invoice is not paid yet.
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).
List of discounts to apply to the immediate phase. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
URL to redirect to after successful checkout.
Additional parameters to pass into the creation of the Stripe checkout session.
Controls when to return a checkout URL for the immediate phase. 'always' forces a confirmation or checkout flow, 'if\_required' only redirects when needed, and 'never' disables redirects.
Whether to prorate the immediate phase. 'none' skips proration charges and credits.
If true, skips any billing changes for the schedule.
Pass 'now' to reset the billing cycle anchor of the immediate phase to the current time.
If true, the immediate-phase cusProducts are activated immediately (and scheduled-phase cusProducts pre-inserted) even when payment is pending via Stripe checkout. The Autumn schedule rows are persisted on checkout.session.completed.
Deprecated and ignored. Active plans the schedule does not declare are always retained.
Plans billed with the immediate phase that the schedule never expires or replaces. No phase may declare a plan in the same group and scope.
The ID of the plan to schedule in this phase.
The plan scope. Omit to inherit the request entity, pass null for customer-level, or pass an entity ID. On phases after the first, the entity must already be scoped by the first phase — a schedule cannot change scope mid-flight.
Optional prepaid feature quantities for this phase's plan.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
Optional explicit plan version to schedule.
Customize the plan to schedule. Can override price, replace items, or patch items with add\_items and remove\_items.
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.
Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add\_items / remove\_items / deprecated update\_items.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Items to add to the plan.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
A unique ID to identify this subscription. Useful when scheduling the same plan multiple times.
Ordered phase definitions for the schedule.
When this phase should start, in epoch milliseconds, or 'now' for the immediate phase.
Relative start offset from the previous resolved schedule phase.
The duration unit to offset this phase from the prior phase.
How many duration\_type periods after the prior phase to start.
Plans to materialize for this phase.
The ID of the plan to schedule in this phase.
The plan scope. Omit to inherit the request entity, pass null for customer-level, or pass an entity ID. On phases after the first, the entity must already be scoped by the first phase — a schedule cannot change scope mid-flight.
Optional prepaid feature quantities for this phase's plan.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
Optional explicit plan version to schedule.
Customize the plan to schedule. Can override price, replace items, or patch items with add\_items and remove\_items.
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.
Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add\_items / remove\_items / deprecated update\_items.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Items to add to the plan.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
A unique ID to identify this subscription. Useful when scheduling the same plan multiple times.
Pass 'phase\_start' to reset the Stripe billing cycle anchor when this phase starts.
### Response
The ID of the customer.
The entity ID for the schedule, or null when customer-level.
Whether the schedule is fully created or waiting for payment or confirmation to complete.
The ID of the created schedule. Null when the schedule is waiting on Autumn checkout confirmation.
Persisted phases in ascending starts\_at order. Empty when waiting on Autumn checkout confirmation.
The ID of the persisted phase row.
When this phase starts, in epoch milliseconds.
Customer products materialized for this phase.
Invoice details if an invoice was created. Only present when a charge was made.
The status of the invoice (e.g., 'paid', 'open', 'draft').
The Stripe invoice ID.
The total amount of the invoice in cents.
The three-letter ISO currency code (e.g., 'usd').
URL to the hosted invoice page where the customer can view and pay the invoice.
URL to redirect the customer to complete payment. Null if no payment action is required.
The type of action required to complete the payment.
A human-readable explanation of why this action is required.
```json 200 theme={null}
{
"customer_id": "cus_123",
"entity_id": null,
"status": "created",
"schedule_id": "sch_1234",
"phases": [
{
"phase_id": "sphs_1111",
"starts_at": 1735689600000,
"customer_product_ids": [
"cus_prod_1111"
]
},
{
"phase_id": "sphs_2222",
"starts_at": 1736899200000,
"customer_product_ids": [
"cus_prod_2222"
]
}
],
"invoice": null,
"payment_url": null
}
```
# Import
Source: https://docs.useautumn.com/api-reference/billing/import
openapi POST /v1/billing.import
Image a customer into Autumn for live migration. Read-only against processors.
### Body Parameters
Autumn customer to image into.
Optional identity fields upserted onto the customer (applied to existing customers too).
Display name for the customer.
Email address for the customer.
Anti-fraud fingerprint for the customer.
Unix ms timestamp the customer signed up, so a migrated customer keeps its original signup date. Defaults to the import time for a customer Autumn creates here.
The customer's processor identities (e.g. Stripe customer id, RevenueCat app\_user\_id). Omit for customers with no processor, e.g. those only ever on a free plan.
The processor this identity belongs to.
The customer's id in that processor (Stripe customer id, or RevenueCat app\_user\_id).
The billing objects (subscriptions, one-offs) to image, each carrying its plan.
The processor that owns this billable (stripe or revenuecat). Omit for plans with no processor, e.g. a free plan.
Existing processor billing object this billable is adopted from; omit for paid one-offs.
Existing processor subscription id this billable is adopted from.
Existing processor subscription-schedule id this billable is adopted from.
Unix ms billing anchor shared by co-billed plans on this billable.
The single plan on this billable (provide either plan or phases, not both).
The Autumn plan to attach to the customer.
Specific plan version to attach; defaults to the latest.
Set the status of the plan to be flashed. Active if undefined.
When the plan started (Unix ms). Defaults to the linked subscription's start, else the import time. Set this for one-off purchases to record the real purchase date.
Seat/unit quantity for the plan.
Purchased prepaid quantities per feature.
The prepaid feature being quantified.
Purchased quantity for this prepaid feature.
Per-feature balances to image onto the plan.
The feature whose balance is being set.
Disambiguates which entitlement line to target when the feature has multiple.
Reset interval selecting which entitlement line to target when a feature has several ('lifetime' or null = the non-resetting one-off line).
Selects the included vs prepaid vs usage-based (pay-per-use) entitlement line when a feature has several.
Units already consumed; remaining balance is derived from the plan allowance minus this.
Explicit remaining balance override (mutually exclusive with usage).
Unix ms timestamp of this line's next reset.
If true, validate and compute without persisting; returns what would be flashed.
### Response
The imaged customer's id.
Per-plan outcome of the flash.
The plan that was imaged.
The processor that owns the imaged plan.
The created (or existing) customer product id, if any.
The resulting status of the imaged plan.
True if an active plan already existed and this one was left untouched.
True if this was an existing active plan expired because it was absent from the imaged desired state.
True when the imaged state may be wrong — e.g. a resetting plan with no resolvable billing anchor, or a paid recurring plan with no linked subscription for Autumn to manage. The plan is still imaged; see `reason` and fix by supplying started\_at or a subscription\_id.
Why the plan was skipped, expired, or flagged as a mismatch, when applicable.
The freshly-read imaged customer; null for dry\_run.
Your unique identifier for the customer.
The name of the customer.
The email address of the customer.
Timestamp of customer creation in milliseconds since epoch.
A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
Stripe customer ID.
The environment this customer was created in.
The metadata for the customer.
Whether to send email receipts to the customer.
Billing controls for the customer (auto top-ups, etc.)
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. Expand billing\_controls.auto\_topups.purchase\_limit for a count of top ups and the next\_reset\_at.
The time interval for the purchase limit window. Null when no purchase limit is configured.
Number of intervals in the purchase limit window. Null when no purchase limit is configured.
Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured.
Number of auto top-ups already consumed in the current window.
Unix ms timestamp when the current purchase window ends and the count resets.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature, with current interval usage.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Active and scheduled recurring plans that this customer has attached.
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
One-time purchases made by the customer.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
License seat pools granted by the customer's plans, with seat counts.
The plan offered as an assignable license.
The plan that offers this license.
Display name of the license plan.
Total seats the customer has for this license, included plus paid.
Seats currently assigned to entities.
Seats still available to assign.
Paid seats purchased on top of the plan's included amount.
Feature balances keyed by feature ID, showing usage limits and remaining amounts.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Boolean feature flags keyed by feature ID, showing enabled access for on/off features.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Configuration for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.
Stripe processor connection for the customer.
Stripe customer ID.
Vercel processor connection for the customer (public-safe subset).
Vercel marketplace installation ID for this customer.
Vercel account ID associated with the installation.
RevenueCat processor connection for the customer.
Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set.
Invoices for this customer.
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
Upcoming invoice for each of this customer's Stripe subscriptions.
Plan IDs contributing line items to this invoice.
Unix timestamp (milliseconds) when this invoice will be created.
The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).
The total before discounts.
The total after discounts.
The line items this invoice will contain: usage accrued in the closing cycle, plus recurring charges for the opening cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
Entities associated with this customer.
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
Trial usage history for this customer.
Rewards earned or applied for this customer.
Array of active discounts applied to the customer
The unique identifier for this discount
The name of the discount or coupon
The type of reward
The discount value (percentage or fixed amount)
How long the discount lasts
Number of billing periods the discount applies for repeating durations
The currency code for fixed amount discounts
Timestamp when the discount becomes active
Timestamp when the discount expires
The Stripe subscription ID this discount is applied to
Total amount saved from this discount
Referral records for this customer.
The customer's default payment method.
```json 200 theme={null}
{
"customer_id": "cus_123",
"flashed": [
{
"plan_id": "pro",
"processor": "stripe",
"customer_product_id": "cus_prod_123",
"status": "active",
"skipped": false
}
],
"customer": {
"id": "cus_123",
"name": "Jane Doe",
"email": "jane@example.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_stripe_123",
"processors": {
"stripe": {
"id": "cus_stripe_123"
}
},
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"billingControls": {
"autoTopups": []
},
"subscriptions": [
{
"planId": "pro",
"autoEnable": false,
"addOn": false,
"status": "active",
"pastDue": false,
"canceledAt": null,
"expiresAt": null,
"trialEndsAt": null,
"startedAt": 1771431921437,
"currentPeriodStart": 1771431921437,
"currentPeriodEnd": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"balances": {
"messages": {
"featureId": "messages",
"granted": 100,
"remaining": 90,
"usage": 10,
"unlimited": false,
"overageAllowed": false,
"maxPurchase": null,
"nextResetAt": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"planId": "pro",
"includedGrant": 100,
"prepaidGrant": 0,
"remaining": 90,
"usage": 10,
"unlimited": false,
"reset": {
"interval": "month",
"resetsAt": 1773851121437
},
"price": null,
"expiresAt": null
}
]
}
},
"flags": {},
"config": {
"disable_pooled_balance": false,
"disable_overage_billing": false
}
}
}
```
# Multi Attach
Source: https://docs.useautumn.com/api-reference/billing/multiAttach
openapi POST /v1/billing.multi_attach
Attaches multiple plans to a customer in a single request. Creates a single Stripe subscription with all plans consolidated.
Use this endpoint when you need to subscribe a customer to multiple plans at once, such as a base plan plus add-ons, or to create a bundle of products.
### Body Parameters
The ID of the customer to attach the plans to.
The ID of the entity to attach the plans to.
The list of plans to attach to the customer.
The ID of the plan to attach.
Customize the plan to attach. Can override its price or items.
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.
Override the items in the plan.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
The version of the plan to attach.
A unique ID to identify this subscription. Useful when attaching the same plan multiple times.
The entity scope for this plan. Omit to inherit the request scope, or pass null for customer-level.
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.
Unix timestamp in milliseconds for backdating every plan in this multi-attach.
Currency to bill this multi-attach in (e.g. usd, eur). Must match the customer's currency if they are already locked to one, and every plan must offer a paid price in it. Defaults to the customer's currency, then the org default.
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately.
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send\_invoice collection method.
If true, enables the plan immediately even though the invoice is not paid yet.
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
How to handle billing. 'prorate\_immediately' charges/credits prorated amounts now, 'none' does not charge/credit anything.
Pass 'now' to reset the billing cycle of every plan on the subscription to the time of this request.
URL to redirect to after successful checkout.
Additional parameters to pass into the creation of the Stripe checkout session.
Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if\_required' only when payment action is needed, 'never' disables redirects.
Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout.
Customer details to set when creating a customer
Customer's name
Customer's email address
Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
Additional metadata for the customer
Stripe customer ID if you already have one
Whether to create the customer in Stripe
The ID of the free plan to auto-enable for the customer
Whether to send email receipts to this customer
Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.
Billing controls for the customer (auto top-ups, etc.)
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.
Miscellaneous configurations for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
The feature ID that this entity is associated with
Name of the entity
Billing controls for the entity.
List of spend limits per feature. Each entry caps overage (overage\_limit) and/or per-interval usage (usage\_limit).
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 for this entity. An entity entry overrides the customer's for that feature.
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.
### Response
The ID of the customer.
The ID of the entity, if the plan was attached to an entity.
Invoice details if an invoice was created. Only present when a charge was made.
The status of the invoice (e.g., 'paid', 'open', 'draft').
The Stripe invoice ID.
The total amount of the invoice in cents.
The three-letter ISO currency code (e.g., 'usd').
URL to the hosted invoice page where the customer can view and pay the invoice.
URL to redirect the customer to complete payment. Null if no payment action is required.
Details about any action required to complete the payment. Present when the payment could not be processed automatically.
The type of action required to complete the payment.
A human-readable explanation of why this action is required.
```json 200 theme={null}
{
"customer_id": "cus_123",
"invoice": {
"status": "paid",
"stripe_id": "in_1234",
"total": 4900,
"currency": "usd",
"hosted_invoice_url": "https://invoice.stripe.com/..."
},
"payment_url": null
}
```
# Multi Update
Source: https://docs.useautumn.com/api-reference/billing/multiUpdate
openapi POST /v1/billing.multi_update
Updates multiple plans on a customer in a single request. Currently supports cancel actions (immediately, end of cycle, or uncancel) across one or more subscriptions.
Use this endpoint to cancel or uncancel several plans atomically in one call — for example canceling a main plan together with its add-ons, or plans across multiple entities.
The multi update endpoint applies updates to multiple plans in a single,
atomic request. It currently supports cancel actions. For updating a single
plan (like changing quantities or customizing items), use
[update](/api-reference/billing/billingUpdate) instead.
### Common Use Cases
```typescript Cancel a plan and its add-on theme={null}
const response = await autumn.billing.multiUpdate({
customerId: "cus_123",
updates: [
{ planId: "pro_plan", cancelAction: "cancel_end_of_cycle" },
{ planId: "addon_seats", cancelAction: "cancel_end_of_cycle" },
],
});
```
```typescript Cancel immediately with a refund and Stripe reason theme={null}
const response = await autumn.billing.multiUpdate({
customerId: "cus_123",
updates: [
{
planId: "pro_plan",
cancelAction: "cancel_immediately",
refundLastPayment: "full",
subscriptionParams: {
cancellation_details: {
feedback: "too_expensive",
comment: "Switching to a competitor",
},
},
},
],
});
```
### Body Parameters
The ID of the customer to update plans for.
The ID of the entity to update plans for. Individual updates can override this with their own entity\_id.
Controls how the last payment is refunded on immediate cancellation. 'prorated' refunds the unused portion, 'full' refunds the entire last payment.
Additional parameters to pass into the Stripe subscription update or cancel call.
The list of plan updates to apply to the customer.
The ID of the plan to update. Optional if subscription\_id is provided.
A unique ID to identify the subscription to update. Useful when a customer has multiple products with the same plan.
The ID of the entity this update targets. Overrides the top-level entity\_id for this update.
Action to perform for cancellation. 'cancel\_immediately' cancels now with prorated refund, 'cancel\_end\_of\_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.
How to handle proration for this update. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
### Response
The ID of the customer.
The ID of the entity, if the plan was attached to an entity.
Invoice details if an invoice was created. Only present when a charge was made.
The status of the invoice (e.g., 'paid', 'open', 'draft').
The Stripe invoice ID.
The total amount of the invoice in cents.
The three-letter ISO currency code (e.g., 'usd').
URL to the hosted invoice page where the customer can view and pay the invoice.
URL to redirect the customer to complete payment. Null if no payment action is required.
Details about any action required to complete the payment. Present when the payment could not be processed automatically.
The type of action required to complete the payment.
A human-readable explanation of why this action is required.
```json 200 theme={null}
{
"customer_id": "cus_123",
"invoice": {
"status": "paid",
"stripe_id": "in_1234",
"total": -20,
"currency": "usd",
"hosted_invoice_url": "https://invoice.stripe.com/..."
},
"payment_url": null
}
```
# Open Customer Portal
Source: https://docs.useautumn.com/api-reference/billing/openCustomerPortal
openapi POST /v1/billing.open_customer_portal
Create a billing portal session for a customer to manage their subscription.
### Body Parameters
The ID of the customer to open the billing portal for.
Stripe billing portal configuration ID. Create configurations in your Stripe dashboard.
URL to redirect to when back button is clicked in the billing portal
### Response
The ID of the billing portal session
URL to the billing portal
```json 200 theme={null}
{
"customer_id": "cus_123",
"url": "https://billing.stripe.com/session/..."
}
```
# Preview Attach
Source: https://docs.useautumn.com/api-reference/billing/previewAttach
openapi POST /v1/billing.preview_attach
Previews the billing changes that would occur when attaching a plan, without actually making any changes.
Use this endpoint to show customers what they will be charged before confirming a subscription change.
### Body Parameters
The ID of the customer to attach the plan to.
The ID of the entity to attach the plan to.
The ID of the plan.
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
The version of the plan to attach.
Free trial configuration for a plan.
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.
Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.
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.
Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add\_items / remove\_items / deprecated update\_items.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Items to add to the plan.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send\_invoice collection method.
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send\_invoice collection method.
If true, enables the plan immediately even though the invoice is not paid yet.
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).
How to handle proration when updating an existing subscription. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if\_required' only when payment action is needed, 'never' disables redirects.
A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
URL to redirect to after successful checkout.
Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
Reset the billing cycle immediately with 'now', or schedule a reset at a future Unix timestamp in milliseconds.
When the plan change should take effect. 'immediate' applies now, 'end\_of\_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription.
Unix timestamp in milliseconds for when the attached plan should end.
Additional parameters to pass into the creation of the Stripe checkout session.
If true, returns an Autumn-hosted checkout link that can create a fresh Stripe checkout session when opened.
Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans).
Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
Description for the line item.
The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.
Whether to carry over balances from the previous plan.
Whether to carry over balances from the previous plan.
The IDs of the features to carry over balances from. If left undefined, all features will be carried over.
Whether to carry over usages from the previous plan.
Whether to carry over usages from the previous plan.
The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.
Seat quantities for the plan's licenses, keyed by license plan.
The license plan to set seat quantity for.
Total seats for the license, inclusive of the plan's included amount — seats beyond it are paid.
Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn\_' are reserved and will be stripped.
If true, skips any billing changes for the attach operation.
If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer\_product is inserted before the customer completes the hosted form. Set it here rather than on `invoice_mode`, which only covers the invoice-unpaid case.
Stripe tax rate ID (txr\_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items.
Currency to bill this attach in (e.g. usd, eur). Must match the customer's currency if they are already locked to one, and the plan must offer a paid price in it. Defaults to the customer's currency, then the org default.
Plan IDs to expire on the customer as part of this attach. Each must be an active plan billed on the same subscription as the attach (or a free plan); plans on a separate subscription are rejected.
### Response
The ID of the customer.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
The total amount before discounts and tax for the current billing period.
The final amount after discounts and tax for the current billing period.
The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).
True when this change clears the customer's usage balances, so the approver can see usage will reset.
Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
Unix timestamp (milliseconds) when the next billing cycle starts.
The total amount before discounts and tax for the next cycle.
The final amount after discounts and tax for the next cycle.
List of line items for the next billing cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
List of line items for usage-based features in the next cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
Expand the response with additional data.
Products or subscription changes being added or updated.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
Products or subscription changes being removed or ended.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
Whether the customer will be redirected to a checkout page if attach is called.
The type of checkout that will be used if the customer is redirected to a checkout page.
Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location.
Total tax amount in major currency units.
Tax included in line item subtotals.
Tax added on top of subtotals.
Three-letter currency code.
Calculation status ('complete' when Stripe Tax succeeds or 'incomplete' when Stripe Tax returned 0 or errored).
Stripe customer invoice credits preview.
Stripe customer credit balance available, expressed as a positive number in major currency units.
Three-letter currency code.
```json 200 theme={null}
{
"customerId": "charles",
"lineItems": [
{
"display_name": "Pro seed",
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
"subtotal": 20,
"total": 20,
"discounts": []
}
],
"subtotal": 20,
"total": 20,
"currency": "usd"
}
```
# Preview Multi Attach
Source: https://docs.useautumn.com/api-reference/billing/previewMultiAttach
openapi POST /v1/billing.preview_multi_attach
Previews the billing changes that would occur when attaching multiple plans, without actually making any changes.
Use this endpoint to show customers what they will be charged before confirming a multi-plan subscription.
### Body Parameters
The ID of the customer to attach the plans to.
The ID of the entity to attach the plans to.
The list of plans to attach to the customer.
The ID of the plan to attach.
Customize the plan to attach. Can override its price or items.
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.
Override the items in the plan.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
The version of the plan to attach.
A unique ID to identify this subscription. Useful when attaching the same plan multiple times.
The entity scope for this plan. Omit to inherit the request scope, or pass null for customer-level.
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.
Unix timestamp in milliseconds for backdating every plan in this multi-attach.
Currency to bill this multi-attach in (e.g. usd, eur). Must match the customer's currency if they are already locked to one, and every plan must offer a paid price in it. Defaults to the customer's currency, then the org default.
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately.
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send\_invoice collection method.
If true, enables the plan immediately even though the invoice is not paid yet.
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
How to handle billing. 'prorate\_immediately' charges/credits prorated amounts now, 'none' does not charge/credit anything.
Pass 'now' to reset the billing cycle of every plan on the subscription to the time of this request.
URL to redirect to after successful checkout.
Additional parameters to pass into the creation of the Stripe checkout session.
Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if\_required' only when payment action is needed, 'never' disables redirects.
Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
If true, the cusProducts are activated immediately even when payment is pending via Stripe checkout.
Customer details to set when creating a customer
Customer's name
Customer's email address
Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
Additional metadata for the customer
Stripe customer ID if you already have one
Whether to create the customer in Stripe
The ID of the free plan to auto-enable for the customer
Whether to send email receipts to this customer
Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.
Billing controls for the customer (auto top-ups, etc.)
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.
Miscellaneous configurations for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
The feature ID that this entity is associated with
Name of the entity
Billing controls for the entity.
List of spend limits per feature. Each entry caps overage (overage\_limit) and/or per-interval usage (usage\_limit).
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 for this entity. An entity entry overrides the customer's for that feature.
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.
### Response
The ID of the customer.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
The total amount before discounts and tax for the current billing period.
The final amount after discounts and tax for the current billing period.
The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).
True when this change clears the customer's usage balances, so the approver can see usage will reset.
Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
Unix timestamp (milliseconds) when the next billing cycle starts.
The total amount before discounts and tax for the next cycle.
The final amount after discounts and tax for the next cycle.
List of line items for the next billing cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
List of line items for usage-based features in the next cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
Expand the response with additional data.
Products or subscription changes being added or updated.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
Products or subscription changes being removed or ended.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
Whether the customer will be redirected to a checkout page if attach is called.
The type of checkout that will be used if the customer is redirected to a checkout page.
Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location.
Total tax amount in major currency units.
Tax included in line item subtotals.
Tax added on top of subtotals.
Three-letter currency code.
Calculation status ('complete' when Stripe Tax succeeds or 'incomplete' when Stripe Tax returned 0 or errored).
Stripe customer invoice credits preview.
Stripe customer credit balance available, expressed as a positive number in major currency units.
Three-letter currency code.
```json 200 theme={null}
{
"customerId": "charles",
"lineItems": [
{
"display_name": "Pro seed",
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
"subtotal": 20,
"total": 20,
"discounts": []
}
],
"subtotal": 20,
"total": 20,
"currency": "usd"
}
```
# Preview Multi Update
Source: https://docs.useautumn.com/api-reference/billing/previewMultiUpdate
openapi POST /v1/billing.preview_multi_update
Previews the billing changes of a multi-plan update without making any changes. Returns one core preview per affected subscription.
Use this endpoint to show customers the credits and next-cycle changes of canceling multiple plans before confirming.
### Body Parameters
The ID of the customer to update plans for.
The ID of the entity to update plans for. Individual updates can override this with their own entity\_id.
Controls how the last payment is refunded on immediate cancellation. 'prorated' refunds the unused portion, 'full' refunds the entire last payment.
Additional parameters to pass into the Stripe subscription update or cancel call.
The list of plan updates to apply to the customer.
The ID of the plan to update. Optional if subscription\_id is provided.
A unique ID to identify the subscription to update. Useful when a customer has multiple products with the same plan.
The ID of the entity this update targets. Overrides the top-level entity\_id for this update.
Action to perform for cancellation. 'cancel\_immediately' cancels now with prorated refund, 'cancel\_end\_of\_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.
How to handle proration for this update. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
### Response
The ID of the customer the preview applies to.
The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).
The combined amount due today across all subscriptions (sum of subscriptions\[].total).
One preview per affected Stripe subscription. Updates to plans without a subscription (free plans) produce no entry.
The ID of the customer.
List of line items for the current billing period.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
The total amount before discounts and tax for the current billing period.
The final amount after discounts and tax for the current billing period.
The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).
True when this change clears the customer's usage balances, so the approver can see usage will reset.
Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
Unix timestamp (milliseconds) when the next billing cycle starts.
The total amount before discounts and tax for the next cycle.
The final amount after discounts and tax for the next cycle.
List of line items for the next billing cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
List of line items for usage-based features in the next cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
Expand the response with additional data.
Products or subscription changes being added or updated.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
Products or subscription changes being removed or ended.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
The IDs of the plans updated on this subscription.
```json 200 theme={null}
{
"customer_id": "cus_123",
"currency": "usd",
"total": -40,
"subscriptions": [
{
"customerId": "charles",
"lineItems": [
{
"display_name": "Pro seed",
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
"subtotal": 20,
"total": 20,
"discounts": []
}
],
"subtotal": -20,
"total": -20,
"currency": "usd",
"plan_ids": [
"pro_plan"
]
},
{
"customerId": "charles",
"lineItems": [
{
"display_name": "Pro seed",
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
"subtotal": 20,
"total": 20,
"discounts": []
}
],
"subtotal": -20,
"total": -20,
"currency": "usd",
"plan_ids": [
"addon_seats"
]
}
]
}
```
# Preview Update
Source: https://docs.useautumn.com/api-reference/billing/previewUpdate
openapi POST /v1/billing.preview_update
Previews the billing changes that would occur when updating a subscription, without actually making any changes.
Use this endpoint to show customers prorated charges or refunds before confirming subscription modifications.
### Body Parameters
The ID of the customer to attach the plan to.
The ID of the entity to attach the plan to.
The ID of the plan to update. Optional if subscription\_id is provided, or if the customer has only one product.
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
The version of the plan to attach.
Free trial configuration for a plan.
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.
Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.
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.
Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add\_items / remove\_items / deprecated update\_items.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Items to add to the plan.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send\_invoice collection method.
When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send\_invoice collection method.
If true, enables the plan immediately even though the invoice is not paid yet.
If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
ID of an invoice template (configured in billing settings) whose footer (e.g. bank details) is applied to the invoice.
Number of days the customer has to pay the invoice before it is due (Stripe days\_until\_due).
How to handle proration when updating an existing subscription. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if\_required' only when payment action is needed, 'never' disables redirects.
A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
Action to perform for cancellation. 'cancel\_immediately' cancels now with prorated refund, 'cancel\_end\_of\_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.
Reset the billing cycle immediately with 'now', or schedule a reset at a future Unix timestamp in milliseconds.
If true, the subscription is updated internally without applying billing changes in Stripe.
Controls how the last payment is refunded on immediate cancellation. 'prorated' refunds the unused portion, 'full' refunds the entire last payment.
Additional parameters to pass into the Stripe subscription update or cancel call.
Controls whether balances should be recalculated during the subscription update.
If true, recalculates balances during the subscription update. Only applicable when updating feature quantities.
Whether to carry over usages from the previous plan.
Whether to carry over usages from the previous plan.
The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.
Total seat quantities (inclusive of the license's included count) per license plan offered by this plan. Licenses not listed keep their current paid quantity.
The license plan to set seat quantity for.
Total seats for the license, inclusive of the plan's included amount — seats beyond it are paid.
Custom line items that replace the auto-generated proration invoice, or bill a standalone invoice when nothing else changes. Only valid on an existing recurring subscription.
Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
Description for the line item.
### Response
The ID of the customer.
List of line items for the current billing period.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
The total amount before discounts and tax for the current billing period.
The final amount after discounts and tax for the current billing period.
The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).
True when this change clears the customer's usage balances, so the approver can see usage will reset.
Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
Unix timestamp (milliseconds) when the next billing cycle starts.
The total amount before discounts and tax for the next cycle.
The final amount after discounts and tax for the next cycle.
List of line items for the next billing cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
List of line items for usage-based features in the next cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
Expand the response with additional data.
Products or subscription changes being added or updated.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
Products or subscription changes being removed or ended.
The ID of the plan affected by this preview change.
The full plan object if it was expanded in the 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 feature quantity selections associated with this plan change.
The ID of the adjustable feature included in this change.
The quantity that will apply for this feature in the change.
When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
Tax preview for the immediate charge. Contact us to enable the tax flag on your organisation. Shows only with flag enabled, a Stripe customer exists and has a location.
Total tax amount in major currency units.
Tax included in line item subtotals.
Tax added on top of subtotals.
Three-letter currency code.
Calculation status ('complete' when Stripe Tax succeeds or 'incomplete' when Stripe Tax returned 0 or errored).
Stripe customer invoice credits preview.
Stripe customer credit balance available, expressed as a positive number in major currency units.
Three-letter currency code.
```json 200 theme={null}
{
"customerId": "charles",
"lineItems": [
{
"display_name": "Pro seed",
"description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
"subtotal": 20,
"total": 20,
"discounts": []
}
],
"subtotal": 20,
"total": 20,
"currency": "usd"
}
```
# Setup Payment
Source: https://docs.useautumn.com/api-reference/billing/setupPayment
openapi POST /v1/billing.setup_payment
Create a payment setup session for a customer to add or update their payment method.
### Body Parameters
The ID of the customer to attach the plan to.
The ID of the entity to attach the plan to.
If specified, the plan will be attached to the customer after setup.
If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
The ID of the feature to set quantity for.
The quantity of the feature.
Whether the customer can adjust the quantity.
The version of the plan to attach.
Free trial configuration for a plan.
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.
Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.
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.
Override the items in the plan (PUT-style — replaces all existing items). Mutually exclusive with add\_items / remove\_items / deprecated update\_items.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Items to add to the plan.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
How to handle proration when updating an existing subscription. 'prorate\_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.
List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
URL to redirect to after successful checkout.
Reset the billing cycle immediately with 'now', or schedule a reset at a future Unix timestamp in milliseconds.
Unix timestamp in milliseconds for when the attached plan should start. Future dates create a scheduled subscription.
Unix timestamp in milliseconds for when the attached plan should end.
Additional parameters to pass into the creation of the Stripe checkout session.
Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans).
Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
Description for the line item.
The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.
Whether to carry over balances from the previous plan.
Whether to carry over balances from the previous plan.
The IDs of the features to carry over balances from. If left undefined, all features will be carried over.
Whether to carry over usages from the previous plan.
Whether to carry over usages from the previous plan.
The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.
Seat quantities for the plan's licenses, keyed by license plan.
The license plan to set seat quantity for.
Total seats for the license, inclusive of the plan's included amount — seats beyond it are paid.
Key-value metadata to attach to the Stripe subscription, invoice, and checkout session created during this attach flow. Keys prefixed with 'autumn\_' are reserved and will be stripped.
If true, skips any billing changes for the attach operation.
If true, the customer's plan is activated immediately even when payment is deferred (invoice mode) or pending (Stripe checkout). For Stripe checkout, the customer\_product is inserted before the customer completes the hosted form. Set it here rather than on `invoice_mode`, which only covers the invoice-unpaid case.
Stripe tax rate ID (txr\_...) to apply as the default tax rate on the created subscription, invoice, or checkout session line items.
Currency to bill this attach in (e.g. usd, eur). Must match the customer's currency if they are already locked to one, and the plan must offer a paid price in it. Defaults to the customer's currency, then the org default.
Plan IDs to expire on the customer as part of this attach. Each must be an active plan billed on the same subscription as the attach (or a free plan); plans on a separate subscription are rejected.
### Response
The ID of the customer
The ID of the entity the plan (if specified) will be attached to after setup.
URL to redirect the customer to setup their payment.
```json 200 theme={null}
{
"customer_id": "cus_123",
"url": "https://checkout.stripe.com/..."
}
```
# Batch Track Usage
Source: https://docs.useautumn.com/api-reference/core/batchTrack
openapi POST /v1/balances.batch_track
Enqueue up to 1000 usage events for asynchronous processing. Items are validated synchronously up front; validated items are then enqueued via SQS for background deduction by workers. The response returns 202 immediately and does not include balance information. On partial enqueue failure (some items fail to enqueue, others succeed), the endpoint still returns 202 and logs the failures server-side; clients should NOT retry, because retrying re-enqueues the already-succeeded items. A 503 is returned only when zero items were successfully enqueued (queue entirely unavailable) — that case is safe to retry.
Batch track enqueues up to **1000 usage events** in a single request. Items are validated synchronously, then enqueued for asynchronous processing. The response returns **202 immediately** without balance information — balances are deducted by background workers.
Use this when you're sending high volumes of tracking events and don't need an immediate balance read for each one.
### Common Use Cases
```typescript Batch many customers theme={null}
await autumn.balances.batchTrack([
{ customerId: "cus_alice", featureId: "ai_messages", value: 1 },
{ customerId: "cus_bob", featureId: "ai_messages", value: 1 },
{ customerId: "cus_carol", featureId: "ai_messages", value: 3 },
]);
```
```typescript Mixed features and entities theme={null}
await autumn.balances.batchTrack([
{ customerId: "cus_123", featureId: "ai_messages", value: 5 },
{ customerId: "cus_123", featureId: "api_calls", value: 12 },
{ customerId: "cus_123", featureId: "seats", entityId: "team_a", value: 1 },
]);
```
### Partial-Failure Semantics
Batch track is designed for fire-and-forget metering. On partial failure, **the endpoint still returns 202** and logs the failed items server-side. Clients should NOT retry the batch — retrying re-enqueues the already-succeeded items, which causes double-deduction. The trade-off is silent loss of the small subset that didn't enqueue vs. duplicate processing of the much larger subset that did. For event-logging workloads, gaps are preferable to duplicates.
A 503 is returned only when **zero items were successfully enqueued** (the queue is entirely unavailable). In that case the whole request is safe to retry.
If your workload requires per-item delivery guarantees, use the [single-event track endpoint](/api-reference/core/track) with client-side retry semantics instead.
### Limits
* **Maximum batch size:** 1000 items per request
* **Minimum batch size:** 1 item
* **Rate limit:** 10 requests/second per organization (separate bucket from the single `/v1/balances.track` limiter)
### Body Parameters
Array item
The ID of the customer.
The ID of the feature to track usage for. Required if event\_name is not provided.
The ID of the entity for entity-scoped balances (e.g., per-seat limits).
Event name to track usage for. Use instead of feature\_id when multiple features should be tracked from a single event.
The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat).
Additional properties to attach to this usage event.
Unix timestamp in milliseconds to use for the usage event. Defaults to the current time.
How to handle usage that exceeds the available balance. "cap" (default) deducts only what fits, stopping at zero. "overflow" deducts the full value: the balance can go negative and usage limits do not clamp the deduction, though spend limits still apply.
If true, enqueue the event for asynchronous processing and return 204 immediately. The response will not include balance information.
A unique identifier for this lock. Used to finalize the lock later via balances.finalize.
Must be true to enable locking.
Unix timestamp (ms) when the lock automatically expires and releases the held balance.
# Check Permissions
Source: https://docs.useautumn.com/api-reference/core/check
openapi POST /v1/balances.check
Checks whether a customer currently has enough balance to use a feature.
Use this to gate access before a feature action. Enable sendEvent when you want to check and consume balance atomically in one request.
Check determines if a customer has access to a feature based on their current balance. Returns `allowed: true` if they have sufficient balance, the feature is unlimited, or it's a boolean feature included in their plan.
### Common Use Cases
```typescript Check feature access theme={null}
const { allowed, balance } = await autumn.check({
customerId: "cus_123",
featureId: "ai_messages"
});
if (!allowed) {
// Show upgrade prompt or paywall
}
console.log(`You have ${balance.remaining} messages left`);
```
```typescript Check and track atomically theme={null}
const { allowed } = await autumn.check({
customerId: "cus_123",
featureId: "api_calls",
requiredBalance: 1,
sendEvent: true // Deducts usage if allowed
});
```
### Body Parameters
The ID of the customer.
The ID of the feature.
The ID of the entity for entity-scoped balances (e.g., per-seat limits).
Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1.
Additional properties to attach to the usage event if send\_event is true.
If true, atomically records a usage event while checking access. The required\_balance value is used as the usage amount. Combines check + track in one call.
Reserve units of a feature upfront by passing a lock\_id, then call balances.finalize to confirm or release the hold.
A unique identifier for this lock. Used to finalize the lock later via balances.finalize.
Must be true to enable locking.
Unix timestamp (ms) when the lock automatically expires and releases the held balance.
How to handle a lock that exceeds the available balance. "reject" (default) returns allowed: false and reserves nothing. "cap" reserves only what fits and returns allowed: true. "overflow" reserves the full value: the balance can go negative, though spend limits still apply. balances.finalize reuses the behavior chosen here.
If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls.
### Response
Whether the customer is allowed to use the feature. True if they have sufficient balance or the feature is unlimited/boolean.
The ID of the customer that was checked.
The ID of the entity, if an entity-scoped check was performed.
The required balance that was checked against.
The customer's balance for this feature. Null if the customer has no balance for this feature.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Map of feature\_id to balance for the checked feature and any related features (e.g. linked credit systems).
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
The flag associated with this check, if any.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Upgrade/upsell information when access is denied. Only present if with\_preview was true and allowed is false.
The reason access was denied. 'usage\_limit' means the customer exceeded their balance, 'feature\_flag' means the feature is not included in their plan.
A title suitable for displaying in a paywall or upgrade modal.
A message explaining why access was denied.
The ID of the feature that was checked.
The display name of the feature.
Products that would grant access to this feature. Use to display upgrade options.
The ID of the product you set when creating the product
The name of the product
Product group which this product belongs to
The environment of the product
Whether the product is an add-on and can be purchased alongside other products
Whether the product is the default product
Whether this product has been archived and is no longer available
The current version of the product
The timestamp of when the product was created in milliseconds since epoch
Array of product items that define the product's features and pricing
The type of the product item
The feature ID of the product item. If the item is a fixed price, should be `null`
Single use features are used once and then depleted, like API calls or credits. Continuous use features are those being used on an ongoing-basis, like storage or seats.
The amount of usage included for this feature.
The reset or billing interval of the product item. If null, feature will have no reset date, and if there's a price, it will be billed one-off.
The interval count of the product item.
The price of the product item. Should be `null` if tiered pricing is set.
Tiered pricing for the product item. Not applicable for fixed price items.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier). Defaults to graduated.
Whether the feature should be prepaid upfront or billed for how much they use end of billing period.
The amount per billing unit (eg. \$9 / 250 units)
Whether the usage should be reset when the product is enabled.
The entity feature ID of the product item if applicable.
The display of the product item.
Used in customer context. Quantity of the feature the customer has prepaid for.
Used in customer context. Quantity of the feature the customer will prepay for in the next cycle.
Configuration for rollover and proration behavior of the feature.
Free trial configuration for this product, if available
The duration type of the free trial
The length of the duration type specified
Whether the free trial is limited to one per customer fingerprint
Whether the free trial requires a card. If false, the customer can attach the product without going through a checkout flow or having a card on file.
Behavior when the trial ends. 'bill' charges the customer (default). 'revert' expires the trial and restores the customer's previous plan.
Used in customer context. Whether the free trial is available for the customer if they were to attach the product.
ID of the base variant this product is derived from
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.
Scenario for when this product is used in attach flows
True if the product has no base price or usage prices
True if the product only contains a one-time price
The billing interval group for recurring products (e.g., 'monthly', 'yearly')
True if the product includes a free trial
True if the product can be updated after creation (only applicable if there are prepaid recurring prices)
```json 200 theme={null}
{
"allowed": true,
"customer_id": "cus_123",
"entity_id": null,
"required_balance": 1,
"balance": {
"feature_id": "messages",
"granted": 100,
"remaining": 72,
"usage": 28,
"unlimited": false,
"overage_allowed": false,
"max_purchase": null,
"next_reset_at": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"plan_id": "pro_plan",
"included_grant": 100,
"prepaid_grant": 0,
"remaining": 72,
"usage": 28,
"unlimited": false,
"reset": {
"interval": "month",
"resets_at": 1773851121437
},
"price": null,
"expires_at": null
}
]
}
}
```
# Track Usage
Source: https://docs.useautumn.com/api-reference/core/track
openapi POST /v1/balances.track
Records usage for a customer feature and returns updated balances.
Use this after an action happens to decrement usage, or send a negative value to credit balance back.
Track records usage events to decrement a customer's balance. Use this to meter feature consumption like API calls, messages sent, or credits used.
### Common Use Cases
```typescript Track single usage theme={null}
await autumn.track({
customerId: "cus_123",
featureId: "ai_messages",
value: 1
});
```
```typescript Track with idempotency theme={null}
await autumn.track(
{
customerId: "cus_123",
featureId: "api_calls",
value: 1
},
{ headers: { "Idempotency-Key": "request_abc123" } } // Retries with the same key are rejected with a 409
);
```
```typescript Credit balance (negative value) theme={null}
await autumn.track({
customerId: "cus_123",
featureId: "seats",
value: -1 // Increases balance when removing a seat
});
```
```typescript Async (fire-and-forget) theme={null}
await autumn.track({
customerId: "cus_123",
featureId: "ai_messages",
value: 1,
async: true // Returns 202 immediately; usage processed in the background
});
```
### Body Parameters
The ID of the customer.
The ID of the feature to track usage for. Required if event\_name is not provided.
The ID of the entity for entity-scoped balances (e.g., per-seat limits).
Event name to track usage for. Use instead of feature\_id when multiple features should be tracked from a single event.
The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat).
Additional properties to attach to this usage event.
Unix timestamp in milliseconds to use for the usage event. Defaults to the current time.
How to handle usage that exceeds the available balance. "cap" (default) deducts only what fits, stopping at zero. "overflow" deducts the full value: the balance can go negative and usage limits do not clamp the deduction, though spend limits still apply.
If true, enqueue the event for asynchronous processing and return 204 immediately. The response will not include balance information.
A unique identifier for this lock. Used to finalize the lock later via balances.finalize.
Must be true to enable locking.
Unix timestamp (ms) when the lock automatically expires and releases the held balance.
### Response
The ID of the customer whose usage was tracked.
The ID of the entity, if entity-scoped tracking was performed.
The event name that was tracked, if event\_name was used instead of feature\_id.
The amount of usage that was recorded.
The updated balance for the tracked feature. Null if tracking by event\_name that affects multiple features.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Map of feature\_id to updated balance for the tracked feature and any related features (e.g. linked credit systems). Value is null when the customer has no balance for that feature.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Per-balance breakdown of what this event deducted. A single event can consume from multiple balance rows when credit systems or rollovers are involved; this surfaces each one so callers can build per-feature usage views without polling.
ID of the underlying balance row that was deducted from (customer\_entitlement or rollover).
The feature this balance belongs to.
ID of the plan/product this balance belongs to. Null when the balance can't be attributed to a single plan (e.g. it spans multiple).
Reset configuration for the balance this deduction came from, or null if the balance doesn't reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Amount deducted from this balance. Positive when usage was consumed, negative when credit was restored (e.g. a refund via negative track value).
```json 200 theme={null}
{
"customer_id": "cus_123",
"value": 1,
"balance": {
"feature_id": "messages",
"granted": 100,
"remaining": 72,
"usage": 28,
"unlimited": false,
"overage_allowed": false,
"max_purchase": null,
"next_reset_at": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"plan_id": "pro_plan",
"included_grant": 100,
"prepaid_grant": 0,
"remaining": 72,
"usage": 28,
"unlimited": false,
"reset": {
"interval": "month",
"resets_at": 1773851121437
},
"price": null,
"expires_at": null
}
]
},
"deductions": [
{
"balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2",
"feature_id": "messages",
"plan_id": "pro",
"reset": {
"interval": "month",
"resets_at": 1781288736881
},
"value": 1
}
]
}
```
# Delete Customer
Source: https://docs.useautumn.com/api-reference/customers/deleteCustomer
openapi POST /v1/customers.delete
Deletes a customer by ID.
### Body Parameters
ID of the customer to delete
Whether to also delete the customer in Stripe
### Response
# Get Customer
Source: https://docs.useautumn.com/api-reference/customers/getCustomer
openapi POST /v1/customers.get
Fetches a customer by ID, optionally expanding related data such as invoices or entities.
Use this when you know the customer exists or assert they exist without creating them.
### Body Parameters
ID of the customer to fetch
Expand related customer data like invoices or entities, or expand nested objects like balances.feature, flags.feature, subscriptions.plan, and purchases.plan.
### Response
Your unique identifier for the customer.
The name of the customer.
The email address of the customer.
Timestamp of customer creation in milliseconds since epoch.
A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
Stripe customer ID.
The environment this customer was created in.
The metadata for the customer.
Whether to send email receipts to the customer.
Billing controls for the customer (auto top-ups, etc.)
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. Expand billing\_controls.auto\_topups.purchase\_limit for a count of top ups and the next\_reset\_at.
The time interval for the purchase limit window. Null when no purchase limit is configured.
Number of intervals in the purchase limit window. Null when no purchase limit is configured.
Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured.
Number of auto top-ups already consumed in the current window.
Unix ms timestamp when the current purchase window ends and the count resets.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature, with current interval usage.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Active and scheduled recurring plans that this customer has attached.
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
One-time purchases made by the customer.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
License seat pools granted by the customer's plans, with seat counts.
The plan offered as an assignable license.
The plan that offers this license.
Display name of the license plan.
Total seats the customer has for this license, included plus paid.
Seats currently assigned to entities.
Seats still available to assign.
Paid seats purchased on top of the plan's included amount.
Feature balances keyed by feature ID, showing usage limits and remaining amounts.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Boolean feature flags keyed by feature ID, showing enabled access for on/off features.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Configuration for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.
Stripe processor connection for the customer.
Stripe customer ID.
Vercel processor connection for the customer (public-safe subset).
Vercel marketplace installation ID for this customer.
Vercel account ID associated with the installation.
RevenueCat processor connection for the customer.
Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set.
Invoices for this customer.
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
Upcoming invoice for each of this customer's Stripe subscriptions.
Plan IDs contributing line items to this invoice.
Unix timestamp (milliseconds) when this invoice will be created.
The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).
The total before discounts.
The total after discounts.
The line items this invoice will contain: usage accrued in the closing cycle, plus recurring charges for the opening cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
Entities associated with this customer.
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
Trial usage history for this customer.
Rewards earned or applied for this customer.
Array of active discounts applied to the customer
The unique identifier for this discount
The name of the discount or coupon
The type of reward
The discount value (percentage or fixed amount)
How long the discount lasts
Number of billing periods the discount applies for repeating durations
The currency code for fixed amount discounts
Timestamp when the discount becomes active
Timestamp when the discount expires
The Stripe subscription ID this discount is applied to
Total amount saved from this discount
Referral records for this customer.
The customer's default payment method.
```json 200 theme={null}
{
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
"name": "Patrick",
"email": "patrick@useautumn.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_U0BKxpq1mFhuJO",
"processors": {
"stripe": {
"id": "cus_U0BKxpq1mFhuJO"
}
},
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"billingControls": {
"autoTopups": []
},
"subscriptions": [
{
"planId": "pro_plan",
"autoEnable": true,
"addOn": false,
"status": "active",
"pastDue": false,
"canceledAt": null,
"expiresAt": null,
"trialEndsAt": null,
"startedAt": 1771431921437,
"currentPeriodStart": 1771431921437,
"currentPeriodEnd": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"licenses": [],
"balances": {
"messages": {
"featureId": "messages",
"granted": 100,
"remaining": 0,
"usage": 100,
"unlimited": false,
"overageAllowed": false,
"maxPurchase": null,
"nextResetAt": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"planId": "pro_plan",
"includedGrant": 100,
"prepaidGrant": 0,
"remaining": 0,
"usage": 100,
"unlimited": false,
"reset": {
"interval": "month",
"resetsAt": 1773851121437
},
"price": null,
"expiresAt": null
}
]
}
},
"flags": {
"advanced_workflows": {
"id": "cus_ent_abc123",
"plan_id": "pro_plan",
"expires_at": null,
"feature_id": "advanced_workflows"
}
},
"config": {
"disable_pooled_balance": false,
"disable_overage_billing": false
}
}
```
# Get or Create Customer
Source: https://docs.useautumn.com/api-reference/customers/getOrCreateCustomer
openapi POST /v1/customers.get_or_create
Creates a customer if they do not exist, or returns the existing customer by your external customer ID.
Use this as the primary entrypoint before billing operations so the customer record is always present and up to date.
If the customer already exists and you try to create it again, you will simply be returned the customer object (rather than an error being thrown).
### Currency
Pass `currency` to bill this customer in a currency other than your organization's default. Their plans must offer a price in that currency via [`additional_currencies`](/documentation/concepts/plans#multiple-currencies). If omitted, the customer's currency is set by their first paid attach.
### Body Parameters
Your unique identifier for the customer
Customer's name
Customer's email address
Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
Additional metadata for the customer
Stripe customer ID if you already have one
Whether to create the customer in Stripe
The ID of the free plan to auto-enable for the customer
Whether to send email receipts to this customer
Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.
Billing controls for the customer (auto top-ups, etc.)
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.
Miscellaneous configurations for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
Fields to expand in the returned customer response, such as subscriptions.plan, purchases.plan, balances.feature, or flags.feature.
### Response
Your unique identifier for the customer.
The name of the customer.
The email address of the customer.
Timestamp of customer creation in milliseconds since epoch.
A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
Stripe customer ID.
The environment this customer was created in.
The metadata for the customer.
Whether to send email receipts to the customer.
Billing controls for the customer (auto top-ups, etc.)
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. Expand billing\_controls.auto\_topups.purchase\_limit for a count of top ups and the next\_reset\_at.
The time interval for the purchase limit window. Null when no purchase limit is configured.
Number of intervals in the purchase limit window. Null when no purchase limit is configured.
Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured.
Number of auto top-ups already consumed in the current window.
Unix ms timestamp when the current purchase window ends and the count resets.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature, with current interval usage.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Active and scheduled recurring plans that this customer has attached.
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
One-time purchases made by the customer.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
License seat pools granted by the customer's plans, with seat counts.
The plan offered as an assignable license.
The plan that offers this license.
Display name of the license plan.
Total seats the customer has for this license, included plus paid.
Seats currently assigned to entities.
Seats still available to assign.
Paid seats purchased on top of the plan's included amount.
Feature balances keyed by feature ID, showing usage limits and remaining amounts.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Boolean feature flags keyed by feature ID, showing enabled access for on/off features.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Configuration for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.
Stripe processor connection for the customer.
Stripe customer ID.
Vercel processor connection for the customer (public-safe subset).
Vercel marketplace installation ID for this customer.
Vercel account ID associated with the installation.
RevenueCat processor connection for the customer.
Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set.
Invoices for this customer.
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
Upcoming invoice for each of this customer's Stripe subscriptions.
Plan IDs contributing line items to this invoice.
Unix timestamp (milliseconds) when this invoice will be created.
The three-letter ISO currency code. All amounts are in the currency's major unit (e.g., dollars for USD).
The total before discounts.
The total after discounts.
The line items this invoice will contain: usage accrued in the closing cycle, plus recurring charges for the opening cycle.
The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
A detailed description of the line item.
The amount before discounts and tax for this line item.
The final amount after discounts and tax for this line item.
List of discounts applied to this line item.
The ID of the plan that this line item belongs to.
The ID of the feature that this line item belongs to.
The period of time that this line item is being charged for.
The start of the period in milliseconds since the Unix epoch.
The end of the period in milliseconds since the Unix epoch.
The quantity of the line item.
Entities associated with this customer.
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
Trial usage history for this customer.
Rewards earned or applied for this customer.
Array of active discounts applied to the customer
The unique identifier for this discount
The name of the discount or coupon
The type of reward
The discount value (percentage or fixed amount)
How long the discount lasts
Number of billing periods the discount applies for repeating durations
The currency code for fixed amount discounts
Timestamp when the discount becomes active
Timestamp when the discount expires
The Stripe subscription ID this discount is applied to
Total amount saved from this discount
Referral records for this customer.
The customer's default payment method.
```json 200 theme={null}
{
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
"name": "Patrick",
"email": "patrick@useautumn.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_U0BKxpq1mFhuJO",
"processors": {
"stripe": {
"id": "cus_U0BKxpq1mFhuJO"
}
},
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"billingControls": {
"autoTopups": []
},
"subscriptions": [
{
"planId": "pro_plan",
"autoEnable": true,
"addOn": false,
"status": "active",
"pastDue": false,
"canceledAt": null,
"expiresAt": null,
"trialEndsAt": null,
"startedAt": 1771431921437,
"currentPeriodStart": 1771431921437,
"currentPeriodEnd": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"licenses": [],
"balances": {
"messages": {
"featureId": "messages",
"granted": 100,
"remaining": 0,
"usage": 100,
"unlimited": false,
"overageAllowed": false,
"maxPurchase": null,
"nextResetAt": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"planId": "pro_plan",
"includedGrant": 100,
"prepaidGrant": 0,
"remaining": 0,
"usage": 100,
"unlimited": false,
"reset": {
"interval": "month",
"resetsAt": 1773851121437
},
"price": null,
"expiresAt": null
}
]
}
},
"flags": {
"advanced_workflows": {
"id": "cus_ent_abc123",
"plan_id": "pro_plan",
"expires_at": null,
"feature_id": "advanced_workflows"
}
},
"config": {
"disable_pooled_balance": false,
"disable_overage_billing": false
}
}
```
# List Customers
Source: https://docs.useautumn.com/api-reference/customers/listCustomers
openapi POST /v1/customers.list
Lists customers with cursor pagination and optional filters. Pass `start_cursor: ""` (or omit) for the first page; use `next_cursor` from a prior response for subsequent pages.
### Body Parameters
Opaque pagination cursor. Empty string (default) requests the first page; use next\_cursor from a prior response for subsequent pages.
Number of items to return. Default 50, hard ceiling 5000.
Filter by plan ID and version. Returns customers with active subscriptions to this plan.
Filter by customer product status. Defaults to active and scheduled.
Search customers by id, name, or email.
Filter by customer processor type (stripe, revenuecat, vercel).
Sort by customer creation time. Defaults to desc (newest first).
Filter by customer creation time (epoch milliseconds, inclusive bounds).
Include customers created at or after this timestamp (epoch milliseconds, inclusive)
Include customers created at or before this timestamp (epoch milliseconds, inclusive)
### Response
Items for current page.
Your unique identifier for the customer.
The name of the customer.
The email address of the customer.
Timestamp of customer creation in milliseconds since epoch.
A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
Stripe customer ID.
The environment this customer was created in.
The metadata for the customer.
Whether to send email receipts to the customer.
Billing controls for the customer (auto top-ups, etc.)
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. Expand billing\_controls.auto\_topups.purchase\_limit for a count of top ups and the next\_reset\_at.
The time interval for the purchase limit window. Null when no purchase limit is configured.
Number of intervals in the purchase limit window. Null when no purchase limit is configured.
Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured.
Number of auto top-ups already consumed in the current window.
Unix ms timestamp when the current purchase window ends and the count resets.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature, with current interval usage.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Active and scheduled recurring plans that this customer has attached.
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
One-time purchases made by the customer.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
License seat pools granted by the customer's plans, with seat counts.
The plan offered as an assignable license.
The plan that offers this license.
Display name of the license plan.
Total seats the customer has for this license, included plus paid.
Seats currently assigned to entities.
Seats still available to assign.
Paid seats purchased on top of the plan's included amount.
Feature balances keyed by feature ID, showing usage limits and remaining amounts.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Boolean feature flags keyed by feature ID, showing enabled access for on/off features.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Configuration for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.
Stripe processor connection for the customer.
Stripe customer ID.
Vercel processor connection for the customer (public-safe subset).
Vercel marketplace installation ID for this customer.
Vercel account ID associated with the installation.
RevenueCat processor connection for the customer.
Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set.
Opaque cursor for the next page. Null when there are no more results.
```json 200 theme={null}
{
"list": [
{
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
"name": "Patrick",
"email": "patrick@useautumn.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_U0BKxpq1mFhuJO",
"processors": {
"stripe": {
"id": "cus_U0BKxpq1mFhuJO"
}
},
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"billingControls": {
"autoTopups": []
},
"subscriptions": [
{
"planId": "pro_plan",
"autoEnable": true,
"addOn": false,
"status": "active",
"pastDue": false,
"canceledAt": null,
"expiresAt": null,
"trialEndsAt": null,
"startedAt": 1771431921437,
"currentPeriodStart": 1771431921437,
"currentPeriodEnd": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"licenses": [],
"balances": {
"messages": {
"featureId": "messages",
"granted": 100,
"remaining": 0,
"usage": 100,
"unlimited": false,
"overageAllowed": false,
"maxPurchase": null,
"nextResetAt": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"planId": "pro_plan",
"includedGrant": 100,
"prepaidGrant": 0,
"remaining": 0,
"usage": 100,
"unlimited": false,
"reset": {
"interval": "month",
"resetsAt": 1773851121437
},
"price": null,
"expiresAt": null
}
]
}
},
"flags": {
"advanced_workflows": {
"id": "cus_ent_abc123",
"plan_id": "pro_plan",
"expires_at": null,
"feature_id": "advanced_workflows"
}
},
"config": {
"disable_pooled_balance": false,
"disable_overage_billing": false
}
}
],
"next_cursor": null
}
```
# Update Customer
Source: https://docs.useautumn.com/api-reference/customers/updateCustomer
openapi POST /v1/customers.update
Updates an existing customer by ID.
### Body Parameters
ID of the customer to update
Customer's name
Customer's email address
Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
Additional metadata for the customer
Stripe customer ID if you already have one
Whether to send email receipts to this customer
Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.
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. An entry with only feature\_id and usage sets the current counter without changing configuration.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Miscellaneous configurations for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
New ID for the customer
### Response
Your unique identifier for the customer.
The name of the customer.
The email address of the customer.
Timestamp of customer creation in milliseconds since epoch.
A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
Stripe customer ID.
The environment this customer was created in.
The metadata for the customer.
Whether to send email receipts to the customer.
Billing controls for the customer (auto top-ups, etc.)
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. Expand billing\_controls.auto\_topups.purchase\_limit for a count of top ups and the next\_reset\_at.
The time interval for the purchase limit window. Null when no purchase limit is configured.
Number of intervals in the purchase limit window. Null when no purchase limit is configured.
Maximum number of auto top-ups allowed within the interval. Null when no purchase limit is configured.
Number of auto top-ups already consumed in the current window.
Unix ms timestamp when the current purchase window ends and the count resets.
When true, auto top-up creates a send\_invoice invoice instead of auto-charging.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature, with current interval usage.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Active and scheduled recurring plans that this customer has attached.
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
One-time purchases made by the customer.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
License seat pools granted by the customer's plans, with seat counts.
The plan offered as an assignable license.
The plan that offers this license.
Display name of the license plan.
Total seats the customer has for this license, included plus paid.
Seats currently assigned to entities.
Seats still available to assign.
Paid seats purchased on top of the plan's included amount.
Feature balances keyed by feature ID, showing usage limits and remaining amounts.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
Boolean feature flags keyed by feature ID, showing enabled access for on/off features.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Configuration for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
Payment processors this customer is connected to (Stripe, Vercel, RevenueCat). Omitted entirely when the customer has not been created in any processor.
Stripe processor connection for the customer.
Stripe customer ID.
Vercel processor connection for the customer (public-safe subset).
Vercel marketplace installation ID for this customer.
Vercel account ID associated with the installation.
RevenueCat processor connection for the customer.
Customer's external ID, used as the RevenueCat app user ID. Null if the customer has no external ID set.
```json 200 theme={null}
{
"id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
"name": "Patrick",
"email": "patrick@useautumn.com",
"createdAt": 1771409161016,
"fingerprint": null,
"stripeId": "cus_U0BKxpq1mFhuJO",
"processors": {
"stripe": {
"id": "cus_U0BKxpq1mFhuJO"
}
},
"env": "sandbox",
"metadata": {},
"sendEmailReceipts": false,
"billingControls": {
"autoTopups": []
},
"subscriptions": [
{
"planId": "pro_plan",
"autoEnable": true,
"addOn": false,
"status": "active",
"pastDue": false,
"canceledAt": null,
"expiresAt": null,
"trialEndsAt": null,
"startedAt": 1771431921437,
"currentPeriodStart": 1771431921437,
"currentPeriodEnd": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"licenses": [],
"balances": {
"messages": {
"featureId": "messages",
"granted": 100,
"remaining": 0,
"usage": 100,
"unlimited": false,
"overageAllowed": false,
"maxPurchase": null,
"nextResetAt": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"planId": "pro_plan",
"includedGrant": 100,
"prepaidGrant": 0,
"remaining": 0,
"usage": 100,
"unlimited": false,
"reset": {
"interval": "month",
"resetsAt": 1773851121437
},
"price": null,
"expiresAt": null
}
]
}
},
"flags": {
"advanced_workflows": {
"id": "cus_ent_abc123",
"plan_id": "pro_plan",
"expires_at": null,
"feature_id": "advanced_workflows"
}
},
"config": {
"disable_pooled_balance": false,
"disable_overage_billing": false
}
}
```
# Create Entity
Source: https://docs.useautumn.com/api-reference/entities/createEntity
openapi POST /v1/entities.create
Creates an entity for a customer and feature, then returns the entity with balances and subscriptions.
Use entities when usage and access must be scoped to sub-resources (for example seats, projects, or workspaces) instead of only the customer.
### Body Parameters
The name of the entity
The ID of the feature this entity is associated with
Billing controls for the entity.
List of spend limits per feature. Each entry caps overage (overage\_limit) and/or per-interval usage (usage\_limit).
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 for this entity. An entity entry overrides the customer's for that feature.
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.
Customer attributes used to resolve the customer when customer\_id is not provided.
Customer's name
Customer's email address
Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
Additional metadata for the customer
Stripe customer ID if you already have one
Whether to create the customer in Stripe
The ID of the free plan to auto-enable for the customer
Whether to send email receipts to this customer
Currency to bill this customer in (e.g. usd, eur). Defaults to the organization's default currency.
Billing controls for the customer (auto top-ups, etc.)
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.
Miscellaneous configurations for the customer.
Whether to disable the shared customer-level pool for entities.
Stops Autumn from posting usage-overage line items to Stripe for this customer. Check/track and balance resets still behave normally. When set, this overrides the organization-level disable\_overage\_billing setting.
The ID of the customer to create the entity for.
The ID of the entity.
### Response
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Billing controls for the entity.
List of spend limits per feature. Each entry caps overage (overage\_limit) and/or per-interval usage (usage\_limit).
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature for this entity. An entity entry overrides the customer's for that feature.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Invoices for this entity (only included when expand=invoices)
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
```json 200 theme={null}
{
"id": "seat_42",
"name": "Seat 42",
"customer_id": "cus_123",
"feature_id": "seats",
"created_at": 1771409161016,
"env": "sandbox",
"subscriptions": [
{
"plan_id": "pro_plan",
"auto_enable": true,
"add_on": false,
"status": "active",
"past_due": false,
"canceled_at": null,
"expires_at": null,
"trial_ends_at": null,
"started_at": 1771431921437,
"current_period_start": 1771431921437,
"current_period_end": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"balances": {
"messages": {
"feature_id": "messages",
"granted": 100,
"remaining": 72,
"usage": 28,
"unlimited": false,
"overage_allowed": false,
"max_purchase": null,
"next_reset_at": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"plan_id": "pro_plan",
"included_grant": 100,
"prepaid_grant": 0,
"remaining": 72,
"usage": 28,
"unlimited": false,
"reset": {
"interval": "month",
"resets_at": 1773851121437
},
"price": null,
"expires_at": null
}
]
}
},
"invoices": []
}
```
# Delete Entity
Source: https://docs.useautumn.com/api-reference/entities/deleteEntity
openapi POST /v1/entities.delete
Deletes an entity by entity ID.
Use this when the underlying resource is removed and you no longer want entity-scoped balances or subscriptions tracked for it.
### Body Parameters
The ID of the customer.
The ID of the entity.
### Response
```json 200 theme={null}
{
"success": true
}
```
# Get Entity
Source: https://docs.useautumn.com/api-reference/entities/getEntity
openapi POST /v1/entities.get
Fetches an entity by its ID.
Use this to read one entity's current state. Pass customerId when you want to scope the lookup to a specific customer.
### Body Parameters
The ID of the customer to create the entity for.
The ID of the entity.
### Response
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Billing controls for the entity.
List of spend limits per feature. Each entry caps overage (overage\_limit) and/or per-interval usage (usage\_limit).
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature for this entity. An entity entry overrides the customer's for that feature.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Invoices for this entity (only included when expand=invoices)
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
```json 200 theme={null}
{
"id": "seat_42",
"name": "Seat 42",
"customer_id": "cus_123",
"feature_id": "seats",
"created_at": 1771409161016,
"env": "sandbox",
"subscriptions": [
{
"plan_id": "pro_plan",
"auto_enable": true,
"add_on": false,
"status": "active",
"past_due": false,
"canceled_at": null,
"expires_at": null,
"trial_ends_at": null,
"started_at": 1771431921437,
"current_period_start": 1771431921437,
"current_period_end": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"balances": {
"messages": {
"feature_id": "messages",
"granted": 100,
"remaining": 72,
"usage": 28,
"unlimited": false,
"overage_allowed": false,
"max_purchase": null,
"next_reset_at": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"plan_id": "pro_plan",
"included_grant": 100,
"prepaid_grant": 0,
"remaining": 72,
"usage": 28,
"unlimited": false,
"reset": {
"interval": "month",
"resets_at": 1773851121437
},
"price": null,
"expires_at": null
}
]
}
},
"invoices": []
}
```
# List Entities
Source: https://docs.useautumn.com/api-reference/entities/listEntities
openapi POST /v1/entities.list
Lists entities across the organization with pagination and optional filters.
Use this to page through entities globally, including filtering by plans inherited from parent customers or attached directly to entities.
### Body Parameters
Opaque pagination cursor. Empty string (default) requests the first page; use next\_cursor from a prior response for subsequent pages.
Number of items to return. Default 50, hard ceiling 5000.
Filter by plan ID and version. Returns entities with active subscriptions to this plan, including plans inherited from the parent customer.
Filter customer products used for entity hydration and plan matching. Defaults to active and scheduled.
Search entities by id or name.
Filter by parent customer processor type (stripe, revenuecat, vercel).
Restrict the response to entities owned by this customer id. Use to bulk-fetch all entities for one customer in a single paginated call instead of iterating entities.get.
### Response
Items for current page.
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Billing controls for the entity.
List of spend limits per feature. Each entry caps overage (overage\_limit) and/or per-interval usage (usage\_limit).
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature for this entity. An entity entry overrides the customer's for that feature.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Invoices for this entity (only included when expand=invoices)
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
Opaque cursor for the next page. Null when there are no more results.
```json 200 theme={null}
{
"list": [
{
"id": "seat_42",
"name": "Seat 42",
"customer_id": "cus_123",
"feature_id": "seats",
"created_at": 1771409161016,
"env": "sandbox",
"subscriptions": [
{
"plan_id": "pro_plan",
"auto_enable": true,
"add_on": false,
"status": "active",
"past_due": false,
"canceled_at": null,
"expires_at": null,
"trial_ends_at": null,
"started_at": 1771431921437,
"current_period_start": 1771431921437,
"current_period_end": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"balances": {
"messages": {
"feature_id": "messages",
"granted": 100,
"remaining": 72,
"usage": 28,
"unlimited": false,
"overage_allowed": false,
"max_purchase": null,
"next_reset_at": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"plan_id": "pro_plan",
"included_grant": 100,
"prepaid_grant": 0,
"remaining": 72,
"usage": 28,
"unlimited": false,
"reset": {
"interval": "month",
"resets_at": 1773851121437
},
"price": null,
"expires_at": null
}
]
}
},
"invoices": []
}
],
"next_cursor": null
}
```
# Update Entity
Source: https://docs.useautumn.com/api-reference/entities/updateEntity
openapi POST /v1/entities.update
Updates an existing entity and returns the refreshed entity object.
Use this to change entity billing controls or other mutable entity fields after the entity has already been created.
### Body Parameters
The ID of the customer that owns the entity.
The ID of the entity.
Billing controls to replace on the entity.
List of spend limits per feature. Each entry caps overage (overage\_limit) and/or per-interval usage (usage\_limit).
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. An entry with only feature\_id and usage sets the current counter without changing configuration.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
### Response
The unique identifier of the entity
The name of the entity
The customer ID this entity belongs to
The feature ID this entity belongs to
Unix timestamp when the entity was created
The environment (sandbox/live)
The unique identifier of this subscription. If a subscription\_id was provided at attach time, it is used; otherwise, falls back to the internal ID.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the subscribed plan.
Whether the plan was automatically enabled for the customer.
Whether this is an add-on plan rather than a base subscription.
Current status of the subscription.
Whether the subscription has overdue payments.
Timestamp when the subscription was canceled, or null if not canceled.
Timestamp when the subscription will expire, or null if no expiry set.
Timestamp when the trial period ends, or null if not on trial.
Timestamp when the subscription started.
Start timestamp of the current billing period.
End timestamp of the current billing period.
Number of units of this subscription (for per-seat plans).
Whether this subscription is attached at the customer level or entity level.
The full plan object if 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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 unique identifier of the purchased plan.
Timestamp when the purchase expires, or null for lifetime access.
Timestamp when the purchase was made.
Number of units purchased.
Whether this purchase is attached at the customer level or entity level.
The feature ID this balance is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Total balance granted (included + prepaid).
Remaining balance available for use.
Total usage consumed in the current period.
Whether this feature has unlimited usage.
Whether usage beyond the granted balance is allowed (with overage charges).
Maximum quantity that can be purchased as a top-up, or null for unlimited.
Timestamp when the balance will reset, or null for no reset.
Detailed breakdown of balance sources when stacking multiple plans or grants.
The unique identifier for this balance breakdown.
The plan ID this balance originates from, or null for standalone balances.
Amount granted from the plan's included usage.
Amount granted from prepaid purchases or top-ups.
Remaining balance available for use.
Amount consumed in the current period.
Whether this balance has unlimited usage.
Reset configuration for this balance, or null if no reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Pricing configuration if this balance has usage-based pricing.
The per-unit price amount.
Tiered pricing configuration if applicable.
How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
The number of units per billing increment (eg. \$9 / 250 units).
Whether usage is prepaid or billed pay-per-use.
Maximum quantity that can be purchased, or null for unlimited.
Timestamp when this balance expires, or null for no expiration.
Rollover balances carried over from previous periods.
Amount originally rolled over from a previous period, before any of it was consumed.
Amount of balance rolled over from a previous period.
Timestamp when the rollover balance expires.
The unique identifier for this flag.
The plan ID this flag originates from, or null for standalone flags.
Timestamp when this flag expires, or null for no expiration.
The feature ID this flag is for.
The full feature object if expanded.
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
Billing controls for the entity.
List of spend limits per feature. Each entry caps overage (overage\_limit) and/or per-interval usage (usage\_limit).
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
List of hard usage caps per feature for this entity. An entity entry overrides the customer's for that feature.
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.
Usage consumed in the active interval, stored in the usage-window counter.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
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.
Response-only: whether the entry is a customer-level override or inherited from an attached plan's defaults.
Invoices for this entity (only included when expand=invoices)
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
```json 200 theme={null}
{
"id": "seat_42",
"name": "Seat 42",
"customer_id": "cus_123",
"feature_id": "seats",
"created_at": 1771409161016,
"env": "sandbox",
"subscriptions": [
{
"plan_id": "pro_plan",
"auto_enable": true,
"add_on": false,
"status": "active",
"past_due": false,
"canceled_at": null,
"expires_at": null,
"trial_ends_at": null,
"started_at": 1771431921437,
"current_period_start": 1771431921437,
"current_period_end": 1771999921437,
"quantity": 1
}
],
"purchases": [],
"balances": {
"messages": {
"feature_id": "messages",
"granted": 100,
"remaining": 72,
"usage": 28,
"unlimited": false,
"overage_allowed": false,
"max_purchase": null,
"next_reset_at": 1773851121437,
"breakdown": [
{
"id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
"plan_id": "pro_plan",
"included_grant": 100,
"prepaid_grant": 0,
"remaining": 72,
"usage": 28,
"unlimited": false,
"reset": {
"interval": "month",
"resets_at": 1773851121437
},
"price": null,
"expires_at": null
}
]
}
},
"invoices": []
}
```
# Aggregate Events
Source: https://docs.useautumn.com/api-reference/events/aggregateEvents
openapi POST /v1/events.aggregate
Aggregate usage events by time period. Returns usage totals grouped by feature and optionally by a custom property.
Aggregate usage events by time period. Returns usage totals grouped by feature and optionally by a custom property.
## Working with Properties
When tracking events, you can attach custom properties that can later be used for grouping aggregations:
```typescript theme={null}
// Track an event with properties
await autumn.track({
customerId: "cus_123",
featureId: "api_calls",
value: 1,
properties: {
model: "gpt-4",
source: "api",
region: "us-east"
}
});
```
You can then aggregate events grouped by any property using the `group_by` parameter:
```typescript theme={null}
const result = await autumn.events.aggregate({
customerId: "cus_123",
featureId: "api_calls",
range: "7d",
groupBy: "properties.model" // Group by the "model" property
});
```
### Special Group By Operators
In addition to custom properties, you can group by built-in columns using `$`-prefixed operators:
* `$customer_id` -- Group results by customer ID. Useful when aggregating across all customers (i.e. no `customer_id` specified).
* `$entity_id` -- Group results by entity ID. Useful for seeing usage broken down per entity.
```typescript theme={null}
// Aggregate across all customers, grouped by customer
const result = await autumn.events.aggregate({
featureId: "api_calls",
range: "7d",
groupBy: "$customer_id"
});
// Aggregate for a customer, grouped by entity
const result = await autumn.events.aggregate({
customerId: "cus_123",
featureId: "api_calls",
range: "7d",
groupBy: "$entity_id"
});
```
## Response Format
The response structure changes based on whether `group_by` is provided:
### Without `group_by` (Flat Response)
When no grouping is specified, `values` contains the aggregated sum for each feature:
```json theme={null}
{
"list": [
{
"period": 1762905600000,
"values": {
"api_calls": 150,
"messages": 45
}
}
],
"total": {
"api_calls": { "count": 10, "sum": 150 },
"messages": { "count": 5, "sum": 45 }
}
}
```
### With `group_by` (Grouped Response)
When grouping is specified, `values` contains the total sum while `grouped_values` breaks down values by group:
```json theme={null}
{
"list": [
{
"period": 1762905600000,
"values": {
"api_calls": 150
},
"grouped_values": {
"api_calls": {
"gpt-4": 100,
"gpt-3.5": 50
}
}
}
],
"total": {
"api_calls": { "count": 10, "sum": 150 }
}
}
```
The `grouped_values` field is only present when `group_by` is provided in the request.
## Deduction Breakdowns
By default, aggregations answer *"how much usage was tracked?"*. Passing `aggregate_on: "deducted"` additionally answers *"which balances did that usage actually come out of?"* — the response gains a `deductions` array, keyed by the **balance-owning feature** rather than the tracked event. The `list` and `total` fields are unchanged.
A `customer_id` is required in this mode, since deductions are resolved against a specific customer's balances.
There are two situations where this matters:
### Case 1: Usage spilling into a credit system
A feature can have its own included allowance *and* feed a credit system — usage drains the allowance first, then overflows into credits at the feature's credit cost. The standard aggregation only shows tracked totals, so the overflow is invisible. With `aggregate_on: "deducted"`, the two sides show up separately:
```typescript theme={null}
const result = await autumn.events.aggregate({
customerId: "cus_123",
featureId: "observability_events",
range: "30d",
aggregateOn: "deducted"
});
```
```json theme={null}
{
"deductions": [
{
"period": 1762905600000,
"values": {
"observability_events": {
"feature_type": "metered",
"deducted": 1000000,
"events": 12,
"balances": [
{
"balance_id": "cus_ent_abc",
"entity_id": null,
"plan_id": "team",
"reset": { "interval": "month", "resets_at": 1789218895573 },
"credit_cost": null,
"deducted": 1000000,
"events": 12
}
]
},
"usage_credits": {
"feature_type": "credit_system",
"deducted": 0.8,
"events": 1,
"balances": [
{
"balance_id": "cus_ent_def",
"entity_id": null,
"plan_id": "team",
"reset": { "interval": "month", "resets_at": 1789218895573 },
"credit_cost": 0.00008,
"deducted": 0.8,
"events": 1
}
]
}
}
}
]
}
```
Reading this: the customer's 1M-event allowance absorbed the tracked usage, and 10,000 events overflowed into the `usage_credits` pool, burning 0.8 credits at the feature's credit cost of 0.00008. Each entry is in **that balance's own unit** — events for the metered feature, credits for the credit system.
`credit_cost` is only populated when the request pins a single non-credit feature via `feature_id`, since several features feeding one pool each convert at a different rate. It reflects the credit system's current schema.
### Case 2: Per-entity balances falling through to a shared pool
When entities (e.g. seats) each carry their own balance and overflow lands on a customer-level shared balance, group by `$entity_id` to see who spent from where:
```typescript theme={null}
const result = await autumn.events.aggregate({
customerId: "cus_123",
featureId: "ai_credits",
range: "30d",
aggregateOn: "deducted",
groupBy: "$entity_id"
});
```
```json theme={null}
{
"deductions": [
{
"period": 1762905600000,
"values": {
"ai_credits": {
"feature_type": "credit_system",
"deducted": 1650,
"events": 5,
"balances": [
{ "balance_id": "cus_ent_seat_3", "entity_id": "seat_3", "plan_id": "team_seat", "deducted": 600, "events": 2, ... },
{ "balance_id": "cus_ent_seat_4", "entity_id": "seat_4", "plan_id": "team_seat", "deducted": 600, "events": 1, ... },
{ "balance_id": "cus_ent_shared", "entity_id": null, "plan_id": "team_yearly", "deducted": 50, "events": 3, ... }
]
}
},
"grouped_values": {
"cus_ent_seat_3": { "seat_3": { "deducted": 600 } },
"cus_ent_seat_4": { "seat_4": { "deducted": 600 } },
"cus_ent_shared": {
"seat_3": { "deducted": 25 },
"seat_4": { "deducted": 25 }
}
}
}
]
}
```
**Finding each entity's spillover** takes one join between the two halves of the response:
1. In `balances`, find the entry whose `entity_id` is `null`. That's the customer-level shared balance — the pool that entities fall through to when their own balance runs out. (Entries with an `entity_id` are balances owned by that entity.)
2. Take that entry's `balance_id` and look it up in `grouped_values`. The keys of that object are the entities that spent from the shared pool, and each `deducted` is exactly how much they overdrew.
Here `cus_ent_shared` is the shared balance, and `grouped_values["cus_ent_shared"]` shows seats 3 and 4 each pulled 25 credits from it beyond their own 600-credit seat balances — the "used 25 extra credits" number to show next to each seat.
The seat-owned balances appear in `grouped_values` too, but for them the owner and the spender are the same entity, so the split just restates the balance total.
`group_by: "$plan_id"` is rejected with `aggregate_on` — every balance belongs to exactly one plan, so `balances[].plan_id` already carries the plan split.
### Body Parameters
Customer ID to aggregate events for
Entity ID to filter aggregated events for (e.g., per-seat or per-resource limits)
Feature ID(s) to aggregate events for
Property to group events by (e.g. "properties.region"), or "$customer_id" / "$entity\_id" / "$plan_id" to group by those columns. When aggregate_on is "deducted", "$feature\_id" groups deductions by the tracked feature that consumed each balance.
Time range to aggregate events for. Either range or custom\_range must be provided
Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day
Custom time range to aggregate events for. If provided, range must not be provided
Filter events by property values, e.g. \{"model": "gpt-4", "region": "us"}. Maximum 5 filters.
Maximum number of distinct group values to return per time bin when using group\_by. Remaining values are bundled into an 'Other' bucket. Defaults to 9
Set to "deducted" to additionally return a per-balance breakdown of what each event consumed, under `deductions`. Purely additive: `list` and `total` are unchanged. Requires customer\_id.
### Response
Array of time periods with aggregated values
Unix timestamp (epoch ms) for this time period
Aggregated values per feature: \{ \[featureId]: number }
Values broken down by group (only present when group\_by is used): \{ \[featureId]: \{ \[groupValue]: number } }
Total aggregations per feature. Keys are feature IDs, values contain count and sum.
Number of events for this feature
Sum of event values for this feature
Per-balance breakdown of what was consumed. Present only when aggregate\_on is "deducted".
Unix timestamp (epoch ms), same basis as `list`.
Keyed by the feature that OWNS the balance drawn from, not the feature that was tracked.
credit\_system means `deducted` is credits; metered means it is that feature's own amount.
ID of the balance row drawn from (customer\_entitlement or rollover).
Entity that owns this balance, or null when it is customer-level and shared.
Plan the balance came with. Null for balances created outside a plan.
Reset config for this balance, captured at deduction time.
Multiplier applied converting the tracked feature into this balance. Null when 1:1, or when the query spans sources converting at different rates.
Present only when group\_by is used. Keyed by balance\_id, then by group value — the only way to attribute a shared balance to the entity that spent from it.
```json 200 theme={null}
{
"list": [
{
"period": 1762905600000,
"values": {
"messages": 10,
"sessions": 3
}
},
{
"period": 1762992000000,
"values": {
"messages": 3,
"sessions": 12
}
}
],
"total": {
"messages": {
"count": 2,
"sum": 13
},
"sessions": {
"count": 2,
"sum": 15
}
}
}
```
# List Events
Source: https://docs.useautumn.com/api-reference/events/listEvents
openapi POST /v1/events.list
List usage events for your organization. Filter by customer, feature, or time range.
### Body Parameters
Opaque pagination cursor. Empty string (default) requests the first page; use next\_cursor from a prior response for subsequent pages.
Number of items to return. Default 50, hard ceiling 5000.
Filter events by customer ID
Filter events by entity ID (e.g., per-seat or per-resource)
Filter by specific feature ID(s)
Filter events by time range
Filter events after this timestamp (epoch milliseconds)
Filter events before this timestamp (epoch milliseconds)
### Response
Items for current page.
Event ID (KSUID)
Event timestamp (epoch milliseconds)
ID of the feature that the event belongs to
Customer identifier
Event value/count
Event properties (JSON)
Per-balance breakdown of what this event deducted. Null for events ingested before deductions were tracked; an empty array means the event was accepted but no balance moved.
ID of the underlying balance row that was deducted from (customer\_entitlement or rollover).
The feature this balance belongs to.
ID of the plan/product this balance belongs to. Null when the balance can't be attributed to a single plan (e.g. it spans multiple).
Reset configuration for the balance this deduction came from, or null if the balance doesn't reset.
The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
Number of intervals between resets (eg. 2 for bi-monthly).
Timestamp when the balance will next reset.
Amount deducted from this balance. Positive when usage was consumed, negative when credit was restored (e.g. a refund via negative track value).
Opaque cursor for the next page. Null when there are no more results.
```json 200 theme={null}
{
"list": [
{
"id": "evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg",
"timestamp": 1765958215459,
"feature_id": "credits",
"customer_id": "0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx",
"value": 30,
"properties": {},
"deductions": [
{
"balance_id": "cus_ent_3DdSDtFBlvDbjyUuJeUIbQlyN12",
"feature_id": "credits",
"plan_id": "pro",
"reset": {
"interval": "month",
"resets_at": 1765958215459
},
"value": 30
}
]
},
{
"id": "evt_36xmHxxjAkqxufDf9yHAPNfRrLM",
"timestamp": 1765956512057,
"feature_id": "credits",
"customer_id": "0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx",
"value": 49,
"properties": {},
"deductions": null
}
],
"next_cursor": "eyJ2IjowLCJpZCI6ImV2dF8zNnhtSHh4akFrcXh1ZkRmOXlIQVBOZlJyTE0iLCJ0IjoxNzY1OTU2NTEyMDU3fQ"
}
```
# Create Feature
Source: https://docs.useautumn.com/api-reference/features/createFeature
openapi POST /v1/features.create
Creates a new feature.
Use this to programmatically create features for metering usage, managing access, or building credit systems.
### Body Parameters
The name of the feature.
The type of the feature. 'single\_use' features are consumed, like API calls, tokens, or messages. 'continuous\_use' features are allocated, like seats, workspaces, or projects. 'credit\_system' features are schemas that unify multiple 'single\_use' features into a single credit system.
Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features.
Singular and plural display names for the feature in your user interface.
A schema that maps metered feature IDs to flat or graduated credit costs. For classic credit systems only — AI credit systems use model\_markups instead.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems. Maps model IDs to their markup configuration.
Default percentage markup for this AI credit system. Used when no model or provider markup applies. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems. Provider keys match the first segment of model\_id.
The ID of the feature to create.
### Response
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
```json 200 theme={null}
{
"id": "api-calls",
"name": "API Calls",
"type": "metered",
"consumable": true,
"archived": false,
"display": {
"singular": "API call",
"plural": "API calls"
}
}
```
# Delete Feature
Source: https://docs.useautumn.com/api-reference/features/deleteFeature
openapi POST /v1/features.delete
Deletes a feature by its ID.
Use this to permanently remove a feature. Note: features that are used in products cannot be deleted - archive them instead.
### Body Parameters
The ID of the feature to delete.
### Response
```json 200 theme={null}
{
"success": true
}
```
# Get Feature
Source: https://docs.useautumn.com/api-reference/features/getFeature
openapi POST /v1/features.get
Retrieves a single feature by its ID.
Use this when you need to fetch the details of a specific feature.
### Body Parameters
The ID of the feature.
### Response
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
```json 200 theme={null}
{
"id": "api-calls",
"name": "API Calls",
"type": "metered",
"consumable": true,
"archived": false,
"display": {
"singular": "API call",
"plural": "API calls"
}
}
```
# List Features
Source: https://docs.useautumn.com/api-reference/features/listFeatures
openapi POST /v1/features.list
Lists all features in the current environment.
Use this to retrieve all features configured for your organization to display in dashboards or for feature management.
### Response
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
```json 200 theme={null}
{
"list": [
{
"id": "api-calls",
"name": "API Calls",
"type": "metered",
"consumable": true,
"archived": false,
"display": {
"singular": "API call",
"plural": "API calls"
}
},
{
"id": "credits",
"name": "Credits",
"type": "credit_system",
"consumable": true,
"archived": false,
"credit_schema": [
{
"metered_feature_id": "api-calls",
"credit_cost": 1
},
{
"metered_feature_id": "image-generations",
"credit_cost": 10
}
],
"display": {
"singular": "credit",
"plural": "credits"
}
}
]
}
```
# Update Feature
Source: https://docs.useautumn.com/api-reference/features/updateFeature
openapi POST /v1/features.update
Updates an existing feature.
Use this to modify feature properties like name, display settings, or to archive a feature.
### Body Parameters
The name of the feature.
The type of the feature. 'single\_use' features are consumed, like API calls, tokens, or messages. 'continuous\_use' features are allocated, like seats, workspaces, or projects. 'credit\_system' features are schemas that unify multiple 'single\_use' features into a single credit system.
Whether this feature is consumable. A consumable feature is one that periodically resets and is consumed rather than allocated (like credits, API requests, etc.). Applicable only for 'metered' features.
Singular and plural display names for the feature in your user interface.
A schema that maps metered feature IDs to flat or graduated credit costs. For classic credit systems only — AI credit systems use model\_markups instead.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems. Maps model IDs to their markup configuration.
Default percentage markup for this AI credit system. Used when no model or provider markup applies. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems. Provider keys match the first segment of model\_id.
Whether the feature is archived. Archived features are hidden from the dashboard.
The ID of the feature to update.
The new ID of the feature. Feature ID can only be updated if it's not being used by any customers.
### Response
The unique identifier for this feature, used in /check and /track calls.
Human-readable name displayed in the dashboard and billing UI.
Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit\_system' for unified credit pools, 'ai\_credit\_system' for model-based token pricing.
For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
For classic credit systems: maps metered features to flat or graduated credit costs.
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.
Whether usage of this classic credit system should be itemized as invoice credits.
Per-model markup overrides for AI credit systems.
Default percentage markup for AI credit systems. Use -100 to make usage free.
Per-provider default markup percentages for AI credit systems.
Display names for the feature in billing UI and customer-facing components.
Singular form for UI display (e.g., 'API call', 'seat').
Plural form for UI display (e.g., 'API calls', 'seats').
Whether the feature is archived and hidden from the dashboard.
Processor mappings for this feature. Present when a Stripe product or meter is set.
Stripe product ID this feature's usage prices bill under.
Stripe meter ID used to create this feature's metered price.
```json 200 theme={null}
{
"id": "api-calls",
"name": "API Calls",
"type": "metered",
"consumable": true,
"archived": false,
"display": {
"singular": "API call",
"plural": "API calls"
}
}
```
# Insert Invoices
Source: https://docs.useautumn.com/api-reference/invoices/insertInvoices
openapi POST /v1/invoices.insert
Inserts or updates up to 500 historical invoices without reading or mutating the billing processor.
### Body Parameters
Invoices to insert or update, in response order.
The customer this invoice belongs to.
Plan IDs represented by this invoice.
The processor's stable invoice ID.
The billing processor that owns this invoice.
The invoice status.
The invoice total in major currency units.
The amount paid in major currency units.
The refunded amount in major currency units.
The currency code. Defaults to the organization's default currency.
The invoice creation timestamp in milliseconds.
The hosted invoice URL, when available.
### Response
Inserted or updated invoices in request order.
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
The Autumn invoice ID.
The customer this invoice belongs to.
The amount paid in major currency units.
The refunded amount in major currency units.
```json 200 theme={null}
{
"invoices": [
{
"id": "inv_2b3c4d5e6f7g8h",
"customer_id": "cus_123",
"plan_ids": [
"pro"
],
"stripe_id": "in_legacy_123",
"processor_type": "stripe",
"status": "paid",
"total": 29.99,
"amount_paid": 29.99,
"refunded_amount": 0,
"currency": "usd",
"created_at": 1451606400000,
"hosted_invoice_url": "https://billing.example.com/invoices/legacy-123"
}
]
}
```
# List Invoices
Source: https://docs.useautumn.com/api-reference/invoices/listInvoices
openapi POST /v1/invoices.list
Lists invoices with cursor pagination and optional filters (customer, entity, status, processor). Pass `start_cursor: ""` (or omit) for the first page; use `next_cursor` from a prior response for subsequent pages.
### Body Parameters
Opaque pagination cursor. Empty string (default) requests the first page; use next\_cursor from a prior response for subsequent pages.
Number of items to return. Default 50, hard ceiling 5000.
Filter invoices to a single customer by ID.
Filter invoices to a single entity by ID. Must be provided together with customer\_id, since entity IDs are only unique per customer.
Filter by invoice status (draft, open, paid, void, uncollectible).
Filter by billing processor (stripe, revenuecat). Invoices recorded before processor tracking count as stripe.
### Response
Items for current page.
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
The Autumn invoice ID
The ID of the customer this invoice belongs to. Null for customers created without an ID.
The ID of the entity this invoice belongs to, if entity-scoped
The amount paid on the invoice. Null on invoices recorded before amounts paid were tracked.
The total amount refunded on the invoice
Line items on the invoice, one per line as shown in Stripe. Capped at 100. Empty for invoices recorded before line item storage.
Description of the invoice line item
Timestamp when the billing period starts
Timestamp when the billing period ends
The plan this line item came from. Null for lines with no Autumn plan behind them.
The ID of the feature associated with this line item
The name of the feature associated with this line item
Quantity actually charged on this line. Null on fixed-price lines.
Amount charged on this line, pre-discount and pre-tax. Negative for credits.
How this line splits by entity. Empty for customer-level lines. Only populated for invoices finalized after entity attribution shipped.
The entity this share of the line item is attributed to
Quantity charged to this entity. Null on fixed-price lines.
Amount attributed to this entity, pre-discount and pre-tax
Opaque cursor for the next page. Null when there are no more results.
```json 200 theme={null}
{
"list": [
{
"id": "inv_2b3c4d5e6f7g8h",
"customer_id": "cus_123",
"entity_id": null,
"plan_ids": [
"pro_plan"
],
"stripe_id": "in_1A2B3C4D5E6F7G8H",
"processor_type": "stripe",
"status": "paid",
"total": 29.99,
"amount_paid": 29.99,
"refunded_amount": 0,
"currency": "usd",
"created_at": 1759247877000,
"hosted_invoice_url": "https://invoice.stripe.com/i/acct_123/test_456",
"items": [
{
"description": "Pro plan",
"plan_id": "pro_plan",
"feature_id": null,
"feature_name": null,
"quantity": null,
"amount": 20,
"period_start": 1759247877000,
"period_end": 1761839877000,
"entities": []
},
{
"description": "AI credits",
"plan_id": "pro_plan",
"feature_id": "ai_credits",
"feature_name": "AI Credits",
"quantity": 4995,
"amount": 9.99,
"period_start": 1759247877000,
"period_end": 1761839877000,
"entities": [
{
"entity_id": "acme-docs-prod",
"quantity": 4995,
"amount": 9.99
}
]
}
]
}
],
"next_cursor": null
}
```
# Pay Invoice
Source: https://docs.useautumn.com/api-reference/invoices/payInvoice
openapi POST /v1/invoices.pay
Marks an open Stripe invoice as paid out of band. No charge is attempted; use this when payment was collected elsewhere (e.g. a marketplace). Already-paid invoices are returned unchanged.
### Body Parameters
The Autumn invoice ID to mark as paid.
### Response
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
The Autumn invoice ID
The ID of the customer this invoice belongs to. Null for customers created without an ID.
The ID of the entity this invoice belongs to, if entity-scoped
The amount paid on the invoice. Null on invoices recorded before amounts paid were tracked.
The total amount refunded on the invoice
Line items on the invoice, one per line as shown in Stripe. Capped at 100. Empty for invoices recorded before line item storage.
Description of the invoice line item
Timestamp when the billing period starts
Timestamp when the billing period ends
The plan this line item came from. Null for lines with no Autumn plan behind them.
The ID of the feature associated with this line item
The name of the feature associated with this line item
Quantity actually charged on this line. Null on fixed-price lines.
Amount charged on this line, pre-discount and pre-tax. Negative for credits.
How this line splits by entity. Empty for customer-level lines. Only populated for invoices finalized after entity attribution shipped.
The entity this share of the line item is attributed to
Quantity charged to this entity. Null on fixed-price lines.
Amount attributed to this entity, pre-discount and pre-tax
```json 200 theme={null}
{
"invoice": {
"id": "inv_2b3c4d5e6f7g8h",
"customer_id": "cus_123",
"entity_id": null,
"plan_ids": [
"pro_plan"
],
"stripe_id": "in_1A2B3C4D5E6F7G8H",
"processor_type": "stripe",
"status": "paid",
"total": 29.99,
"amount_paid": 29.99,
"refunded_amount": 0,
"currency": "usd",
"created_at": 1759247877000,
"hosted_invoice_url": "https://invoice.stripe.com/i/acct_123/test_456",
"items": [
{
"description": "Pro plan",
"plan_id": "pro_plan",
"feature_id": null,
"feature_name": null,
"quantity": null,
"amount": 20,
"period_start": 1759247877000,
"period_end": 1761839877000,
"entities": []
},
{
"description": "AI credits",
"plan_id": "pro_plan",
"feature_id": "ai_credits",
"feature_name": "AI Credits",
"quantity": 4995,
"amount": 9.99,
"period_start": 1759247877000,
"period_end": 1761839877000,
"entities": [
{
"entity_id": "acme-docs-prod",
"quantity": 4995,
"amount": 9.99
}
]
}
]
}
}
```
# Mint
Source: https://docs.useautumn.com/api-reference/keys/mintKey
openapi POST /v1/keys.mint
Mints a per-customer token (a scoped `am_jwt_` credential) so a downstream / self-hosted app can call Autumn directly without your secret key. Returns a short-lived access token plus a rotating refresh token, both bound to the given customer. Authenticated with your secret key.
Mints a per-customer token — a scoped `am_jwt_` credential — so a self-hosted or downstream app can call Autumn directly without your secret key. Authenticated with your **secret key**. Returns a short-lived access token (1h) and a rotating refresh token (24h), both bound to a single customer.
### How it works
1. Your backend calls `keys.mint` with your secret key to issue a token pair for a customer.
2. Hand the **access token** to that customer's app. It can call `check`, `track`, `customers.get` and `entities.get` — always scoped to that customer, even if a different `customer_id` is sent.
3. Before the access token expires, the app calls [`keys.refresh`](/api-reference/keys/refreshKey) with its **refresh token** to rotate a fresh pair — no secret key required.
```typescript TypeScript theme={null}
const { accessToken, refreshToken } = await autumn.keys.mint({
customerId: "cus_123",
});
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/keys.mint" \
-H "Authorization: Bearer am_sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "customer_id": "cus_123" }'
```
### Body Parameters
The customer to mint a token for.
If true, mint a non-expiring access token (no refresh token). Revoke via keys.revoke.
### Response
Access token (1h, or non-expiring if indefinite), prefixed `am_jwt_`.
Rotating refresh token (24h). Omitted for indefinite tokens.
Access-token expiry, ms since epoch. null for indefinite tokens.
Refresh-token expiry, ms since epoch. Omitted for indefinite tokens.
```json 200 theme={null}
{
"access_token": "am_jwt_eyJhbGciOiJIUzI1NiJ9...",
"refresh_token": "am_jwt_eyJhbGciOiJIUzI1NiJ9...",
"expires_at": 1781113864000,
"refresh_expires_at": 1781196664000
}
```
# Refresh
Source: https://docs.useautumn.com/api-reference/keys/refreshKey
openapi POST /v1/keys.refresh
Exchanges a refresh token (sent as the Bearer credential) for a freshly rotated access + refresh pair. Self-service for the token holder — no secret key required. The previous refresh token is honored for one rotation as a grace window; replaying an older one revokes the customer's tokens.
Exchanges a refresh token for a freshly rotated access + refresh pair. Self-service for the token holder — **no secret key required**. Send the refresh token as the Bearer credential.
### How it works
The just-replaced refresh token is honored for one more rotation (a grace window so a dropped response or a second app instance doesn't lock the customer out). Replaying a refresh token that is more than one generation old is treated as theft and revokes the customer's tokens.
```typescript TypeScript theme={null}
// Client configured with the refresh token as its key
import { Autumn } from "autumn-js";
const autumn = new Autumn({
secretKey: JWT_REFRESH_TOKEN,
});
const { accessToken, refreshToken } = await autumn.keys.refresh({});
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/keys.refresh" \
-H "Authorization: Bearer am_jwt_"
```
### Response
Access token (1h, or non-expiring if indefinite), prefixed `am_jwt_`.
Rotating refresh token (24h). Omitted for indefinite tokens.
Access-token expiry, ms since epoch. null for indefinite tokens.
Refresh-token expiry, ms since epoch. Omitted for indefinite tokens.
```json 200 theme={null}
{
"access_token": "am_jwt_eyJhbGciOiJIUzI1NiJ9...",
"refresh_token": "am_jwt_eyJhbGciOiJIUzI1NiJ9...",
"expires_at": 1781113864000,
"refresh_expires_at": 1781196664000
}
```
# Revoke
Source: https://docs.useautumn.com/api-reference/keys/revokeKey
openapi POST /v1/keys.revoke
Revokes every outstanding token (access and refresh) for a customer. Authenticated with your secret key. New tokens can be issued afterwards with `keys.mint`.
Revokes every outstanding token — access and refresh — for a customer. Authenticated with your **secret key**. Issue new tokens afterwards with [`keys.mint`](/api-reference/keys/mintKey).
```typescript TypeScript theme={null}
await autumn.keys.revoke({ customerId: "cus_123" });
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/keys.revoke" \
-H "Authorization: Bearer am_sk_live_..." \
-H "Content-Type: application/json" \
-d '{ "customer_id": "cus_123" }'
```
### Body Parameters
The customer whose tokens (every outstanding access + refresh token) should be revoked.
### Response
```json 200 theme={null}
{
"revoked": true
}
```
# Attach License
Source: https://docs.useautumn.com/api-reference/licenses/attachLicense
openapi POST /v1/licenses.attach
Assigns licenses to one or more entities.
License assignment is idempotent for an entity that already has an active
assignment for the same license plan. Autumn skips those entities without
consuming another license; mixed batches assign only unassigned entities. A
duplicate-only request still returns `200` with `{ "success": true }`.
Duplicate IDs within one batch and insufficient capacity for new assignments
still return an error.
### Body Parameters
The ID of the entity to assign the license to.
The name of the entity, used when creating it.
The feature the entity is associated with. Required when the entity does not exist yet.
### Response
# List License Assignments
Source: https://docs.useautumn.com/api-reference/licenses/listLicenseAssignments
openapi POST /v1/licenses.list_assignments
Lists license assignments for a customer.
### Body Parameters
### Response
```json 200 theme={null}
{
"list": [
{
"id": "lic_asn_123",
"entity_id": "user_123",
"license_plan_id": "seat_plan",
"started_at": 1759247877000,
"ended_at": null
}
]
}
```
# List Licenses
Source: https://docs.useautumn.com/api-reference/licenses/listLicenses
openapi POST /v1/licenses.list
Lists a customer's license pools and available seats.
### Body Parameters
### Response
The plan offered as an assignable license.
The plan that offers this license.
Display name of the license plan.
Total seats the customer has for this license, included plus paid.
Seats currently assigned to entities.
Seats still available to assign.
Paid seats purchased on top of the plan's included amount.
```json 200 theme={null}
{
"list": [
{
"license_plan_id": "seat_plan",
"parent_plan_id": "pro_plan",
"license_plan_name": "Seat",
"granted": 10,
"usage": 3,
"remaining": 7,
"paid_quantity": 5
}
]
}
```
# Release License
Source: https://docs.useautumn.com/api-reference/licenses/releaseLicense
openapi POST /v1/licenses.release
Releases licenses assigned to one or more entities.
### Body Parameters
Scopes the release when an entity holds licenses of multiple plans.
### Response
# Create a plan
Source: https://docs.useautumn.com/api-reference/plans/createPlan
openapi POST /v1/plans.create
Creates a new plan with optional base price and feature configurations.
Use this to programmatically create pricing plans. See [How plans work](/documentation/pricing/plans) for concepts.
Creates a new plan with optional base price and feature configurations. See [How plans work](/documentation/concepts/plans) for concepts and [Adding features to plans](/documentation/concepts/plan-items) for item configuration.
### Plan Configuration
A plan consists of:
* **Base price** - optional recurring charge for the plan itself
* **Items** - feature configurations defining what customers get and how they're billed
### Configuring Items
Each item in the `items` array configures a single feature. There are two types:
**Consumable features** (API calls, messages, credits):
* Set `included` for free units that reset each period
* Set `reset.interval` to define when balance resets to `included`
* Optionally add `price` for usage beyond included amount
**Non-consumable features** (seats, storage):
* Set `included` for the base allocation
* Do NOT set `reset` - usage persists across billing cycles
* Use `billing_method: "prepaid"` for upfront payment per unit
### Multiple Currencies
To sell a plan in currencies beyond your organization's default, set `additional_currencies` on the base price, a feature price, or each tier of a tiered price. Amounts are explicit per currency - no exchange rates are applied - and tier boundaries stay the same across currencies. See [Plans](/documentation/concepts/plans#multiple-currencies) for how customers are matched to a currency.
### Common Use Cases
```typescript Free plan with auto-enable theme={null}
await autumn.plans.create({
planId: "free_plan",
name: "Free",
autoEnable: true, // Automatically attached on customer creation
items: [
{
featureId: "messages",
included: 100,
reset: { interval: "month" }
}
]
});
```
```typescript Paid plan with base price + usage-based feature theme={null}
await autumn.plans.create({
planId: "pro_plan",
name: "Pro Plan",
price: { amount: 10, interval: "month" },
items: [
{
featureId: "messages",
included: 1000,
reset: { interval: "month" },
price: {
amount: 0.01,
interval: "month",
billingUnits: 1,
billingMethod: "usage_based"
}
}
]
});
```
```typescript Plan with prepaid seats theme={null}
await autumn.plans.create({
planId: "team_plan",
name: "Team Plan",
price: { amount: 49, interval: "month" },
items: [
{
featureId: "seats",
included: 5,
// No reset - seats persist across billing cycles
price: {
amount: 10,
interval: "month",
billingUnits: 1,
billingMethod: "prepaid"
}
}
]
});
```
```typescript Add-on plan theme={null}
await autumn.plans.create({
planId: "analytics_addon",
name: "Advanced Analytics",
addOn: true, // Can be attached alongside other plans
price: { amount: 20, interval: "month" }
});
```
```typescript Plan with tiered pricing theme={null}
await autumn.plans.create({
planId: "api_plan",
name: "API Plan",
items: [
{
featureId: "api_calls",
included: 1000,
reset: { interval: "month" },
price: {
tiers: [
{ to: 10000, amount: 0.001 },
{ to: 100000, amount: 0.0005 },
{ to: "inf", amount: 0.0001 }
],
interval: "month",
billingUnits: 1,
billingMethod: "usage_based"
}
}
]
});
```
```typescript Plan with free trial theme={null}
await autumn.plans.create({
planId: "premium_plan",
name: "Premium",
price: { amount: 99, interval: "month" },
freeTrial: {
durationLength: 14,
durationType: "day",
cardRequired: true
}
});
```
### Body Parameters
The ID of the plan to create.
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
Display name of the plan.
Optional description of the plan.
If true, this plan can be attached alongside other plans. Otherwise, attaching replaces existing plans in the same group.
If true, plan is automatically attached when a customer is created. Use for free tiers.
Base recurring price for the plan. Omit for free or usage-only plans.
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.
Feature configurations for this plan. Each item defines included units, pricing, and reset behavior.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Plans offered as assignable licenses under this plan. The full set replaces existing links.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Free trial configuration. Customers can try this plan before being charged.
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.
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. 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.
Arbitrary key-value metadata defined by you for your own use (e.g. UI copy, feature highlights). Values can be any JSON-serializable value. Shared across all versions of the plan.
### 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
```json 200 theme={null}
{
"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": {}
}
```
# Delete a plan
Source: https://docs.useautumn.com/api-reference/plans/deletePlan
openapi POST /v1/plans.delete
Deletes a plan by its ID.
Use this to permanently remove a plan. Plans with active customers cannot be deleted - archive them instead.
Deletes a plan or a specific version of a plan.
Deleting a plan cannot be undone. Existing subscriptions to this plan will remain active until canceled.
### Common Use Cases
```typescript Delete latest version theme={null}
await autumn.plans.delete({
planId: "old_plan"
});
```
```typescript Delete all versions theme={null}
await autumn.plans.delete({
planId: "old_plan",
allVersions: true
});
```
### Body Parameters
The ID of the plan to delete.
If true, deletes all versions of the plan. Otherwise, only deletes the latest version.
### Response
# Get a plan
Source: https://docs.useautumn.com/api-reference/plans/getPlan
openapi POST /v1/plans.get
Retrieves a single plan by its ID.
Use this to fetch the full configuration of a specific plan, including its features and pricing.
Retrieves a single plan by its ID. Returns the latest version by default.
### Common Use Cases
```typescript Get a plan theme={null}
const plan = await autumn.plans.get({
planId: "pro_plan"
});
```
```typescript Get a specific version theme={null}
const plan = await autumn.plans.get({
planId: "pro_plan",
version: 2
});
```
### Body Parameters
The ID of the plan to retrieve.
The version of the plan to get. Defaults to the latest version.
### 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
```json 200 theme={null}
{
"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": {}
}
```
# List all plans
Source: https://docs.useautumn.com/api-reference/plans/listPlans
openapi POST /v1/plans.list
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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
}
]
}
]
}
```
# Update a plan
Source: https://docs.useautumn.com/api-reference/plans/updatePlan
openapi POST /v1/plans.update
Updates an existing plan. Creates a new version unless `disableVersion` is set.
Use this to modify plan properties, pricing, or feature configurations. See [Adding features to plans](/documentation/pricing/plan-features) for item configuration.
Updates an existing plan. By default, creates a new version of the plan. See [Adding features to plans](/documentation/concepts/plan-items) for item configuration.
Updates create a new plan version by default. Existing customers remain on their current version until their subscription renews or they explicitly upgrade.
### Updating Items
When updating `items`, you must provide the complete items array. The new array replaces the existing configuration entirely.
To update a single feature's configuration while keeping others unchanged, include all existing items with the modified values.
### Common Use Cases
```typescript Update plan price theme={null}
await autumn.plans.update({
planId: "pro_plan",
price: { amount: 15, interval: "month" }
});
```
```typescript Remove base price (usage-only plan) theme={null}
await autumn.plans.update({
planId: "pro_plan",
price: null // Removes the base price
});
```
```typescript Update feature's included amount theme={null}
await autumn.plans.update({
planId: "pro_plan",
items: [
{
featureId: "messages",
included: 2000, // Increased from 1000
reset: { interval: "month" }
}
]
});
```
```typescript Archive a plan theme={null}
await autumn.plans.update({
planId: "old_plan",
archived: true
});
```
```typescript Rename a plan theme={null}
await autumn.plans.update({
planId: "pro_plan",
name: "Pro Plan (Updated)",
newPlanId: "pro_plan_v2" // Optional: change the plan ID
});
```
### Body Parameters
The ID of the plan to update.
Display name of the plan.
Whether the plan is an add-on.
Whether the plan is automatically enabled.
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.
Feature configurations for this plan. Each item defines included units, pricing, and reset behavior.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Plans offered as assignable licenses under this plan. The full set replaces existing links.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
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.
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. 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.
Arbitrary key-value metadata defined by you for your own use (e.g. UI copy, feature highlights). Values can be any JSON-serializable value. Shared across all versions of the plan.
The base plan this plan should be linked to as a variant. Set to null to detach it from its base plan.
The new ID to use for the plan. Can only be updated if the plan has not been used by any customers.
Apply the update diff to all versions of this plan. Mutually exclusive with disable\_version.
Force versioning even when no customers exist. Mutually exclusive with disable\_version.
Variant plan IDs to apply this update to. Empty or omitted means no propagation.
Parent plan versions that should receive this license-plan update.
Additive variant updates for this base plan. Missing variants are created when name is provided.
The variant plan ID to update or create.
Display name to use when creating the variant if it does not exist.
The exact customize patch to apply to 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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
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.
Edit this variant in place instead of versioning it for this update.
Force this variant update to create a new version.
Migration draft options for an in-place direct variant update.
Whether this is the org's default plan. Cannot be true on a variant.
### 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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
Bills this many feature units when outstanding overage reaches it.
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.
```json 200 theme={null}
{
"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": {}
}
```
# Create Organization
Source: https://docs.useautumn.com/api-reference/platform/create-organization
platform POST /platform/organizations
Creates a new organization for a platform tenant. Reuses existing users and organizations if they already exist.
Creates a new organization for a platform tenant. If a user with the provided email already exists, it will be reused. If an organization with the slug already exists for this user, it will be reused.
# List Organizations
Source: https://docs.useautumn.com/api-reference/platform/list-orgs
platform GET /platform/organizations
Lists all organizations created by your master organization. Supports pagination.
Lists all organizations created by your master organization. Supports pagination to handle large numbers of tenant organizations.
Only returns organizations that were created by your master organization through the Platform API. Organization slugs in the response do not include the master org ID prefix.
# List Users
Source: https://docs.useautumn.com/api-reference/platform/list-users
platform GET /platform/users
Lists all users created by your master organization. Supports pagination and optional expansion of related organizations.
Lists all users created by your master organization. Supports pagination and optional expansion of related organizations.
# Generate Stripe OAuth URL
Source: https://docs.useautumn.com/api-reference/platform/oauth-url
platform POST /platform/oauth_url
Generates a Stripe Connect OAuth URL for a platform organization. Use this to allow your tenants to connect their Stripe accounts.
Generates a Stripe Connect OAuth URL for a platform organization. Use this to allow your tenants to connect their Stripe accounts through the OAuth flow.
## OAuth Flow
After generating the OAuth URL:
1. Redirect your tenant to the `oauth_url`
2. User authorizes their Stripe account
3. Stripe redirects to Autumn's callback URL
4. Autumn processes the authorization and redirects to your `redirect_url`
5. Your `redirect_url` will receive query parameters:
* `success=true` or `success=false`
* `message=...` (if error occurred)
OAuth state is stored in Upstash with a 10-minute expiry. The organization must have been created via the platform API before generating an OAuth URL.
# Overview
Source: https://docs.useautumn.com/api-reference/platform/overview
Manage Autumn on behalf of your users in a multi-tenant flow
**Private Preview** - This feature is currently in private preview. Contact us at [hey@useautumn.com](mailto:hey@useautumn.com) if you would like access!
## What is the Platform API?
The Platform API is for users who want to manage Autumn on behalf of their users (for example, AI app builders) in a multi-tenant flow.
## How it Works
### 1. Create an Organization
Create an Autumn organization linked to a user email. This generates API keys that your user can use to interact with Autumn's billing features.
### 2. Integrate
Each organization created through Step 1 already has a Stripe account connected to their sandbox environment. As such, you can freely integrate and test Autumn without additional Stripe credentials. When you're ready to go to prod, you can then connect your user's Stripe account through the Step 3.
### 3. Link Stripe Account
Connect your user's Stripe account using one of two methods:
**Option A: OAuth Flow**
Call our [Generate Stripe OAuth URL](/api-reference/platform/oauth-url) endpoint, which generates a link that lets the user connect their Stripe account directly.
**Option B: Direct Account ID**
If you have your own Stripe Connect platform, simply pass us the Stripe account ID using the [Update Connected Stripe Account](/api-reference/platform/update-stripe) endpoint and we'll handle the rest.
# Update Connected Stripe Account
Source: https://docs.useautumn.com/api-reference/platform/update-stripe
platform POST /platform/organizations/stripe
Updates a platform organization's Stripe Connect configuration. Associates a Stripe account ID with the organization using your master Stripe credentials.
Updates a platform organization's Stripe Connect configuration. Associates a Stripe account ID with the organization using your master Stripe credentials.
## When to Use This Endpoint
Use this endpoint when you want to manage Stripe accounts on behalf of your tenants using your own Stripe Connect credentials, rather than having them go through the OAuth flow.
## Validation
* Your organization must have the corresponding Stripe secret key connected (test/live)
* The endpoint validates that your master Stripe account can access the provided account ID
* If validation fails, you'll receive a descriptive error message
The `master_org_id` is automatically set to your organization ID. All Stripe operations for the tenant will use your master Stripe credentials with the tenant's account ID.
At least one of `test_account_id` or `live_account_id` must be provided in the request.
# Create Referral Code
Source: https://docs.useautumn.com/api-reference/referrals/createReferralCode
openapi POST /v1/referrals.create_code
Create or fetch a referral code for a customer in a referral program.
### Body Parameters
The unique identifier of the customer
ID of your referral program
### Response
The referral code that can be shared with customers
Your unique identifier for the customer
The timestamp of when the referral code was created
```json 200 theme={null}
{
"code": "",
"customer_id": "",
"created_at": 123
}
```
# Create Referral Program
Source: https://docs.useautumn.com/api-reference/referrals/createReferralProgram
openapi POST /v1/referral_programs.create
Create a referral program linked to an existing reward.
### Body Parameters
When the reward is granted: on redemption, or when the redeemer checks out.
Who receives the reward: the referrer only, or both parties.
A positive redemption limit, or null for unlimited redemptions.
Required when redeem\_on is checkout. Plan IDs must be unique.
Whether checkouts that start a trial should skip granting the reward.
Address an existing referral program by its stable id. Omit when creating — the server generates one.
### Response
The unique identifier for the referral program.
The ID of the reward granted when a code is redeemed.
When the reward is granted: on redemption, or when the redeemer checks out.
Who receives the reward: the referrer only, or both parties.
The maximum number of times a referral code can be redeemed.
The plans whose checkout triggers the reward. Only used when redeem\_on is checkout.
Whether checkouts that start a trial should skip granting the reward.
The Unix timestamp (in milliseconds) when the referral program was created.
```json 200 theme={null}
{
"id": "refer_a_friend",
"reward_id": "beta_credits_grant",
"redeem_on": "customer_creation",
"received_by": "referrer",
"max_redemptions": 10,
"plan_ids": null,
"exclude_trial": false,
"created_at": 1718000000000
}
```
# Delete Referral Program
Source: https://docs.useautumn.com/api-reference/referrals/deleteReferralProgram
openapi POST /v1/referral_programs.delete
Delete a referral program.
### Body Parameters
The ID of the referral program.
### Response
```json 200 theme={null}
{
"success": true
}
```
# Get Referral Program
Source: https://docs.useautumn.com/api-reference/referrals/getReferralProgram
openapi POST /v1/referral_programs.get
Fetch a referral program by ID.
### Body Parameters
The ID of the referral program.
### Response
The unique identifier for the referral program.
The ID of the reward granted when a code is redeemed.
When the reward is granted: on redemption, or when the redeemer checks out.
Who receives the reward: the referrer only, or both parties.
The maximum number of times a referral code can be redeemed.
The plans whose checkout triggers the reward. Only used when redeem\_on is checkout.
Whether checkouts that start a trial should skip granting the reward.
The Unix timestamp (in milliseconds) when the referral program was created.
```json 200 theme={null}
{
"id": "refer_a_friend",
"reward_id": "beta_credits_grant",
"redeem_on": "customer_creation",
"received_by": "referrer",
"max_redemptions": 10,
"plan_ids": null,
"exclude_trial": false,
"created_at": 1718000000000
}
```
# List Referral Programs
Source: https://docs.useautumn.com/api-reference/referrals/listReferralPrograms
openapi POST /v1/referral_programs.list
List the referral programs configured for the org.
### Response
The unique identifier for the referral program.
The ID of the reward granted when a code is redeemed.
When the reward is granted: on redemption, or when the redeemer checks out.
Who receives the reward: the referrer only, or both parties.
The maximum number of times a referral code can be redeemed.
The plans whose checkout triggers the reward. Only used when redeem\_on is checkout.
Whether checkouts that start a trial should skip granting the reward.
The Unix timestamp (in milliseconds) when the referral program was created.
```json 200 theme={null}
{
"list": [
{
"id": "refer_a_friend",
"reward_id": "beta_credits_grant",
"redeem_on": "customer_creation",
"received_by": "referrer",
"max_redemptions": 10,
"plan_ids": null,
"exclude_trial": false,
"created_at": 1718000000000
}
]
}
```
# Redeem Referral Code
Source: https://docs.useautumn.com/api-reference/referrals/redeemReferralCode
openapi POST /v1/referrals.redeem_code
Redeem a referral code for a customer.
### Body Parameters
The referral code to redeem
The unique identifier of the customer redeeming the code
### Response
The ID of the redemption event
Your unique identifier for the customer
The ID of the reward that will be granted
```json 200 theme={null}
{
"id": "",
"customer_id": "",
"reward_id": ""
}
```
# Update Referral Program
Source: https://docs.useautumn.com/api-reference/referrals/updateReferralProgram
openapi POST /v1/referral_programs.update
Update a referral program. Omitted fields keep their current value.
### Body Parameters
The ID of the referral program.
The ID of the reward granted when a code is redeemed.
When the reward is granted: on redemption, or when the redeemer checks out.
Who receives the reward: the referrer only, or both parties.
A positive redemption limit. Omit to leave unchanged; null removes it.
Required when redeem\_on is checkout. Plan IDs must be unique. Omit to leave unchanged; null removes them.
Omit to leave unchanged; null removes it.
### Response
The unique identifier for the referral program.
The ID of the reward granted when a code is redeemed.
When the reward is granted: on redemption, or when the redeemer checks out.
Who receives the reward: the referrer only, or both parties.
The maximum number of times a referral code can be redeemed.
The plans whose checkout triggers the reward. Only used when redeem\_on is checkout.
Whether checkouts that start a trial should skip granting the reward.
The Unix timestamp (in milliseconds) when the referral program was created.
```json 200 theme={null}
{
"id": "refer_a_friend",
"reward_id": "beta_credits_grant",
"redeem_on": "customer_creation",
"received_by": "referrer",
"max_redemptions": 10,
"plan_ids": null,
"exclude_trial": false,
"created_at": 1718000000000
}
```
# Create Reward
Source: https://docs.useautumn.com/api-reference/rewards/createReward
openapi POST /v1/rewards.create
Create a coupon or feature grant.
### Body Parameters
Provide exactly one of coupon or feature\_grant, not both.
Use a positive integer length for months, and null for one\_off or forever.
Plan IDs must be unique.
Promo code values must be unique.
Address an existing reward by its stable id. Omit when creating — the server generates one.
Percentage discounts must be at most 100; fixed discounts must be positive.
Provide exactly one of coupon or feature\_grant, not both.
Feature IDs must be unique.
A non-negative amount to grant, or null for boolean features.
The unit of time the grant lasts.
The positive integer count of periods before the grant expires.
Promo code values must be unique.
A positive redemption limit, or null for unlimited uses.
Address an existing reward by its stable id. Omit when creating — the server generates one.
### Response
The unique identifier for the coupon.
A human-readable name for the coupon.
The type of discount: percentage\_discount, fixed\_discount, or invoice\_credits.
The discount value. A percentage for percentage\_discount, or an amount for fixed\_discount / invoice\_credits.
How long the coupon applies once redeemed.
The unit of time the duration is measured in.
The number of `type` periods the duration lasts, or null when the type has no length (e.g. one\_off, forever).
The plan IDs the coupon applies to, or null when it applies to all plans.
The promo code customers enter to redeem the coupon.
Maximum number of times this promo code can be redeemed across all customers, or null for unlimited.
Whether this promo code can only be applied to a customer's first transaction.
The Unix timestamp (in milliseconds) when the coupon was created.
The unique identifier for the feature grant.
A human-readable name for the feature grant.
The feature ID this grant applies to.
The amount of the feature granted, or null for boolean features.
How long the granted amount lasts before expiring, or null for a permanent grant.
The unit of time the grant lasts.
The positive integer count of periods before the grant expires.
The promo code customers enter to redeem the feature grant.
Maximum number of times this promo code can be redeemed, or null for unlimited.
The Unix timestamp (in milliseconds) when the feature grant was created.
# Delete Reward
Source: https://docs.useautumn.com/api-reference/rewards/deleteReward
openapi POST /v1/rewards.delete
Delete a coupon or feature grant.
### Body Parameters
The ID of the coupon or feature grant.
### Response
```json 200 theme={null}
{
"success": true
}
```
# Get Reward
Source: https://docs.useautumn.com/api-reference/rewards/getReward
openapi POST /v1/rewards.get
Fetch a coupon or feature grant by ID.
### Body Parameters
The ID of the coupon or feature grant.
### Response
The unique identifier for the coupon.
A human-readable name for the coupon.
The type of discount: percentage\_discount, fixed\_discount, or invoice\_credits.
The discount value. A percentage for percentage\_discount, or an amount for fixed\_discount / invoice\_credits.
How long the coupon applies once redeemed.
The unit of time the duration is measured in.
The number of `type` periods the duration lasts, or null when the type has no length (e.g. one\_off, forever).
The plan IDs the coupon applies to, or null when it applies to all plans.
The promo codes customers can use to redeem the coupon.
The promo code customers enter to redeem the coupon.
Maximum number of times this promo code can be redeemed across all customers, or null for unlimited.
Whether this promo code can only be applied to a customer's first transaction.
The Unix timestamp (in milliseconds) when the coupon was created.
The unique identifier for the feature grant.
A human-readable name for the feature grant.
The feature grants awarded when the grant is redeemed.
The feature ID this grant applies to.
The amount of the feature granted, or null for boolean features.
How long the granted amount lasts before expiring, or null for a permanent grant.
The unit of time the grant lasts.
The positive integer count of periods before the grant expires.
The promo codes customers can use to redeem the feature grant.
The promo code customers enter to redeem the feature grant.
Maximum number of times this promo code can be redeemed, or null for unlimited.
The Unix timestamp (in milliseconds) when the feature grant was created.
```json 200 theme={null}
{
"coupon": {
"id": "summer_sale",
"name": "Summer Sale",
"type": "percentage_discount",
"value": 20,
"duration": {
"type": "months",
"length": 3
},
"plan_ids": [
"pro",
"starter"
],
"promo_codes": [
{
"code": "SUMMER20",
"global_max_redemption": 100,
"first_time_transaction": false
}
],
"created_at": 1718000000000
}
}
```
# List Rewards
Source: https://docs.useautumn.com/api-reference/rewards/listRewards
openapi POST /v1/rewards.list
List the coupons and feature grants configured for the org.
### Response
The list of coupons configured for the organization.
The unique identifier for the coupon.
A human-readable name for the coupon.
The type of discount: percentage\_discount, fixed\_discount, or invoice\_credits.
The discount value. A percentage for percentage\_discount, or an amount for fixed\_discount / invoice\_credits.
How long the coupon applies once redeemed.
The unit of time the duration is measured in.
The number of `type` periods the duration lasts, or null when the type has no length (e.g. one\_off, forever).
The plan IDs the coupon applies to, or null when it applies to all plans.
The promo codes customers can use to redeem the coupon.
The promo code customers enter to redeem the coupon.
Maximum number of times this promo code can be redeemed across all customers, or null for unlimited.
Whether this promo code can only be applied to a customer's first transaction.
The Unix timestamp (in milliseconds) when the coupon was created.
The list of feature grants configured for the organization.
The unique identifier for the feature grant.
A human-readable name for the feature grant.
The feature grants awarded when the grant is redeemed.
The feature ID this grant applies to.
The amount of the feature granted, or null for boolean features.
How long the granted amount lasts before expiring, or null for a permanent grant.
The unit of time the grant lasts.
The positive integer count of periods before the grant expires.
The promo codes customers can use to redeem the feature grant.
The promo code customers enter to redeem the feature grant.
Maximum number of times this promo code can be redeemed, or null for unlimited.
The Unix timestamp (in milliseconds) when the feature grant was created.
```json 200 theme={null}
{
"coupons": [],
"feature_grants": []
}
```
# Redeem Reward Code
Source: https://docs.useautumn.com/api-reference/rewards/redeemRewardCode
openapi POST /v1/rewards.redeem
Redeem a reward promo code for a customer.
### Body Parameters
The reward promo code to redeem
The unique identifier of the customer redeeming the code
### Response
The ID of the redeemed reward
The feature balances granted to the customer
The ID of the feature granted by the reward
The balance granted for the feature
```json 200 theme={null}
{
"reward_id": "reward_789",
"entitlements_granted": [
{
"feature_id": "messages",
"balance": 100
}
]
}
```
# Update Reward
Source: https://docs.useautumn.com/api-reference/rewards/updateReward
openapi POST /v1/rewards.update
Update a coupon or feature grant. Omitted fields keep their current value.
### Body Parameters
The ID of the coupon or feature grant.
Plan IDs must be unique. Null applies the coupon to all plans.
Replaces the existing promo codes when provided.
Replaces the existing grants when provided.
How long the granted amount lasts before expiring, or null for a permanent grant.
The unit of time the grant lasts.
The positive integer count of periods before the grant expires.
Replaces the existing promo codes when provided.
### Response
The unique identifier for the coupon.
A human-readable name for the coupon.
The type of discount: percentage\_discount, fixed\_discount, or invoice\_credits.
The discount value. A percentage for percentage\_discount, or an amount for fixed\_discount / invoice\_credits.
How long the coupon applies once redeemed.
The unit of time the duration is measured in.
The number of `type` periods the duration lasts, or null when the type has no length (e.g. one\_off, forever).
The plan IDs the coupon applies to, or null when it applies to all plans.
The promo code customers enter to redeem the coupon.
Maximum number of times this promo code can be redeemed across all customers, or null for unlimited.
Whether this promo code can only be applied to a customer's first transaction.
The Unix timestamp (in milliseconds) when the coupon was created.
The unique identifier for the feature grant.
A human-readable name for the feature grant.
The feature ID this grant applies to.
The amount of the feature granted, or null for boolean features.
How long the granted amount lasts before expiring, or null for a permanent grant.
The unit of time the grant lasts.
The positive integer count of periods before the grant expires.
The promo code customers enter to redeem the feature grant.
Maximum number of times this promo code can be redeemed, or null for unlimited.
The Unix timestamp (in milliseconds) when the feature grant was created.
```json 200 theme={null}
{
"feature_grant": {
"id": "beta_credits_grant",
"name": "Beta Tester Credits",
"promo_codes": [
{
"code": "BETA2024",
"max_uses": 500
}
],
"grants": [
{
"feature_id": "credits",
"included": 1000,
"expiry": {
"type": "month",
"length": 1
}
}
],
"created_at": 1718000000000
}
}
```
# Limit Reached
Source: https://docs.useautumn.com/api-reference/webhooks/balancesLimitReached
api/openapi.yml webhook balances.limit_reached
Fired when a customer reaches the limit for a feature (included allowance, max purchase, spend limit, or a usage-limit billing control).
### Payload Fields
The ID of the customer who hit the limit.
The entity ID, if the limit was reached on a specific entity.
The feature ID whose limit was reached.
Which limit was hit: included allowance, max purchase cap, spend limit, or a usage-limit billing control.
The filter of the usage limit that blocked, when a filtered cap was hit.
The usage limit that blocked, with its live window. Present only when limit\_type is usage\_limit.
Maximum units allowed per interval.
Interval of the cap.
Window alignment the cap was configured with.
Units consumed in the current window, after this event.
Units left in the current window, never below zero.
Start of the current window, in milliseconds since epoch.
End of the current window, in milliseconds since epoch.
# Usage Alert Triggered
Source: https://docs.useautumn.com/api-reference/webhooks/balancesUsageAlertTriggered
api/openapi.yml webhook balances.usage_alert_triggered
Fired when a customer crosses a configured usage alert threshold.
### Payload Fields
The ID of the customer whose usage alert was triggered.
The feature ID the alert applies to.
The entity ID the alert applies to, if the usage was entity-scoped.
Details of the usage alert that was triggered.
User-defined label for the alert, if provided.
The threshold value that was crossed.
Whether the threshold is an absolute usage count or a percentage.
What 100% meant for this alert.
The balance the alert measured.
Units consumed on the feature, after this event.
Every grant on the feature: included, prepaid and rollover.
Grants from plan allowances only.
The alert's denominator minus usage. Clamped at zero for included and recurring; balance can go negative on overage.
# Auto Top-Up Failed
Source: https://docs.useautumn.com/api-reference/webhooks/billingAutoTopupFailed
api/openapi.yml webhook billing.auto_topup_failed
Fired when an automatic top-up is blocked, declined, or fails before granting additional prepaid balance.
### Payload Fields
The ID of the customer whose auto top-up failed.
The feature ID that Autumn attempted to auto top-up.
Machine-readable reason the automatic top-up did not grant balance.
The normalized amount of balance Autumn attempted to grant, when a matching auto top-up config was available.
The configured balance threshold for the auto top-up, when available.
The customer's remaining balance for the feature at the time the failure was detected, when available.
Whether the auto top-up was configured to create a send\_invoice invoice instead of auto-charging.
Sanitized provider or Autumn error metadata, when the failure came from an exception or declined charge.
Machine-readable error code when one is available (for example, a Stripe or Autumn error code).
Sanitized error message with details about why the auto top-up failed.
Provider error type when one is available.
Stripe decline code when the failure came from a card decline.
# Auto Top-Up Succeeded
Source: https://docs.useautumn.com/api-reference/webhooks/billingAutoTopupSucceeded
api/openapi.yml webhook billing.auto_topup_succeeded
Fired when an automatic top-up grants additional prepaid balance.
### Payload Fields
The ID of the customer whose balance was topped up.
The feature ID that was automatically topped up.
The normalized amount of balance granted by the top-up.
The configured balance threshold that triggered the top-up.
The customer's remaining balance for the feature after the top-up.
Whether the auto top-up created a send\_invoice invoice instead of auto-charging.
The invoice created for the auto top-up.
The Stripe invoice ID. Use this as a stable dedupe key.
The status of the invoice. "paid" for auto-charged top-ups; "open" for invoice-mode top-ups where credits were granted but the invoice has not yet been paid.
The total amount of the invoice in the smallest currency unit (e.g. cents for USD), matching Stripe's invoice.total.
The ISO currency code for the invoice.
URL to the hosted invoice page, if available.
# Plans Updated
Source: https://docs.useautumn.com/api-reference/webhooks/billingUpdated
api/openapi.yml webhook billing.updated
Fired when a customer's plans change — activated, scheduled, updated, or expired. Each event carries a `plan_changes` array describing what happened and a `tags` array (e.g. `trial_ended`, `phase_changed`) describing why.
### Payload Fields
The ID of the customer whose plans changed.
The ID of the entity, if the changes are scoped to a specific entity.
The plans that were activated, scheduled, updated, or expired.
The ID of the entity this plan is scoped to, or null when the plan is customer-level. A single event can carry changes for several entities.
The lifecycle action applied to this plan: activated (newly active on the customer), scheduled (queued for a future start), updated (mutated in place), or expired (ended).
The subscription as it stands after this change. Present when the plan is billed as a recurring subscription.
The ID of the customer plan.
The current status of the subscription on the customer.
Whether the subscription has overdue payments.
When the subscription started, in milliseconds since the Unix epoch.
When the subscription was canceled, in milliseconds since the Unix epoch, or null if not canceled.
When the subscription ends, in milliseconds since the Unix epoch, or null if no expiry is set.
When the trial ends, in milliseconds since the Unix epoch. Null when not actively trialing.
Start of the current billing period, or null if not applicable.
End of the current billing period, or null if not applicable.
The purchase as it stands after this change. Present when the plan is a one-off purchase.
The ID of the customer plan.
The current status of the purchase on the customer.
When the purchase ends, in milliseconds since the Unix epoch, or null if no expiry is set.
Sparse map of lifecycle scalar fields whose values changed, holding their previous values. Null when the plan is newly activated or scheduled, or when no lifecycle field changed.
The current status of the subscription on the customer.
Whether the subscription has overdue payments.
When the subscription was canceled, in milliseconds since the Unix epoch, or null if not canceled.
When the subscription ends, in milliseconds since the Unix epoch, or null if no expiry is set.
When the trial ends, in milliseconds since the Unix epoch. Null when not actively trialing.
Content-level change to the plan definition for this customer plan (items, base price, free trial).
The plan after the change. Omitted unless the caller expands it.
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.
Bills this many feature units when outstanding overage reaches it.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
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.
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.
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.
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.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
Sparse map of scalar plan fields that changed, holding their previous values. Null when the plan is new.
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.
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.
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.
Whether this is the active version of the plan. At most one version is active.
Whether the plan is archived. Archived plans cannot be attached to new customers.
Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
Previous payment processors when they changed. Null when the plan had none.
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.
Previous free trial when it changed. Null when the plan had none.
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.
Sparse previous billing\_controls — only keys that changed. Null when unset; a null lane was unset before.
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.
Present when the plan's price changed.
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.
The plan's price after the change.
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.
Present when the plan's free trial changed.
The plan's free trial before the change. Null when none.
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.
The plan's free trial after the change. Null when none.
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.
Feature items added to or removed from the plan.
Whether the item was added to or removed from the plan.
The ID of the feature that was added or removed.
The plan item snapshot that was added or removed.
Bills this many feature units when outstanding overage reaches it.
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.
Params that would transform the previous plan into the current one, including license upserts/removes.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
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.
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.
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.
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.
The feature ID this overage allowed control applies to.
Whether overage is allowed for this feature.
planLicenses created or overridden. Same shape as customize.upsert\_licenses / licenses\[] entries.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
planLicenses dropped from this plan.
planLicenses created, updated, or removed on this plan. Omitted when none. Nested plan\_change is core-only.
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.
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.
Bills this many feature units when outstanding overage reaches it.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
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.
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.
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.
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.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
created = new planLicense; updated = row or effective content changed; removed = dropped.
Previous included / prepaid\_only / version. Null when created or removed, or when no row scalar changed.
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.
Diff of the license's effective plan. Null when created, removed, or the effective content is unchanged.
The plan after the change. Omitted unless the caller expands it.
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.
Bills this many feature units when outstanding overage reaches it.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
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.
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.
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.
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.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
Sparse map of scalar plan fields that changed, holding their previous values. Null when the plan is new.
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.
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.
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.
Whether this is the active version of the plan. At most one version is active.
Whether the plan is archived. Archived plans cannot be attached to new customers.
Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
Previous payment processors when they changed. Null when the plan had none.
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.
Previous free trial when it changed. Null when the plan had none.
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.
Sparse previous billing\_controls — only keys that changed. Null when unset; a null lane was unset before.
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.
Present when the plan's price changed.
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.
The plan's price after the change.
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.
Present when the plan's free trial changed.
The plan's free trial before the change. Null when none.
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.
The plan's free trial after the change. Null when none.
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.
Feature items added to or removed from the plan.
Whether the item was added to or removed from the plan.
The ID of the feature that was added or removed.
The plan item snapshot that was added or removed.
Bills this many feature units when outstanding overage reaches it.
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.
Params that would transform the previous plan into the current one. Omitted when nothing customizable changed.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
Override the plan's billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
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.
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.
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.
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.
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').
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.
Bills this many feature units when outstanding overage reaches it.
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.
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.
Deprecated — use plan\_change.item\_changes. Features that were added to or removed from this plan.
Whether the item was added to or removed from the plan.
The ID of the feature that was added or removed.
The plan item snapshot that was added or removed.
Bills this many feature units when outstanding overage reaches it.
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.
Reason tags describing why this event fired (e.g. 'trial\_ended', 'phase\_changed'). Always present; empty when no specific reason applies.
# Invoice Finalized
Source: https://docs.useautumn.com/api-reference/webhooks/invoiceFinalized
api/openapi.yml webhook invoice.finalized
Fired when a Stripe invoice is finalized and its line items have been reconciled. The body is the invoice as returned by `invoices.list`, with `items` populated and each item carrying a per-entity `entities` breakdown.
### Payload Fields
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
The Autumn invoice ID
The ID of the customer this invoice belongs to. Null for customers created without an ID.
The ID of the entity this invoice belongs to, if entity-scoped
The amount paid on the invoice. Null on invoices recorded before amounts paid were tracked.
The total amount refunded on the invoice
Line items on the invoice, one per line as shown in Stripe. Capped at 100. Empty for invoices recorded before line item storage.
Description of the invoice line item
Timestamp when the billing period starts
Timestamp when the billing period ends
The plan this line item came from. Null for lines with no Autumn plan behind them.
The ID of the feature associated with this line item
The name of the feature associated with this line item
Quantity actually charged on this line. Null on fixed-price lines.
Amount charged on this line, pre-discount and pre-tax. Negative for credits.
How this line splits by entity. Empty for customer-level lines. Only populated for invoices finalized after entity attribution shipped.
The entity this share of the line item is attributed to
Quantity charged to this entity. Null on fixed-price lines.
Amount attributed to this entity, pre-discount and pre-tax
# Resource Deleted
Source: https://docs.useautumn.com/api-reference/webhooks/vercelResourcesDeleted
api/openapi.yml webhook vercel.resources.deleted
When a Vercel resource is deleted, you'll need to handle de-provisioning any API keys or other non-Autumn controlled data for this user.
### Payload Fields
The resource that was deleted.
The unique identifier of the deleted resource.
The Vercel integration configuration ID.
# Resource Provisioned
Source: https://docs.useautumn.com/api-reference/webhooks/vercelResourcesProvisioned
api/openapi.yml webhook vercel.resources.provisioned
When a Vercel resource is created, you'll need to provision a secret key for your service. Then you can use the provided access token to patch the resource's secrets.
### Payload Fields
The resource that was provisioned.
The unique identifier of the provisioned resource.
The display name of the provisioned resource.
The Vercel integration configuration ID.
An access token that can be used to patch the resource's secrets.
# Rotate Secrets
Source: https://docs.useautumn.com/api-reference/webhooks/vercelResourcesRotateSecrets
api/openapi.yml webhook vercel.resources.rotate_secrets
This event is sent when Vercel requires a resource's secrets to be rotated.
### Payload Fields
The resource whose secrets should be rotated.
The unique identifier of the resource.
The Vercel integration configuration ID.
The raw request body from Vercel's rotation request.
# Webhook Event
Source: https://docs.useautumn.com/api-reference/webhooks/vercelWebhooksEvent
api/openapi.yml webhook vercel.webhooks.event
Passthrough webhook for Vercel events.
### Payload Fields
The Vercel integration configuration ID.
The raw Vercel webhook event payload.
# Changelog
Source: https://docs.useautumn.com/changelog/changelog
Some new things we've shipped at Autumn HQ
## `atmn` 2.0
The new [`atmn` CLI](/cli/getting-started) is out of nightly and published as `atmn@2`. `atmn init` sets up a repo in one go: it connects to Autumn (sign in, or keyless with no account), creates an `autumn/` folder with `autumn.config.ts`, `features.ts`, `plans.ts` and `rewards.ts`, adds `atmn` to your `package.json`, pulls your existing catalog and installs the agent skills. `atmn push` always previews first and applies with `--yes`. A new `atmn api` command calls any public endpoint from the terminal. Coupons, feature grants, referral programs and organization settings can now be declared in the config alongside features and plans. Configs from `atmn` 1.x are refused with a message pointing at the upgrade steps; see [upgrading from 1.x](/cli/getting-started#upgrading-from-1x). The [CLI reference](/cli/commands) and [config reference](/cli/config) are rewritten for the release.
## Rate cards and dimensions for everyone
Billing units, graduated tiers, per-row dimensions and plan-item rate-card overrides are no longer admin-only in the dashboard. Dimensions now live inside each rate-card row: **Add dimension** sits beside **Add Tier** and reveals that row's tables, a populated row shows its tables with a **Remove dimensions** action, and collapsed rows count their dimensions. Picking a feature on a new row opens it for editing straight away, and the only row in a rate card can be removed (an empty card is still rejected on save). The Stripe product field has left the feature sheets; feature-level Stripe products are managed through the CLI mappings. Customizing a customer's rate card from the dashboard now reaches the server: plan diffs compare and carry `feature_override`. The CLI config reference and the [credit systems guide](/documentation/modelling-pricing/credit-systems#rate-cards-and-dimensions) document billing units, tiers, dimensions and multipliers — [#3413](https://github.com/useautumn/autumn/pull/3413)
## Credit dimensions and multipliers
[Credit systems](/documentation/modelling-pricing/credit-systems) can now price a single feature at different rates based on event properties. Each rate-card row accepts named `dimensions` that match on properties (with a flat or graduated rate and optional priority) and `multipliers` that scale the rate by a factor or additive adjustment. The most specific matching dimension sets the rate, multipliers scale it, and the winning dimension becomes the usage-attribution key. `check`, `track`, and `finalize` all price by the event's properties, invoice credits bill one line per (feature, dimension) with the dimension named on the line, and the dashboard rate-card editor gains a **Dimensions** switch with per-row editors. Rate cards, dimensions, and multipliers are validated at save time — ambiguous same-specificity dimensions and multipliers that could drive the price negative are rejected. `credit_schema` items round-trip `dimensions` and `multipliers` (with `credit_cost` naming) through the API and the `atmn` CLI — [#3216](https://github.com/useautumn/autumn/pull/3216), [#3217](https://github.com/useautumn/autumn/pull/3217), [#3218](https://github.com/useautumn/autumn/pull/3218), [#3220](https://github.com/useautumn/autumn/pull/3220), [#3226](https://github.com/useautumn/autumn/pull/3226), [#3228](https://github.com/useautumn/autumn/pull/3228)
## Threshold billing
Plan items accept a new optional `threshold_billing: { threshold }` config that triggers a charge each time usage crosses the threshold. Crossing a threshold charges exactly one chunk (leaving the remainder), and a failed threshold invoice marks the product `past_due` and blocks usage on that plan until the invoice is paid. Prepaid, unlimited, and tiered pricing are rejected; positive thresholds only. The config carries through the API, persistence, and comparison paths — [#3331](https://github.com/useautumn/autumn/pull/3331), [#3332](https://github.com/useautumn/autumn/pull/3332)
## The new `atmn` CLI
The new [`atmn`](/cli/getting-started) CLI (in nightly, since released as `atmn@2`) manages your catalog — features, plans, plan versions, rewards, referral programs, and a subset of org settings — as TypeScript. `atmn init` scaffolds auth, config path, an initial pull, and a skills folder in one command. `atmn push` takes a config all the way to a live catalog (preview → render → apply), with `--dry-run` stopping after preview. `atmn pull` restores plans and versions with stable `internalId`s, elides values equal to their spec default, and refuses to touch dynamic (non-literal) fixtures. Push backfills minted IDs into fixtures so round-trips preserve identity. Config-wide linting runs up-front and reports every problem at once with field breadcrumbs. `atmn env` prints the resolved organization, environment, user, key, sandbox, and server URL. A new `settings` block manages org config flags PATCH-shaped, and `atmn sandbox use` switches sandboxes. Bundled skills scaffold hint-based prompting with `--headless`/`-c` — [#3235](https://github.com/useautumn/autumn/pull/3235), [#3254](https://github.com/useautumn/autumn/pull/3254), [#3261](https://github.com/useautumn/autumn/pull/3261), [#3262](https://github.com/useautumn/autumn/pull/3262), [#3266](https://github.com/useautumn/autumn/pull/3266), [#3330](https://github.com/useautumn/autumn/pull/3330), [#3335](https://github.com/useautumn/autumn/pull/3335), [#3351](https://github.com/useautumn/autumn/pull/3351), [#3360](https://github.com/useautumn/autumn/pull/3360), [#3370](https://github.com/useautumn/autumn/pull/3370), [#3374](https://github.com/useautumn/autumn/pull/3374)
## Writable usage counters
Customer and entity update endpoints now persist explicitly supplied `usage` values to durable usage windows in the same transaction as any limit-config change. `UsageLimitUpdateSchema` accepts writable usage-limit updates, including usage-only entries (`feature_id` + `usage`) that reject limit-configuration fields. Positive usage without a configured limit returns a 400. Customer billing sheets in the dashboard now let you set current usage when creating or editing usage limits, including plan-inherited caps — [#3339](https://github.com/useautumn/autumn/pull/3339), [#3340](https://github.com/useautumn/autumn/pull/3340), [#3342](https://github.com/useautumn/autumn/pull/3342)
## API v2.4: leaner customer reads and paged lists
From API v2.4, customer-level reads no longer fold in entity subscriptions and balances — use the entities endpoints when you need them — and every list endpoint caps page size at 200. API v2.3 keeps the previous behavior via version gating — [#3271](https://github.com/useautumn/autumn/pull/3271)
* [Rewards and referral programs](/documentation/modelling-pricing/rewards) can now be declared in `atmn` config and managed by `atmn push`; free-product and invoice-credit rewards are intentionally out of scope and left untouched — [#3330](https://github.com/useautumn/autumn/pull/3330)
* Trial expiry now also fires [`customer.products.updated`](/api-reference/webhooks/billingUpdated) with `scenario: expired` (previously only `billing.updated` `trial_ended`), so downstream listeners see the fallback plan take effect — [#3353](https://github.com/useautumn/autumn/pull/3353)
* `check.lock` accepts a new `overage_behavior` of `reject` (default, unchanged), `cap`, or `overflow`; the choice is persisted on the lock receipt and honoured by `finalize` for over-lock deductions — [#3359](https://github.com/useautumn/autumn/pull/3359)
* The OAuth allowlist now includes `customers:write`, `features:write`, `plans:write`, and `apiKeys:write`, so the new `atmn` login no longer fails with `invalid_scope` — [#3354](https://github.com/useautumn/autumn/pull/3354)
* The plan-level `allow_overdue_entitlements` opt-out is removed; overdue access blocking is now purely org-level, and past-due plans are blocked whenever the org block is on. Requests containing the removed field fail validation — [#3352](https://github.com/useautumn/autumn/pull/3352)
* The per-feature auto-top-up attempt limit moves into Rate Limit Overrides as `auto_topup_attempts` (default 2 per 10 minutes); existing `maxAutoTopupAttempts` values are not migrated and silently fall back to default — [#3357](https://github.com/useautumn/autumn/pull/3357), [#3327](https://github.com/useautumn/autumn/pull/3327), [#3329](https://github.com/useautumn/autumn/pull/3329)
* Catalog features can be addressed by a nullable `internal_id` in `catalogV2.update` for stable references across renames (a differing `feature_id` is a rename, an unknown id returns 400). Previews and results include `internal_id` for features and plans — [#3263](https://github.com/useautumn/autumn/pull/3263)
* Analytics `bin_size=month` queries are served from new monthly rollups for complete calendar months, reading hourly rollups only for the partial months at either end. Non-UTC viewers hit the same path because month bins now request UTC (period labels are unchanged), and custom date ranges gain week and month granularity — [#3376](https://github.com/useautumn/autumn/pull/3376), [#3377](https://github.com/useautumn/autumn/pull/3377)
* Expired plan balances now appear in the dashboard when the Plans filter includes **Expired** (view-only), and expired loose balances render greyed out when `include_expired_loose` is set. API responses are unchanged — [#3066](https://github.com/useautumn/autumn/pull/3066)
* Consumed standalone balances with a scheduled reset stay in the customer dashboard's active view; zero-balance standalone entitlements are classified as expired only when `next_reset_at` is null. Drained standalone entitlements now also appear in the dashboard's Expired view — [#3325](https://github.com/useautumn/autumn/pull/3325), [#3326](https://github.com/useautumn/autumn/pull/3326), [#3323](https://github.com/useautumn/autumn/pull/3323)
* The dashboard uses a standalone balance's external ID as its source label when no plan is attached (e.g. goodwill), falling back to **No plan** only when the external ID is missing — [#3356](https://github.com/useautumn/autumn/pull/3356)
* A new customer-scoped rate limit caps `POST /v1/entities.list` at 10 rps per customer (the org-wide 50 rps cap remains), so a single large customer can no longer saturate the database with expensive entity-list queries — [#3273](https://github.com/useautumn/autumn/pull/3273)
* Paid invoice-credit plans no longer add an empty metered credit row to Stripe renewal invoices when a fixed recurring item on the same customer product supplies the same interval. Existing subscriptions pick up the removal on their next subscription-item update; historical invoices are unchanged — [#3379](https://github.com/useautumn/autumn/pull/3379)
* Retrying `attach` or `multi_attach` against an existing open invoice now returns that invoice and its `payment_url` instead of a 409 conflict, resuming the original payment rather than creating a replacement — [#3364](https://github.com/useautumn/autumn/pull/3364)
* Catalog `new_version` push no longer fails with "historical version has customers" when an unpromoted draft version sits above the active row; the active row can mint new versions again — [#3362](https://github.com/useautumn/autumn/pull/3362)
* Pooled license grants are now derived from purchased seats × per-seat grant, including unassigned capacity, instead of only assigned-seat contributions. Usage is preserved across quantity changes, resets, and scheduled activation. License-quantity updates fall back to the catalog credit when stored invoice rows lag behind the pool, and a free parent plan linked to an unpriced pooled license plan now mints its pooled balance on every default-plan path — [#3272](https://github.com/useautumn/autumn/pull/3272), [#3321](https://github.com/useautumn/autumn/pull/3321), [#3316](https://github.com/useautumn/autumn/pull/3316)
* When a plan has both a recurring and a one-off prepaid price for the same feature, `feature_quantities` now applies only to the recurring one, fixing a double-charge/double-grant on attach and mis-routing on update — [#3243](https://github.com/useautumn/autumn/pull/3243)
* Catalog push now rejects up front when a coupon references a plan being renamed or removed in the same request, preventing partially-applied writes where the rename committed and the reward writer then threw — [#3348](https://github.com/useautumn/autumn/pull/3348)
* Variant license overlays (`customize.remove_licenses` / `upsert_licenses`) round-trip through catalog reads and diffs, so `atmn pull` and repeated pushes no longer lose `remove_licenses` or spuriously re-add links. Slug-less nested `variants[]` entries resolve against the base row they sit under, and the CLI backfills `internalId` and `versionSlug` onto inline variants on push and pull — [#3347](https://github.com/useautumn/autumn/pull/3347), [#3344](https://github.com/useautumn/autumn/pull/3344), [#3346](https://github.com/useautumn/autumn/pull/3346)
## Usage alerts can measure what you choose
Usage alerts gain a `basis` field that defines what 100% means: the full `balance` (the default, unchanged), the plan's `included` grants, `recurring` grants, or a `usage_limit` window, plus an optional filter that targets a specific usage limit. The [`balances.usage_alert_triggered`](/api-reference/webhooks/balancesUsageAlertTriggered) webhook now carries the alert's basis and the measured window, and [`balances.limit_reached`](/api-reference/webhooks/balancesLimitReached) includes a `usage_limit` block describing the blocking cap with its live window bounds. The dashboard adds a **Measured against** dropdown on plan, customer, and entity alert forms. Existing alerts keep the `balance` behavior with no migration required.
## Map plans to existing Stripe and RevenueCat products
Catalog plans now accept a `processors` object so Autumn can reuse your existing Stripe catalog instead of minting new objects. Set `processors.stripe` once on a plan and the product mapping fans out to every version and variant, supply a `price_id` to adopt an existing Stripe price (unknown IDs return a 400 instead of silently minting a replacement), or pass `null` to unlink a mapping. RevenueCat product mappings move into the same envelope via `processors.revenuecat`. The dashboard plan page gains a plan-level Stripe product mapping and per-version Stripe price pickers under Advanced.
## Full-state catalog pushes and stable row IDs
Catalog rows now carry a stable `internal_id`, so configs that rename a `plan_id` or `version_slug` keep addressing the same row (the old plan ID survives as an alias). One update request can state multiple versions of the same plan at once, and unknown version slugs mint a new version instead of returning a 400. Setting `skip_deletions: false` treats the payload as the complete desired catalog: omitted plans and features are removed, restating an archived plan revives it, and `skip_plan_ids` / `skip_feature_ids` exempt entries from removal.
## Plans show as pending before payment
Plans attached via Stripe Checkout or invoice mode with `enable_plan_immediately: false` now appear on the customer immediately with a new `Pending` status, instead of being invisible until payment lands. A pending plan grants nothing; it promotes to active when the invoice is paid or the checkout session completes, and expires if the invoice is voided or the session expires.
## Custom rate cards per plan
Plan items on [credit systems](/documentation/modelling-pricing/credit-systems) accept a new `feature_override`, letting a plan reprice or re-member a credit schema without forking the feature. Overrides are honored across track and check rates, membership, subscription updates, and invoice credits. The plan editor gains a **Custom rate card** section, and customer balances show a read-only view of the override.
## Pooled balances for license plans
License plans now support pooled balances: each license link mints a pool, and all seats under it contribute to one shared balance that check, track, resets, and rollovers read like any other. Seat adds, removals, and amount changes flow through, and reducing seat quantity shrinks the pool by expiring unused seats first. The `atmn` CLI also round-trips `pooled` and `entityFeatureId` on plan items through push and pull.
* The attach sheet now defaults trial-end behavior to **Revert to previous plan** instead of billing, with an explanatory **On trial end** select replacing the old checkbox; plans setting `on_end: "bill"` are still respected — [#3190](https://github.com/useautumn/autumn/pull/3190)
* The Add Reward modal can now find coupons by pasting a Stripe promotion code, discount amounts are formatted as currency, and the applied-coupon chip gains a details tooltip — [#3237](https://github.com/useautumn/autumn/pull/3237)
* The credit-system rate card editor is redesigned into accordion rows with compact summaries ("1 credit per 100 messages") that expand into a full editor — [#3204](https://github.com/useautumn/autumn/pull/3204)
* Catalog license links now stay anchored to the exact child version they were created against, pinnable via `version_slug`; variant propagation is pin-only (the `propagate.*.versioning` strategies are removed in favor of explicit version pins), and the plan page adds per-version variant propagation plus a persistent all-variants view — [#3166](https://github.com/useautumn/autumn/pull/3166), [#3167](https://github.com/useautumn/autumn/pull/3167), [#3168](https://github.com/useautumn/autumn/pull/3168)
* The balance edit sheet explains that manual edits are one-off adjustments that reset on the next cycle, with a tooltip pointing to lasting alternatives — [#3140](https://github.com/useautumn/autumn/pull/3140)
* `rewards:read` and `rewards:write` join the default OAuth resource scopes, so MCP and OAuth clients can list and create rewards; a Rewards row appears in the scope selector — [#3143](https://github.com/useautumn/autumn/pull/3143)
* Usage tracked just before a Stripe invoice, subscription, or checkout webhook no longer appears to revert: pending balance deductions are flushed to Postgres before the cached customer view is refreshed — [#3230](https://github.com/useautumn/autumn/pull/3230), [#3232](https://github.com/useautumn/autumn/pull/3232)
* Expired Stripe Checkout sessions now invalidate the cached customer, so plans attached with `enable_product_immediately` no longer linger as phantom active plans — [#3241](https://github.com/useautumn/autumn/pull/3241)
* Cancelling a plan pending on a checkout session clears the checkout reservation, so re-attaching opens a fresh session instead of returning an expired payment link — [#3238](https://github.com/useautumn/autumn/pull/3238)
* Custom-price checkouts no longer crash on completion, and `customer.products.updated` / `billing.updated` webhooks again include the activated paid plan after checkout — [#3225](https://github.com/useautumn/autumn/pull/3225), [#3214](https://github.com/useautumn/autumn/pull/3214)
* A RevenueCat renewal of a past-due cancelled product now clears the stale cancellation fields instead of reporting the live subscription as cancelled — [#3171](https://github.com/useautumn/autumn/pull/3171)
* Cancelling a RevenueCat-managed subscription from the dashboard with **No Billing Changes** no longer returns a 409; Autumn-only cancels bypass the external-provider guard — [#3208](https://github.com/useautumn/autumn/pull/3208)
* Current-billing-cycle analytics now use the exact stored cycle boundaries instead of treating the cycle as a rolling window — [#3179](https://github.com/useautumn/autumn/pull/3179)
* Concurrent lazy usage-window resets no longer stampede the same rows and time out check requests; each customer's roll is guarded by a lock — [#3187](https://github.com/useautumn/autumn/pull/3187)
* License plan transitions reset entitlement usage to the incoming grant unless carry-over is enabled, editing a linked license plan's items no longer fails with a foreign-key error, and [`plans.list`](/api-reference/plans/listPlans) includes license prices when classifying upgrades vs downgrades — [#3255](https://github.com/useautumn/autumn/pull/3255), [#3233](https://github.com/useautumn/autumn/pull/3233), [#3236](https://github.com/useautumn/autumn/pull/3236)
* Sequential seat quantity updates no longer double-count historical refunds when reconstructing prorated invoice credits — [#3256](https://github.com/useautumn/autumn/pull/3256)
* Editing one phase of a generated billing schedule no longer replaces or loses other phases, custom prices, or a requested first-phase start date — [#3203](https://github.com/useautumn/autumn/pull/3203), [#3211](https://github.com/useautumn/autumn/pull/3211)
* The attach review sheet no longer claims to be "pausing" the outgoing plan on plain upgrades with no trial configured — [#3206](https://github.com/useautumn/autumn/pull/3206)
* The customer page's Plans table grows with the selected page size instead of adding an inner scrollbar — [#3198](https://github.com/useautumn/autumn/pull/3198)
* Prepaid prices no longer incorrectly inherit a Stripe usage meter from a reused product-only price match — [#3146](https://github.com/useautumn/autumn/pull/3146)
* The customer page no longer shows the RevenueCat badge when a customer only has expired RevenueCat-backed products — [#3018](https://github.com/useautumn/autumn/pull/3018)
## Plan versions in the dashboard
The plan page now lets you work with [versions](/documentation/customers/versioning) directly. A version selector lists every version with its slug and marks the active one, **Promote to active** moves the pointer to an older version without editing content, and version slugs are editable under **More settings**. When a plan change mints a new version, the dialog asks for the new version's slug up front and surfaces slug collisions in the preview instead of failing on save.
## Rename plan IDs without breaking API calls
Renaming a plan's ID (e.g. `pro` → `pro-new`) now keeps the old ID as an alias, so existing API calls, request bodies, and Stripe checkout metadata that reference the old ID keep resolving. Responses always return the live ID. Renaming again replaces the previous alias, and the dashboard's plan change dialog explains which alias will stop working before you confirm.
## Stripe pass-through params on subscription updates
[`billing.update`](/api-reference/billing/billingUpdate) and [`billing.multi_update`](/api-reference/billing/multiUpdate) accept a new `subscription_params` object that is forwarded onto the underlying Stripe `subscriptions.update` or `subscriptions.cancel` call, with Autumn-owned keys winning any collisions. Multi-update also accepts `refund_last_payment` at the request root for cancel-immediately updates, applying the refund across every update in the call.
## Stripe Prices are reused across customers
When two customers on the same plan end up with identical pricing — including matching custom fixed, usage-based, and prepaid prices — Autumn now reuses the existing Stripe Price instead of minting a duplicate, keeping your Stripe catalog clean. Minted Stripe Prices are also named by kind (Base, Prepaid, Usage-based), and only genuine attach-time customizations get a `(custom)` suffix.
## Trials no longer require a card by default
New [free trials](/documentation/modelling-pricing/trials) default to `card_required: false`, and the card requirement is now visible where the trial is configured. A top-level `free_trial` on [`billing.attach`](/api-reference/billing/attach) is honoured instead of being silently dropped, and free plans no longer report `card_required: true` when signup never asks for a card.
## Default net terms for invoice-mode billing
Organizations billing via `send_invoice` can set a `default_net_terms_days` org setting that fills in `days_until_due` on generated invoices when neither the request nor the invoice template specifies net terms. Precedence is request `net_terms_days` → invoice template → org default → the unchanged 30-day fallback, and it applies across attach, multi-attach, updates, schedules, and plan migrations.
* Analytics usage charts now support pinned tooltips: click a bar to pin it, and when grouped by customer or entity, tooltip rows link straight to the customer or entity page — [#3083](https://github.com/useautumn/autumn/pull/3083)
* [`billing.multi_attach`](/api-reference/billing/multiAttach) supports `billing_cycle_anchor: "now"` to reset the billing cycle, with a matching toggle under More Options in the dashboard attach sheet — [#2986](https://github.com/useautumn/autumn/pull/2986), [#2987](https://github.com/useautumn/autumn/pull/2987)
* Unlimited usage is now surfaced in API responses instead of being hidden behind a null balance — [#2970](https://github.com/useautumn/autumn/pull/2970)
* The customer list's Balance filter and Features sort now default to the `usage` basis, and unlimited balances get consistent semantics per basis: usage counts real consumption on unlimited rows, while remaining/granted comparisons handle unlimited holders explicitly — [#3065](https://github.com/useautumn/autumn/pull/3065), [#3026](https://github.com/useautumn/autumn/pull/3026)
* The customer products Status filter is now a multi-select with a combined active + expired view — [#2957](https://github.com/useautumn/autumn/pull/2957)
* A product scheduled to cancel now offers **Cancel Immediately** and **Manage Cancellation** in its row actions, so you no longer have to uncancel first and cancel again — [#3134](https://github.com/useautumn/autumn/pull/3134), [#3135](https://github.com/useautumn/autumn/pull/3135)
* MCP OAuth now supports named sandboxes: the consent screen's environment picker lists them, and issued credentials stay bound to the selected sandbox across refreshes — [#3025](https://github.com/useautumn/autumn/pull/3025)
* The Verify Stripe sheet's shared-customer warning now links each colliding Autumn customer by name instead of listing plain IDs — [#2953](https://github.com/useautumn/autumn/pull/2953)
* `atmn push` now forwards `archived: true` from `autumn.config.ts`, so `atmn pull` → `atmn push` round-trips archived plans correctly — [#3009](https://github.com/useautumn/autumn/pull/3009)
* Renaming a plan's version slug in the dashboard no longer silently mints a new version; metadata-only saves now edit the existing version — [#3110](https://github.com/useautumn/autumn/pull/3110)
* [`billing.updated`](/api-reference/webhooks/billingUpdated) webhooks now carry `entity_id` when a scheduled downgrade on an entity-scoped plan takes effect, not just on the original cancel call — [#3062](https://github.com/useautumn/autumn/pull/3062)
* The analytics usage chart keeps idle periods on the x-axis, so a 30-day range with usage in only 5 days renders all 30 buckets — [#3032](https://github.com/useautumn/autumn/pull/3032)
* Cancelling at end of cycle with a scheduled downgrade now correctly attaches the free default plan — [#3027](https://github.com/useautumn/autumn/pull/3027)
* `proration_behavior: "none"` is treated as a no-op on new subscriptions instead of returning a 400 — [#2980](https://github.com/useautumn/autumn/pull/2980)
* Billing controls now persist when cleared from Plan Settings, and creating a control no longer fails when a lane was previously unset — [#3004](https://github.com/useautumn/autumn/pull/3004), [#3005](https://github.com/useautumn/autumn/pull/3005)
* Catalog updates no longer fail with a foreign-key error when expired customers still reference a plan's items — [#3095](https://github.com/useautumn/autumn/pull/3095)
* Plan grant changes during migrations only rewrite balances that match the original allowance, so customized grants are preserved instead of duplicated — [#2965](https://github.com/useautumn/autumn/pull/2965)
* Auto top-ups hold their billing lock for the full charge and extend queue visibility, closing a race that could double-charge on message redelivery — [#2962](https://github.com/useautumn/autumn/pull/2962)
* Legacy rollover caps of `max: 0` are treated as uncapped when saving a plan instead of failing validation — [#2955](https://github.com/useautumn/autumn/pull/2955)
* The per-unit selector in graduated pricing tier rows no longer collapses to an unreadable sliver — [#3099](https://github.com/useautumn/autumn/pull/3099)
* The Export customers sheet shows the correct customer count again — [#2967](https://github.com/useautumn/autumn/pull/2967)
## Deduction aggregations on events.aggregate
[`events.aggregate`](/api-reference/events/aggregateEvents) now accepts `aggregate_on: "deducted"` alongside a `customer_id` and returns a per-balance breakdown of what each tracked feature actually consumed from each balance. Existing usage totals are unchanged, `group_by` and `max_groups` still apply (overflow rolls up as `Other`), and the customer analytics view has a new toggle to chart the breakdown directly.
## UTC-anchored usage limits
Usage limits can now reset on the UTC calendar instead of the customer's billing cycle. Set `anchor: "utc"` on any limit (or flip **Anchor to UTC time** in the plan editor or customer usage-limit sheet) and the window uses calendar bounds, doesn't refill on plan changes, and takes precedence when two same-rate limits tie. Existing limits keep the `billing_cycle` behavior with no migration required.
## Expire plans during an attach
[`billing.attach`](/api-reference/billing/attach) accepts a new `remove_plan_ids` array so you can expire one or more active plans in the same call that adds a new one. Removals respect the attach's entity scope, run in a single reconciliation with Stripe, and can act as the carry-over source for usage and balances when there is no same-group predecessor. The attach sheet in the dashboard has a matching **Remove a product** picker next to **Add another product**, with inline greying for plans already being replaced or queued for removal.
## Choose payment methods on Autumn invoices
Organizations on invoice mode (`send_invoice`) can now pick which payment methods appear on the Stripe invoices Autumn generates. **Settings → Invoices → Payment methods** exposes a multi-select for card, bank transfer, ACH, SEPA, Bacs, Canadian pre-authorized debit, and Link. The selection is applied via `payment_settings.payment_method_types` on every invoice the subscription generates. Leaving the setting untouched preserves your Stripe account defaults exactly as before.
## Stripe sync verification in the dashboard
Customer pages now auto-run `billing.verify` in the background and surface a header warning icon only when drift is detected. Clicking it opens a **Verify Stripe** sheet with an **In sync / Warning / Mismatched** badge per subscription and a compact table of the exact fields that differ. The sheet also flags an account-level warning when more than one Autumn customer points at the same Stripe customer and lists the colliding IDs. You can also now clear a customer's Stripe ID by passing `null` or `""` through [`customers.update`](/api-reference/customers/updateCustomer).
* `rollovers[].granted` is now returned on balance responses across check, track, `trackTokens`, import, customer, and entity endpoints so you can see the original rolled-over amount before consumption — [#2671](https://github.com/useautumn/autumn/pull/2671)
* Customer expand now supports `invoice_previews`, returning preview line items and discounts inline — [#2671](https://github.com/useautumn/autumn/pull/2671)
* Create-schedule accepts `unscheduled_plans` (`preserve_add_ons` is deprecated and ignored) — [#2671](https://github.com/useautumn/autumn/pull/2671)
* Feature grants now accept `0` explicitly; only negative amounts are rejected, and boolean features skip allowance entirely — [#2671](https://github.com/useautumn/autumn/pull/2671)
* [`customers.list`](/api-reference/customers/listCustomers) now accepts `sort_order`, and the dashboard customers table exposes created-at sorting — [#2662](https://github.com/useautumn/autumn/pull/2662)
* Customer balance sheet adds a **Pooling** criteria filter so you can slice per-entity vs pooled balances — [#2810](https://github.com/useautumn/autumn/pull/2810)
* Flags now render as a plain section label when a customer has no catalog features, and the Flags/Full Catalog tabs only appear when there is catalog to switch to — [#2690](https://github.com/useautumn/autumn/pull/2690)
* Customer export menu and the created-date filter chip are re-aligned to shared list-action styling, with a clearer active-range label — [#2693](https://github.com/useautumn/autumn/pull/2693)
* Check requests are more resilient under load: the fail-open budget now counts middleware time, and slow primary-pool hydrations race a delayed backup read on the general pool so a single slow lookup no longer trips the timeout — [#2800](https://github.com/useautumn/autumn/pull/2800), [#2721](https://github.com/useautumn/autumn/pull/2721)
* Failed-check fallbacks now log an explicit reason (`route_timeout`, `org_rate_limit`, or `dependency_error`) so you can tell why a check failed open — [#2800](https://github.com/useautumn/autumn/pull/2800)
* SQS workers wait for Redis warmup and settle in-flight requests before shutdown, eliminating spurious `SQS batch accumulator is shutting down` rejections around deploys and recycles — [#2691](https://github.com/useautumn/autumn/pull/2691), [#2695](https://github.com/useautumn/autumn/pull/2695), [#2702](https://github.com/useautumn/autumn/pull/2702)
* Retained entitlements now reset their cycle anchor when a subscription update resets the billing cycle, and reinitialize usage from the final plan when `carry_over_usages.enabled` is `false`; scheduled cancellations are preserved — [#2804](https://github.com/useautumn/autumn/pull/2804)
* `additional_currencies` is now included on feature price items so multi-currency prices round-trip through types and comparators correctly — [#2799](https://github.com/useautumn/autumn/pull/2799)
* Customer balance cells no longer render `0 used` for empty entitlements or `+0 overage` for fully spent prepaid packs; only genuinely negative balances enter the used / overage label — [#2719](https://github.com/useautumn/autumn/pull/2719)
* `atmn` CLI login (1.1.20+) no longer fails with `invalid_scope` when requesting the new `rewards:read` / `rewards:write` scopes — [#2796](https://github.com/useautumn/autumn/pull/2796)
* Variant base plan links are preserved when copying between environments so pulled catalogs stay linked — [#2640](https://github.com/useautumn/autumn/pull/2640)
* `atmn pull` now preserves an explicit variant removal filter `intervalCount: 1` so the generated config round-trips cleanly through `atmn push` — [#2689](https://github.com/useautumn/autumn/pull/2689)
## Pooled balances
A single balance can now be shared across every entity on a customer. Toggle **Pooled balance** on any finite metered plan item and per-entity grants flow into one shared pool that every entity draws down from. Pools reset on the parent subscription's `invoice.created`, on lazy schedules, or never — matching the entitlement lifecycle you already picked — and rollovers carry over cleanly across plan changes and trials. Pooled entitlements show up under `pooled_customer_entitlements` in [`customers.get`](/api-reference/customers/getCustomer), and you can list every contributing entity through the new `pooled_balances.list_contributions` endpoint.
## Scoped multi-plan attach
[`billing.multi_attach`](/api-reference/billing/multiAttach) and [`billing.multi_attach.preview`](/api-reference/billing/previewMultiAttach) now support explicit scopes on each plan you send. Choose `inherited`, `customer`, or `per_entity` per plan to control who a plan attaches to across an entity tree, and Autumn plans the schedule so parent and entity-level plans stay consistent through a single billing action.
## Product-scoped license discounts
Coupons and discounts can now target specific licensed products, and Autumn keeps them applied through every subsequent update. Percent and fixed discounts stack in the same order as your preview, refunds and upgrades pull credits from the stored discounted invoice rows instead of recomputing them, and Stripe subscription updates preserve the original `percent_off` so your dashboard and invoices stay in sync.
## Reliable Stripe webhook processing
Load-bearing Stripe webhooks — `checkout.session.completed`, cycle `invoice.created`, `invoice.paid`, `customer.updated`, and non-Autumn subscription events — now acknowledge Stripe only after processing succeeds, so a failed webhook is automatically retried instead of being silently dropped. Any early-acked failures are also replayed through a durable queue, and Autumn-originated Stripe calls carry an idempotency key so we never process our own writes as inbound events.
## Fixed duplicate checkout subscriptions
A rare race where an attach could produce two active Stripe subscriptions is now closed. Checkout reservations live for the full session lifetime (matching Stripe's `expires_at`), same-parameter [`billing.attach`](/api-reference/billing/attach) retries return the pending Checkout URL instead of creating a new session, and `checkout.session.completed` now serializes with in-flight attaches under a shared billing lock. Repeated attaches with different parameters expire any unpaid session first, then proceed.
* License seat assignment is now idempotent — retrying a batch that already contains assigned entities returns success without consuming pool capacity — [#2414](https://github.com/useautumn/autumn/pull/2414)
* Negative balances now carry over into the new plan when `carry_over_balances` is enabled, so any prior overage reduces the new allowance instead of being dropped — [#2431](https://github.com/useautumn/autumn/pull/2431)
* Track events are now batched into a single SQS send per batch, cutting per-event overhead and improving throughput under bursty usage — [#2489](https://github.com/useautumn/autumn/pull/2489)
* Async Track processing can be enabled per organization from the admin dashboard, replacing the previous hardcoded allowlist — [#2375](https://github.com/useautumn/autumn/pull/2375)
* Auto top-up jobs now retry when they hit a billing lock instead of dropping the run — [#2416](https://github.com/useautumn/autumn/pull/2416)
* Stripe imports now recognize product aliases in your catalog mappings, so linked products keep their references across renames — [#2500](https://github.com/useautumn/autumn/pull/2500)
* Tiered price hydration is now consistent across attach, update, and preview flows — [#2500](https://github.com/useautumn/autumn/pull/2500)
* New `.well-known/oauth-protected-resource` endpoint improves OAuth discovery for MCP clients — [#2500](https://github.com/useautumn/autumn/pull/2500)
* Billing verification now separates identity, shape, and totals mismatches into `warn` vs `error` severities so real drift is easier to spot — [#2500](https://github.com/useautumn/autumn/pull/2500)
* Dashboard Edge Config admin now shows live per-config status (paused queues, ramp percentages, blocked orgs) at a glance — [#2406](https://github.com/useautumn/autumn/pull/2406)
* Entity usage is no longer double-counted when a customer has overlapping add-ons — entities already covered by an active product are excluded from add-on aggregation — [#2496](https://github.com/useautumn/autumn/pull/2496)
* MCP OAuth refresh now stays within the originally granted scopes and no longer forwards a `resource` parameter that some issuers reject — [#2501](https://github.com/useautumn/autumn/pull/2501)
* Unknown `.well-known/*` requests return `404` instead of the 401 session-auth error — [#2499](https://github.com/useautumn/autumn/pull/2499)
* Property-rollup completeness now checks event counts (not net sums), so gate-dropped groups are detected correctly — [#2491](https://github.com/useautumn/autumn/pull/2491)
* Stranded checkout reservations after out-of-order `invoice.paid` and `checkout.session.completed` webhooks are now released, ending sporadic 423 lock errors on the next attach — [#2433](https://github.com/useautumn/autumn/pull/2433)
* Partial SQS batch-delete failures now retry only the failed entries with bounded backoff, so successful jobs are no longer redelivered — [#2415](https://github.com/useautumn/autumn/pull/2415)
* Stripe writes now carry idempotency keys so transient retries can't accidentally create duplicate sessions or transfers — [#2500](https://github.com/useautumn/autumn/pull/2500)
* Batch balance resets warn at 30 minutes and give up at 45 to avoid indefinite stalls behind a wedged message — [#2416](https://github.com/useautumn/autumn/pull/2416)
## License plan customization & propagation
License plans are now fully customizable per parent. You can override items, prices, and included seat counts on individual license plans, and Autumn rebases those overrides automatically when the base license plan changes — Stripe items and subscription lifecycle stay in sync. [`plans.update`](/api-reference/plans/updatePlan) accepts a `licenses[].customize` block per parent, and responses now include the effective `customize` payload on each license link. Pair with the new `include_license_parents` on [`plans.preview_update`](/api-reference/plans/updatePlan) to see downstream impacts before saving.
## Overflow tracking on usage
[`track`](/api-reference/core/track), [`track_tokens`](/api-reference/core/trackTokens), and [`batchTrack`](/api-reference/core/batchTrack) now accept `overage_behavior: "overflow"`, deducting the full amount past zero and letting balances go negative. Usage-window caps are bypassed, but customer and entity spend limits still clamp — useful when you want to record real usage even when a customer has run out of included balance.
## Writable auto top-up purchase counter
You can now reset or set the runtime purchase counter for [auto top-ups](/documentation/modelling-pricing/auto-top-ups) directly through [`customers.update`](/api-reference/customers/updateCustomer). Pass `billing_controls.auto_topups[].purchase_limit.count` to nudge or reset a customer's purchase count without waiting for the interval to roll over. `count > limit` is rejected with a clean 400, and active windows are preserved.
## Automatic recovery for failed customer creation
Customer create and get-or-create requests that hit rate limits or transient database/Redis errors are now automatically queued and replayed in the background, with globally serialized concurrency and deterministic dedupe. Requests come back with their original semantics and Autumn records whether the replay created or fetched the customer — no more one-off failures during traffic spikes.
## License transitions & drop handling
Plan transitions that drop a license pool (e.g. Team → Pro) now release the affected seat assignments and restore pool capacity in a single atomic step, unblocking migrations that previously errored out. The Attach Product preview warns you when a transition will remove licenses and lists the entities that will be released. Assignments carried across matched successor pools stay intact.
* License catalog updates preview and apply cleanly across parent-plan versioning and in-place edits, preserving existing customer license definitions — [#2288](https://github.com/useautumn/autumn/pull/2288)
* Row-batched license transitions preserve quantities, billing state, and Stripe linkage across immediate and scheduled changes — [#2306](https://github.com/useautumn/autumn/pull/2306)
* Child license plan propagation now previews linked parent-plan impacts and supports explicit propagation targets — [#2295](https://github.com/useautumn/autumn/pull/2295)
* Auto top-up thresholds can now be negative, so you can trigger top-ups once a balance dips below zero — [#2354](https://github.com/useautumn/autumn/pull/2354)
* New Stripe customers imported via `stripe_id` on customer creation now pull in eligible subscriptions and schedules automatically — [#2308](https://github.com/useautumn/autumn/pull/2308)
* Customer dashboard plan filters now resolve in milliseconds instead of tens of seconds on large orgs — [#2362](https://github.com/useautumn/autumn/pull/2362)
* Create-schedule previews now show unavoidable immediate charges (initial subscription lines, automatic tax, invoice credits) so previews match the final invoice — [#2329](https://github.com/useautumn/autumn/pull/2329)
* Attach form plan-schedule preview now defaults to **immediate** when unset, matching the UI — [#2345](https://github.com/useautumn/autumn/pull/2345)
* Long checkout URLs in the dashboard truncate from the end with a proper ellipsis instead of clipping both sides — [#2344](https://github.com/useautumn/autumn/pull/2344)
* License assignments are now treated as active only when their pool link has an active parent, so dropped and matched pool transitions behave consistently — [#2353](https://github.com/useautumn/autumn/pull/2353)
* Same-batch customized license plan previews no longer crash on virtual catalog products (empty prices/entitlements) — [#2343](https://github.com/useautumn/autumn/pull/2343)
* Catalog sync tolerates partial product collections, missing entitlements, and missing prices without erroring — [#2317](https://github.com/useautumn/autumn/pull/2317), [#2319](https://github.com/useautumn/autumn/pull/2319), [#2322](https://github.com/useautumn/autumn/pull/2322), [#2324](https://github.com/useautumn/autumn/pull/2324)
* Versioned license schedules and matched plan versions are preserved through Stripe sync — [#2297](https://github.com/useautumn/autumn/pull/2297), [#2284](https://github.com/useautumn/autumn/pull/2284)
* OAuth organization list deduplicates when a user has multiple memberships in the same org — [#2346](https://github.com/useautumn/autumn/pull/2346)
* MCP `getCurrentOrganization` schema now matches the `organization/me` API response, adding `id` and tolerating a missing `user` — [#2140](https://github.com/useautumn/autumn/pull/2140)
* Rate limits on establish routes now return a standard `429` (no `Retry-After`); check and track routes still fail open — [#2384](https://github.com/useautumn/autumn/pull/2384)
* Concurrent migrations no longer duplicate customer plans — [#2282](https://github.com/useautumn/autumn/pull/2282)
* Versioned license pricing renders correctly in the plan dashboard — [#2291](https://github.com/useautumn/autumn/pull/2291)
## Multi-currency pricing and billing
Plans can now be priced in **multiple currencies** end-to-end. Add `base_currency` and `additional_currencies` to any fixed, tiered, or usage-based price, and customers get billed in their resolved currency across checkout, invoices, top-ups, refunds, upgrades, and previews. Customers pick up a `currency` field that locks on their first paid attach — pass `currency` on [`billing.attach`](/api-reference/billing/attach) or [`billing.multi_attach`](/api-reference/billing/multiAttach) to choose, and attaches in a different currency return a clean `currency_mismatch` 400. Reach out to enable the `multi_currency` org flag.
## Licenses
The full **licenses** stack is live: plans can offer other plans as assignable seats with `included` free counts, prepaid seat quantities, and per-customer overrides. New endpoints — [`licenses.attach`](/api-reference/licenses/attachLicense), [`licenses.release`](/api-reference/licenses/releaseLicense), [`licenses.list`](/api-reference/licenses/listLicenses), and [`licenses.list_assignments`](/api-reference/licenses/listLicenseAssignments) — let you provision, release, and inspect seats on entities, with balance tracking and dashboard management for the whole lifecycle. Priced licenses require the license plan to be attached to the customer first (via [`billing.attach`](/api-reference/billing/attach)); free licenses assign directly.
## List invoices endpoint
Fetch a customer's invoices programmatically with the new [`invoices.list`](/api-reference/invoices/listInvoices) endpoint — the same data the dashboard uses, now available on the API for building portals, reconciliation flows, and audit tooling.
## Pay down overages on one-off add-ons
One-off prepaid add-ons now **pay down existing overages** at attach time, so a customer who's already over their included balance immediately settles the outstanding usage on their next invoice instead of waiting for the cycle to close. Behavior is gated by the price's `persist_free_overage` flag for finer control.
## Back-sync carry usage on Stripe imports
When you import an existing Stripe subscription that's mid-cycle on a usage feature, Autumn now **carries the already-consumed usage** into the new customer product so balances line up with what the customer has actually used, instead of resetting on import.
## Invoice-mode start for usage-in-arrears
Subscriptions with usage-in-arrears pricing can now be started directly in **invoice mode** — useful for large customers you're billing outside checkout — without needing a card on file up front.
## Attach-time currency selection
The [`billing.attach`](/api-reference/billing/attach) flow now accepts a `currency` parameter, and dashboard attach/preview sheets show amounts in the customer's currency. Pair with multi-currency plans to sell in EUR, GBP, or any additional currency you configure.
* Rollovers now carry to the best-candidate bucket on plan updates, so leftover balance doesn't disappear when you switch a customer between plans — [#2266](https://github.com/useautumn/autumn/pull/2266)
* Multi-currency plan updates work through preview, save, and migration flows — [#2236](https://github.com/useautumn/autumn/pull/2236)
* Multi-currency Stripe sync now imports historical subscriptions in their original currency — [#2227](https://github.com/useautumn/autumn/pull/2227)
* Attach schedule now always defaults to **immediate**, so plans go live on save unless you explicitly schedule them — [#2232](https://github.com/useautumn/autumn/pull/2232)
* Analytics dashboard refetches on window focus, so numbers stay fresh when you tab back in — [#2241](https://github.com/useautumn/autumn/pull/2241)
* `billing.updated` webhooks now fire after the Stripe customer ID is persisted, so downstream consumers always see the linked Stripe record — [#2267](https://github.com/useautumn/autumn/pull/2267)
* Plan **variants** now stamp their own `previous_price` history, so each variant keeps an independent price trail — [#2238](https://github.com/useautumn/autumn/pull/2238)
* Consent screen shows the Autumn brand logo in the org selector — [#2249](https://github.com/useautumn/autumn/pull/2249)
* Faster reset cron and invoice cron for large workspaces — [#2222](https://github.com/useautumn/autumn/pull/2222), [#2257](https://github.com/useautumn/autumn/pull/2257)
* Coupon **scope** updates now apply cleanly to existing subscriptions instead of only new ones — [#2260](https://github.com/useautumn/autumn/pull/2260)
* Catalog updates that reference customers across plan versions no longer error — [#2244](https://github.com/useautumn/autumn/pull/2244)
* Non-consumable prepaid quantities update correctly on plan changes — [#2220](https://github.com/useautumn/autumn/pull/2220)
* Dashboard no longer shows false "unsaved changes" errors when saving plans — [#2276](https://github.com/useautumn/autumn/pull/2276)
* Entity creation is serialized per customer, avoiding duplicate rows under concurrent attaches — [#2242](https://github.com/useautumn/autumn/pull/2242)
* Pending invoice cleanup cron backs off gracefully instead of retrying tight — [#2239](https://github.com/useautumn/autumn/pull/2239)
## Multi-update billing endpoint
Cancel or uncancel multiple plans for a customer in a **single atomic request** with the new [`billing.multi_update`](/api-reference/billing/multiUpdate) endpoint. Updates are grouped per Stripe subscription and executed as one merged plan, so proration and invoicing land as a single combined result. Preview it first with [`billing.preview_multi_update`](/api-reference/billing/previewMultiUpdate) to see per-subscription and combined totals.
## Plan-inherited billing controls on customer reads
API v2.3 customer and entity reads now include **plan-inherited** [billing controls](/documentation/customers/billing-controls) — `usage_limits`, `spend_limits`, `overage_allowed`, `auto_topups`, and `usage_alerts` — alongside customer-level overrides, with each entry tagged `source: "customer" | "plan"`. Inherited usage limits also return the current-window usage. Older clients keep the previous response shape.
## Eve: new default AI agent for Slack and dashboard chat
Eve is now the default agent harness for Slack and the dashboard streaming chat, with in-thread approvals, follow-up questions, richer status updates, and interactive **catalog decision cards** for versioning and variant changes. Rejecting an approval in Slack or the web app now also clears the underlying suspension cleanly.
## Auto top-up failure webhook
Subscribe to the new [`billing.auto_topup.failed`](/api-reference/webhooks/billingAutoTopupFailed) webhook to react to auto top-up charges that don't go through — pause features, notify the customer, or fall back to manual top-up.
## Expiring free recurring balances
Free recurring balances can now carry an **`expires_at`** timestamp, and the [`balances.update`](/api-reference/balances/updateBalance) endpoint accepts `expires_at` so you can extend or shorten grants after the fact. The dashboard has matching controls in the balance sheet.
## Licenses (early)
Foundational support for **licenses** has landed: a new licenses model, API schema, and a `licenses` field on the [`plans.list`](/api-reference/plans/listPlans) response. Reach out if you'd like to try it early.
## RevenueCat: email and fingerprint identifiers
The [RevenueCat integration](/documentation/external-providers/revenuecat) now recognizes `autumn_customer_email` and `autumn_customer_fingerprint` subscriber attributes on incoming webhooks, so you can match RevenueCat purchases to Autumn customers by email or fingerprint instead of only by ID.
## Any-shape customer import
[`billing.import`](/api-reference/billing/import) can now ingest customers from **any billing processor in any shape** — the processor and per-item `billable.processor` are configurable, and identity updates honor `dry_run`. Email-only `customer_data` payloads are validated before import runs.
## Property filters on usage limits
[Usage limits](/documentation/modelling-pricing/spend-limits) now support **property filters**, so a single limit can target a subset of events (for example, only requests to a specific model or region) instead of the whole feature. `balances.limit_reached` also now fires for plan-level and percentage-based spend and usage limits.
## Copyable sandboxes
Spin up a new sandbox as a **copy** of an existing one, so you can branch off staging or QA without rebuilding your catalog from scratch.
## billing.updated on manual sync
Manual sync operations now emit the [`billing.updated`](/api-reference/webhooks/billingUpdated) webhook, so downstream consumers stay in sync when you re-pull state from Stripe by hand.
* `set_usage` now composes with usage windows: setting a balance no longer errors when a feature has an active window, and window caps still hold after the reset — [#2205](https://github.com/useautumn/autumn/pull/2205)
* Auto top-up expand path returns `purchase_limit` for plan-inherited entries too — [#2205](https://github.com/useautumn/autumn/pull/2205)
* Refund-last-payment is now exposed on the API — [#2179](https://github.com/useautumn/autumn/pull/2179)
* Slack app: additional options for matching a Slack user to an Autumn user — [#2100](https://github.com/useautumn/autumn/pull/2100)
* Archived plans now include an `archived` flag when pulled via the CLI — [#2152](https://github.com/useautumn/autumn/pull/2152)
* Webhook tags: customer and entity IDs are sanitized to the Svix charset so deliveries don't fail on unusual characters — [#2150](https://github.com/useautumn/autumn/pull/2150)
* Free first schedule phase is now supported in plan schedules — [#2137](https://github.com/useautumn/autumn/pull/2137)
* Refreshed checkout favicon — [#2162](https://github.com/useautumn/autumn/pull/2162), [#2161](https://github.com/useautumn/autumn/pull/2161)
* Cleaner subscription sheet tooltips, coupon error messages, and plan ID chip in mappings — [#2157](https://github.com/useautumn/autumn/pull/2157)
* Renewal edge case that could mis-schedule the next cycle is fixed — [#2200](https://github.com/useautumn/autumn/pull/2200)
* Manual `tax_rate_id` is now applied to one-time and deferred charges, not just recurring items — [#2204](https://github.com/useautumn/autumn/pull/2204)
* `check` with a lock correctly returns `allowed: false` when the customer has no entitlement — [#2174](https://github.com/useautumn/autumn/pull/2174)
* Promo minimum validation is now consistent across all billing flows — [#2168](https://github.com/useautumn/autumn/pull/2168)
* ACH processing invoices are handled correctly through the past-due flow — [#2167](https://github.com/useautumn/autumn/pull/2167), [#2128](https://github.com/useautumn/autumn/pull/2128), [#2053](https://github.com/useautumn/autumn/pull/2053)
* Skip overage billing when no overage is due, avoiding empty invoice items — [#2190](https://github.com/useautumn/autumn/pull/2190), [#2182](https://github.com/useautumn/autumn/pull/2182)
* Cardinality gate no longer false-fires on legitimate usage — [#2184](https://github.com/useautumn/autumn/pull/2184)
* Scheduled customer products now resync `starts_at` when a Stripe schedule is updated — [#2177](https://github.com/useautumn/autumn/pull/2177)
* Filter button on the customers page is visible even when a customer only has expired products — [#2165](https://github.com/useautumn/autumn/pull/2165)
* Variant Stripe product renames now propagate correctly — [#2149](https://github.com/useautumn/autumn/pull/2149)
* Product cron trial expiry now paginates correctly at scale — [#2144](https://github.com/useautumn/autumn/pull/2144)
* Schedule phase billing anchors are reset when the phase changes; Stripe anchor reset day is clamped to valid values — [#2133](https://github.com/useautumn/autumn/pull/2133), [#2115](https://github.com/useautumn/autumn/pull/2115)
* Discount upgrades apply cleanly to the upgraded plan — [#1815](https://github.com/useautumn/autumn/pull/1815)
* `billing.import` correctly updates `customer_data` and filters one-off / usage-based balances — [#2154](https://github.com/useautumn/autumn/pull/2154), [#2156](https://github.com/useautumn/autumn/pull/2156)
* Assorted usage-window, coupon, and sync-back fixes — [#2159](https://github.com/useautumn/autumn/pull/2159), [#2186](https://github.com/useautumn/autumn/pull/2186)
## Multiple sandbox environments per org
Organizations can now spin up **multiple sandboxes** alongside production — each with its own API keys, teams, color, and icon — so you can isolate staging, QA, demo, and per-engineer environments without juggling accounts. Provision, switch, edit, and tear down sandboxes directly from the dashboard.
## Per-customer JWT credentials
Issue and rotate **per-customer JWT credentials** for the frontend SDK. State is now persisted in Postgres, so credentials survive restarts and can be managed cleanly per customer.
## Percentage-based spend limits
[Spend limits](/documentation/modelling-pricing/spend-limits) now support a `usage_percentage` mode, letting you cap overage as a percentage of included usage instead of an absolute number — useful for plans where the included quota changes between tiers.
## Plan metadata
Attach arbitrary **metadata to plans** and read it back through the API. Use it to tag plans with internal flags, feature gates, or marketing copy without forking your pricing model.
## List rewards endpoint
New [rewards endpoint](/api-reference/rewards/redeemRewardCode) returns both coupons and feature grants in a single paginated response, making it easier to render available rewards in your own UI.
## Track events with custom timestamps
The `track` endpoint now accepts an explicit `timestamp` field, so you can backfill events or record usage that happened earlier without losing chronological accuracy.
## Plan billing controls
Custom plans get a refreshed **billing controls** panel — clearer toggles, keyboard-focusable tooltips, simplified auto top-up resolution, and improved copy throughout. See [custom plans](/documentation/customers/custom-plans).
## Dual-auth Stripe keys
You can now connect Stripe using **either** OAuth or a restricted API key, and switch between them per organization. The Stripe Keys UI has been redesigned around the new dual-auth flow, with cleaner copy and a smoother delete experience.
* Add interval filter to the customers list page — [#2038](https://github.com/useautumn/autumn/pull/2038)
* "Create more" mode in the create-entity dialog for bulk entity setup — [#1988](https://github.com/useautumn/autumn/pull/1988)
* Plan editor: cleaner update logic and feature-creation flow — [#2035](https://github.com/useautumn/autumn/pull/2035)
* Net payment terms UI refreshed inside the invoice settings accordion — [#2034](https://github.com/useautumn/autumn/pull/2034)
* Customizable buttons in transactional emails — [#1991](https://github.com/useautumn/autumn/pull/1991)
* Customer IDs now accept colons for namespaced identifiers — [#1995](https://github.com/useautumn/autumn/pull/1995)
* Mobile dashboard cleanup, including card-style tables on small screens — [#2013](https://github.com/useautumn/autumn/pull/2013)
* [RevenueCat import](/documentation/external-providers/revenuecat): paginated product list and raw-mapping escape hatch for custom field mapping — [#2040](https://github.com/useautumn/autumn/pull/2040)
* MCP OAuth now grants Leaf scopes when only OIDC scopes are requested — [#2012](https://github.com/useautumn/autumn/pull/2012), [#2023](https://github.com/useautumn/autumn/pull/2023)
* Website content negotiation: canonical URLs serve markdown to clients that ask for it — [#2004](https://github.com/useautumn/autumn/pull/2004), [#2007](https://github.com/useautumn/autumn/pull/2007), [#2009](https://github.com/useautumn/autumn/pull/2009)
* Cleaner Stripe connect dialog and improved Stripe-related copy across the dashboard — [#2020](https://github.com/useautumn/autumn/pull/2020), [#2047](https://github.com/useautumn/autumn/pull/2047)
* Customer portal now has rate limiting to protect against abuse — [#2033](https://github.com/useautumn/autumn/pull/2033)
* Auto top-ups now charge the most recently attached plan's one-off price — [#2049](https://github.com/useautumn/autumn/pull/2049)
* Event table filtering corrected so filters apply to the right columns — [#2005](https://github.com/useautumn/autumn/pull/2005)
* Long event values no longer overflow the events table — [#2048](https://github.com/useautumn/autumn/pull/2048)
* Trialing customers downgrading to Free are correctly anchored to trial end — [#2000](https://github.com/useautumn/autumn/pull/2000)
* Sync no longer adds phantom allowance for imported prepaid Stripe items, and carries prepaid usage correctly when expiring a plan — [#1978](https://github.com/useautumn/autumn/pull/1978)
* Hourly rollovers now enforce the configured max cap on the reset cron — [#2022](https://github.com/useautumn/autumn/pull/2022)
* Rewards: reject duplicate reward IDs and promo codes, and clean up promos on delete — [#2031](https://github.com/useautumn/autumn/pull/2031)
* Event ranking window aligned with the chart for accurate top-events lists — [#2003](https://github.com/useautumn/autumn/pull/2003)
* Separate billing intervals render correctly in the plan editor — [#2001](https://github.com/useautumn/autumn/pull/2001), [#2042](https://github.com/useautumn/autumn/pull/2042), [#2043](https://github.com/useautumn/autumn/pull/2043)
* Prevent horizontal overscroll on the marketing site — [#2019](https://github.com/useautumn/autumn/pull/2019)
* MCP and Leaf auth edge cases resolved — [#2026](https://github.com/useautumn/autumn/pull/2026)
## Autumn Lakehouse
Stream every event, balance change, and invoice straight into your own data warehouse via the new **Autumn Lakehouse**. Connect once and query Autumn data with the SQL engine of your choice — Snowflake, BigQuery, DuckDB, Athena, Spark, or anything else that speaks Apache Iceberg.
See the [Lakehouse overview](/documentation/lakehouse/overview) and [connecting guide](/documentation/lakehouse/connecting) to get started.
## Instant customer products table
The customer detail page now renders its products table immediately, with the rest of the list paginated in the background. Loading a customer with hundreds of products is no longer a wait.
## Weekly analytics granularity
Analytics now supports a **weekly** bin size, and granularity options are tailored per time range (no more greyed-out choices). The granularity picker has moved into the time-period dropdown for fewer clicks.
## Plan version migrations: filter compiler & migrate dialog
Plan version migrations get a new **filter compiler** for targeting exactly the customers you want, a refreshed migrate dialog, and clearer visibility into billing changes before you commit. See [custom plans](/documentation/customers/custom-plans).
## Rewards: boolean grants & first-time conditions
Rewards can now grant **boolean features** (e.g. unlock an add-on as a perk) and can be gated to a customer's **first-time** purchase only. Useful for launch promos and onboarding incentives.
## OpenRouter support in the AI gateway
The Autumn [AI gateway](/documentation/external-providers/openrouter) now supports OpenRouter as a provider, so you can meter and bill OpenRouter usage the same way as direct OpenAI, Anthropic, and others.
* New `carry_over_usages` option on [`billing.update`](/api-reference/billing/billingUpdate) to preserve usage across plan changes — [#1974](https://github.com/useautumn/autumn/pull/1974)
* New `next_reset_at` parameter on [create balance](/api-reference/balances/createBalance) for scheduling the first reset — [#1950](https://github.com/useautumn/autumn/pull/1950)
* Long-lived Stripe checkout sessions so links stay valid for longer — [#1976](https://github.com/useautumn/autumn/pull/1976)
* Consolidated customer header actions, entity-scoped views, and direct Stripe Connect links from the customer page — [#1964](https://github.com/useautumn/autumn/pull/1964)
* Separate billing intervals per price component — [#1961](https://github.com/useautumn/autumn/pull/1961)
* Discounts now support a max-redemptions cap — [#1939](https://github.com/useautumn/autumn/pull/1939)
* Past-due cancellations void the open invoice immediately — [#1948](https://github.com/useautumn/autumn/pull/1948)
* Option to ignore past-due state and preserve the subscription — [#1963](https://github.com/useautumn/autumn/pull/1963)
* Clearer error messages across the dashboard and API — [#1943](https://github.com/useautumn/autumn/pull/1943)
* Refreshed reward selectors and coupon update confirmation — [#1928](https://github.com/useautumn/autumn/pull/1928)
* Org logos now upload to S3 with reliable hosting — [#1225](https://github.com/useautumn/autumn/pull/1225)
* Custom buttons in the dashboard — [#1987](https://github.com/useautumn/autumn/pull/1987)
* AI credit systems are now treated as generic credit systems in the plan editor — [#1903](https://github.com/useautumn/autumn/pull/1903)
* Patch migrations no longer skip custom products — [#1953](https://github.com/useautumn/autumn/pull/1953)
* Multi-entity granted amounts now display correctly in balance sub-rows — [#1947](https://github.com/useautumn/autumn/pull/1947)
* Free-trial dedup is now scoped per entity so each entity gets its own trial — [#1956](https://github.com/useautumn/autumn/pull/1956)
* `billing.updated` webhook now fires on trial-to-paid conversion — [#1972](https://github.com/useautumn/autumn/pull/1972)
* Tax and discounts now render correctly in [attach preview](/api-reference/billing/previewAttach) — [#1944](https://github.com/useautumn/autumn/pull/1944)
* [`createSchedule`](/api-reference/billing/createSchedule) phases now snap to the cycle boundary — [#1975](https://github.com/useautumn/autumn/pull/1975)
* Checkout page no longer renders blank on certain React versions — [#1937](https://github.com/useautumn/autumn/pull/1937)
* Usage limits now respect the AI credit dimension — [#1912](https://github.com/useautumn/autumn/pull/1912)
* Onboarding fee no longer double-charges in edge cases — [#1946](https://github.com/useautumn/autumn/pull/1946)
* Environment selection and org switching in the dashboard — [#1952](https://github.com/useautumn/autumn/pull/1952), [#1970](https://github.com/useautumn/autumn/pull/1970)
* Copy entity ID and allow duplicate plans in the sync editor — [#1957](https://github.com/useautumn/autumn/pull/1957)
* Sync expire no longer fails on certain customer states — [#1967](https://github.com/useautumn/autumn/pull/1967)
* Batch operations are now idempotent — [#1981](https://github.com/useautumn/autumn/pull/1981)
* Slack admin and dashboard gate fixes — [#1986](https://github.com/useautumn/autumn/pull/1986), [#1984](https://github.com/useautumn/autumn/pull/1984)
* CLI auth and Claude OAuth flows — [#1926](https://github.com/useautumn/autumn/pull/1926), [#1925](https://github.com/useautumn/autumn/pull/1925)
* `atmn` CLI now exits with a non-zero code on interactive push/pull errors — [#1927](https://github.com/useautumn/autumn/pull/1927)
* Copy product API call no longer fires with missing required fields — [#1585](https://github.com/useautumn/autumn/pull/1585)
* Keyboard shortcut and scroll fixes in the dashboard — [#1915](https://github.com/useautumn/autumn/pull/1915), [#1942](https://github.com/useautumn/autumn/pull/1942)
## Autumn MCP server
Autumn now ships an official **Model Context Protocol (MCP) server**, so AI assistants like Claude Desktop and Cursor can read and act on your Autumn data directly. The server is generated against the public API and respects your existing API key scopes (`customers:read`, `plans:read`, `billing:read`, `billing:write`) — no new permission model to learn.
Install it as a Claude Desktop extension or wire it into Cursor with a single deeplink. Use it to look up customers, inspect plans, preview attaches, and run billing updates from your assistant.
## Org-level usage alerts
Usage alerts can now be configured **once at the org level** and applied across every customer, instead of being attached plan by plan. Set a threshold and channel from settings, and Autumn fires alerts whenever any customer crosses the bar. The [`balances.usage_alert.triggered` webhook](/api-reference/webhooks/balancesUsageAlertTriggered) fires for both per-plan and org-level alerts.
## Vercel Marketplace: invoice mode and resource logs
The Vercel integration now supports **invoice-mode billing** end to end and surfaces **per-resource logs** in the dashboard, so you can debug a Vercel customer's provisioning, auto top-ups, and invoice flow without leaving Autumn. The frontend was rebuilt around the new resource model, with fallbacks for identity edge cases.
See the [Vercel Marketplace guide](/documentation/external-providers/vercel-marketplace).
* Official Autumn MCP server for Claude Desktop, Cursor, and other MCP clients — [#1715](https://github.com/useautumn/autumn/pull/1715), [#1740](https://github.com/useautumn/autumn/pull/1740), [#1741](https://github.com/useautumn/autumn/pull/1741)
* Org-level usage alerts with shared thresholds across customers — [#1707](https://github.com/useautumn/autumn/pull/1707)
* Vercel Marketplace invoice mode, resource logs, and refreshed frontend — [#1711](https://github.com/useautumn/autumn/pull/1711)
* Preflight tax-address check before charging customers in taxable regions — [#1699](https://github.com/useautumn/autumn/pull/1699)
* Automatically void uncollectible Stripe invoices instead of leaving them open — [#1732](https://github.com/useautumn/autumn/pull/1732)
* New plan-version filters for [custom-plan migrations](/documentation/customers/custom-plans) — [#1718](https://github.com/useautumn/autumn/pull/1718)
* Faster customer detail loads and smoother large entity lists — [#1712](https://github.com/useautumn/autumn/pull/1712)
* Customer list filter by entity ID — [#1688](https://github.com/useautumn/autumn/pull/1688)
* Refreshed dashboard theme and appearance controls — [#1679](https://github.com/useautumn/autumn/pull/1679)
* Optimised product counts in the customer table — [#1690](https://github.com/useautumn/autumn/pull/1690)
* Mobile fixes for the customer list view — [#1689](https://github.com/useautumn/autumn/pull/1689)
* Stripe checkout no longer drops carry-over balances on plan changes — [#1708](https://github.com/useautumn/autumn/pull/1708)
* Trial grants are now excluded from reward eligibility — [#1730](https://github.com/useautumn/autumn/pull/1730)
* RevenueCat sync no longer fails with "entities not found" — [#1729](https://github.com/useautumn/autumn/pull/1729)
* Tax IDs now render correctly in the attach preview — [#1728](https://github.com/useautumn/autumn/pull/1728)
* Invalid email addresses are now rejected with a clearer error — [#1722](https://github.com/useautumn/autumn/pull/1722)
* Sandbox usage alerts now respect their configured threshold — [#1706](https://github.com/useautumn/autumn/pull/1706)
* Proration toggle now shows even when the customer has a past trial — [#1704](https://github.com/useautumn/autumn/pull/1704)
* One-off prepaid items upgrade correctly without double carry-over — [#1676](https://github.com/useautumn/autumn/pull/1676), [#1695](https://github.com/useautumn/autumn/pull/1695)
* Subscription metadata is preserved through checkout — [#1719](https://github.com/useautumn/autumn/pull/1719)
* Price dropdown no longer loses its selected value when reopened — [#1720](https://github.com/useautumn/autumn/pull/1720)
* Vercel auto top-ups no longer fail to process the resulting invoice — multiple fixes ([#1725](https://github.com/useautumn/autumn/pull/1725))
## Batch track and async track
Two new ways to record usage when you don't need an immediate balance read:
* [`POST /v1/balances.batch_track`](/api-reference/core/batchTrack) — enqueue up to **1000 usage events** in one request. Returns 202 immediately; balances are deducted by background workers.
* **`async: true`** on the existing [`POST /v1/balances.track`](/api-reference/core/track) — same fire-and-forget shape for single-event callers that want the speed without switching to the batch endpoint.
Both paths are intended for high-volume metering (event logging, per-action usage counters) where you'd previously be limited by the synchronous deduction's HTTP round-trip. Partial enqueue failures are logged server-side and do NOT surface as errors to the client — see the [batch track reference](/api-reference/core/batchTrack#partial-failure-semantics) for the trade-off.
## `billing.updated` webhook
A new **`billing.updated`** webhook fires whenever a customer's plans change — attaches, renewals, schedule activations, trial conversions, plan updates, and expirations all flow through a single event. The payload includes the customer, optional entity, and an array of `plan_changes` describing what was activated, scheduled, updated, or expired, with previous-state diffs.
Use it to drive provisioning, lifecycle emails, CRM sync, and revenue reporting from one webhook instead of stitching together multiple events.
See the [`billing.updated` webhook reference](/api-reference/webhooks/billingUpdated).
## Cursor-based pagination and list endpoints (API v2.3)
The API is now at **v2.3**, introducing cursor-based pagination across list endpoints. Two new endpoints ship with it:
* [`POST /v1/entities.list`](/api-reference/entities/listEntities) — list a customer's entities with filters and cursor pagination.
* [`POST /v1/events.list`](/api-reference/events/listEvents) — paginate raw event history for a customer or feature.
Cursor pagination replaces offset-based paging on heavy endpoints, giving stable results even while data changes between pages. Pass `start_cursor` to continue from a previous page.
## Manual auto top-ups from the dashboard
You can now trigger an auto top-up for a customer directly from the dashboard, without waiting for the balance to cross the configured threshold. Useful for support flows, manual credit grants, or testing top-up wiring end to end.
See the [auto top-ups guide](/documentation/modelling-pricing/auto-top-ups).
## Passkey sign-in for the dashboard
Dashboard accounts now support **passkeys (WebAuthn)**. Register a passkey from your account settings to sign in with Face ID, Touch ID, Windows Hello, or a hardware key — no password required. Sign-in autofill is enabled so browsers can prompt for a passkey on the login screen.
## Vercel resource pre-provisioning
For Vercel Marketplace installs, Autumn now provisions the customer product the moment a resource is created, using a Stripe preauth instead of waiting for the first invoice. New Vercel customers land in your dashboard with their plan attached and entitlements ready immediately.
See the [Vercel Marketplace guide](/documentation/external-providers/vercel-marketplace).
## `plan_id` in analytics
Analytics queries now group and filter by `plan_id`, so revenue, usage, and event charts can be sliced per plan. Plan selection in the dashboard analytics views drives the new dimension end to end.
## Customer API logs workbench
The dashboard's customer detail view now includes a **workbench panel** showing recent API requests for that customer — endpoint, status, latency, and payload — so you can debug integrations without leaving the customer.
## Schedule editor: copy from previous phase
When customizing a scheduled phase, you can now click **Copy from previous phase** to seed the product selector with the prior phase's items, then adjust from there. Faster than rebuilding a multi-item phase from scratch.
## Trial `on_end` behaviour for attach
`billing.attach` accepts a new option to control what happens when a trial ends — convert to the paid plan, expire, or hand off to another product. The setting respects entity scoping so trials on one entity no longer disrupt others on the same customer.
See the [attach API reference](/api-reference/billing/attach).
* `billing.updated` webhook with unified `plan_changes` payload — [#1637](https://github.com/useautumn/autumn/pull/1637)
* API v2.3 with cursor-based pagination — [#1596](https://github.com/useautumn/autumn/pull/1596)
* `POST /v1/entities.list` endpoint — [#1505](https://github.com/useautumn/autumn/pull/1505), [#1513](https://github.com/useautumn/autumn/pull/1513)
* Paginated `POST /v1/events.list` endpoint — [#1596](https://github.com/useautumn/autumn/pull/1596)
* Manual auto top-up trigger in dashboard — [#1532](https://github.com/useautumn/autumn/pull/1532)
* Passkey (WebAuthn) sign-in and settings UI — [#1587](https://github.com/useautumn/autumn/pull/1587)
* Vercel resource pre-provisioning with Stripe preauth — [#1578](https://github.com/useautumn/autumn/pull/1578)
* `plan_id` dimension in analytics charts and tables — [#1568](https://github.com/useautumn/autumn/pull/1568), [#1613](https://github.com/useautumn/autumn/pull/1613)
* Customer API logs workbench panel — [#1525](https://github.com/useautumn/autumn/pull/1525)
* "Copy from previous phase" button in the schedule editor — [#1556](https://github.com/useautumn/autumn/pull/1556)
* Trial `on_end` option on `billing.attach`, with entity-aware behaviour — [#1554](https://github.com/useautumn/autumn/pull/1554), [#1581](https://github.com/useautumn/autumn/pull/1581)
* Live normalisation of expired auto top-up purchase-limit windows — [#1520](https://github.com/useautumn/autumn/pull/1520)
* Command bar favourites for impersonating frequent orgs and users — [#1597](https://github.com/useautumn/autumn/pull/1597)
* Settings page redesign with clearer navigation — [#1555](https://github.com/useautumn/autumn/pull/1555)
* Dashboard analytics chart and table polish — [#1599](https://github.com/useautumn/autumn/pull/1599), [#1613](https://github.com/useautumn/autumn/pull/1613)
* Stripe webhook race condition that could double-process events — [#1620](https://github.com/useautumn/autumn/pull/1620)
* Checkout session race condition under high concurrency — [#1548](https://github.com/useautumn/autumn/pull/1548)
* Attach now respects `tax_rate_id` overrides — [#1641](https://github.com/useautumn/autumn/pull/1641)
* Attach correctly handles no-op billing changes — [#1586](https://github.com/useautumn/autumn/pull/1586)
* Schedule sync no longer produces empty phases or duplicate items — [#1501](https://github.com/useautumn/autumn/pull/1501), [#1574](https://github.com/useautumn/autumn/pull/1574), [#1575](https://github.com/useautumn/autumn/pull/1575)
* Schedule customize flow now correctly handles removed base prices on free plans — [#1556](https://github.com/useautumn/autumn/pull/1556)
* Entity sync edge cases and item-log alignment fixed — [#1607](https://github.com/useautumn/autumn/pull/1607), [#1614](https://github.com/useautumn/autumn/pull/1614)
* Custom item delete and ghost item issues in the plan editor — [#1517](https://github.com/useautumn/autumn/pull/1517), [#1628](https://github.com/useautumn/autumn/pull/1628), [#1629](https://github.com/useautumn/autumn/pull/1629)
* Cancel flow now handles plans with a future `starts_at` — [#1507](https://github.com/useautumn/autumn/pull/1507)
* Revert trial issue when reversing a recent attach — [#1635](https://github.com/useautumn/autumn/pull/1635)
* Vercel: Stripe Tax disabled when org has no tax config; metadata is now optional — [#1558](https://github.com/useautumn/autumn/pull/1558)
* Various Vercel marketplace bug fixes — [#1579](https://github.com/useautumn/autumn/pull/1579)
* Duplicate Stripe customer ID handling — [#1528](https://github.com/useautumn/autumn/pull/1528)
* Cache invalidation correctness on customer and plan edits — [#1531](https://github.com/useautumn/autumn/pull/1531), [#1612](https://github.com/useautumn/autumn/pull/1612)
* Dashboard customer cache freshness — [#1612](https://github.com/useautumn/autumn/pull/1612)
* Plan analytics: per-item parse failures no longer drop valid deductions; `$plan_id` alias normalised — [#1608](https://github.com/useautumn/autumn/pull/1608)
* `list events` hook returns the correct response type — [#1633](https://github.com/useautumn/autumn/pull/1633)
* Shadow flag evaluation fixes — [#1632](https://github.com/useautumn/autumn/pull/1632)
* Webhook tag filtering improvements — [#1617](https://github.com/useautumn/autumn/pull/1617)
* No-op plan PATCH now exits cleanly without spurious updates — [#1628](https://github.com/useautumn/autumn/pull/1628)
* Database pool sizing and connection limits raised for higher throughput — [#1625](https://github.com/useautumn/autumn/pull/1625), [#1643](https://github.com/useautumn/autumn/pull/1643)
## Scheduled subscriptions with `starts_at`
You can now schedule a plan to start at a future date by passing a `starts_at` Unix timestamp (milliseconds) to `billing.attach`. Future-dated attaches create a Stripe subscription schedule that activates on the start date — perfect for delayed onboarding, contract renewals, or sales-led handoffs.
Pair `starts_at` with `ends_at` to grant access for a fixed window. One-off products now also support `ends_at` and are automatically cleaned up when the window expires.
See the [attach API reference](/api-reference/billing/attach).
## Auto top-up succeeded webhook
A new **`billing.auto_topup_succeeded`** webhook fires whenever an auto top-up is processed for a customer. The payload includes the customer ID, feature ID, quantity granted, threshold that triggered the top-up, post-top-up balance, and the full Stripe invoice (status, total, currency, hosted URL, and PDF link).
Useful for sending receipts, syncing top-ups to your own ledger, or alerting customers that their card was charged. Supports both auto-charged and `send_invoice` modes.
See the [auto top-up webhook reference](/api-reference/webhooks/billingAutoTopupSucceeded) and the [auto top-ups guide](/documentation/modelling-pricing/auto-top-ups).
## Promo codes in Autumn Checkout
Customers can now apply promo codes directly in Autumn Checkout. The order summary surfaces a collapsed promo trigger that expands into an input — applied codes show their discount and expiry inline, and the totals update before confirmation.
## Discounts and coupons in subscription updates
The dashboard's subscription update flow now supports applying discounts. Existing coupons are visible in the subscription detail sheet, and you can attach a discount when changing a plan or quantities.
## Tax and invoice credits in attach preview
`billing.preview_attach` now returns two new optional fields:
* **`tax`**: Tax breakdown for the immediate charge (total, inclusive/exclusive amounts, currency, calculation status). Powered by Stripe Tax — contact us to enable the tax flag on your organisation.
* **`invoice_credits`**: The customer's available Stripe invoice credit balance, so you can show "Account credit" line items in custom checkouts.
See the [preview attach reference](/api-reference/billing/previewAttach).
## `balances` field in `track` responses
The `/track` endpoint now returns the affected feature balances — including a per-plan `breakdown` of grants, prepaid credits, usage, remaining, and rollovers — directly in the response. This removes the need for a follow-up `check` call after recording usage.
See the [track endpoint](/api-reference/core/track).
## `processors` field on customer responses
Customer endpoints (`get`, `getOrCreate`, `update`, `list`) now return a `processors` object listing every payment processor the customer is connected to: Stripe, Vercel, and RevenueCat. The field is omitted for customers not yet present in any processor.
You can also filter `customers.list` by processor with the new `processors` query parameter.
## Auto top-up purchase limits in customer expand
Expand `billing_controls.auto_topups.purchase_limit` on customer endpoints to retrieve the configured top-up rate limit, the current count of top-ups in the period, and the next reset timestamp. Useful for showing customers how close they are to their auto top-up cap.
## RevenueCat invoice sync
RevenueCat-billed subscriptions now record full invoices on initial purchase, renewal, and refund events. Invoices appear alongside Stripe invoices in customer responses and the dashboard, giving you a unified view of revenue across processors.
* `starts_at` parameter on `billing.attach` for scheduled subscription start dates - [#1411](https://github.com/useautumn/autumn/pull/1411), [#1467](https://github.com/useautumn/autumn/pull/1467), [#1476](https://github.com/useautumn/autumn/pull/1476)
* `ends_at` on one-off products with automatic expiry cron - [#1476](https://github.com/useautumn/autumn/pull/1476)
* `billing.auto_topup_succeeded` webhook - [#1429](https://github.com/useautumn/autumn/pull/1429)
* Promo code support in Autumn Checkout - [#1446](https://github.com/useautumn/autumn/pull/1446)
* Discount support on subscription updates and coupon display in subscription detail - [#1463](https://github.com/useautumn/autumn/pull/1463)
* Tax preview in `billing.preview_attach` - [#1417](https://github.com/useautumn/autumn/pull/1417), [#1424](https://github.com/useautumn/autumn/pull/1424)
* Invoice credits preview in `billing.preview_attach` - [#1464](https://github.com/useautumn/autumn/pull/1464)
* `balances` field returned in `/track` responses - [#1470](https://github.com/useautumn/autumn/pull/1470)
* `processors` field and `processors` filter on customer endpoints - [#1490](https://github.com/useautumn/autumn/pull/1490)
* `billing_controls.auto_topups.purchase_limit` expand on customer endpoints - [#1423](https://github.com/useautumn/autumn/pull/1423)
* RevenueCat invoice recording on initial purchase, renewal, and refund - [#1490](https://github.com/useautumn/autumn/pull/1490)
* OpenAPI spec, SDKs, and dashboard updated with `starts_at` / `ends_at` fields - [#1485](https://github.com/useautumn/autumn/pull/1485)
* Checkout `enable_immediately` flow improvements - [#1415](https://github.com/useautumn/autumn/pull/1415)
* API key sheet and table UI cleanup
* Proration settings now visible during cross-entity free-to-paid attach - [#1491](https://github.com/useautumn/autumn/pull/1491)
* Dashboard org switcher now lists the full set of organizations - [#1475](https://github.com/useautumn/autumn/pull/1475)
* Balance validation no longer rejects valid edits - [#1477](https://github.com/useautumn/autumn/pull/1477)
* Schedule sync edge cases fixed - [#1443](https://github.com/useautumn/autumn/pull/1443)
* Orphaned customer products cleaned up correctly - [#1440](https://github.com/useautumn/autumn/pull/1440)
* Auto-sync paid feature mapping on plan edits - [#1448](https://github.com/useautumn/autumn/pull/1448)
* Member toolbar z-index fixed in the dashboard - [#1449](https://github.com/useautumn/autumn/pull/1449)
* Prepaid price v2 fixes - [#1451](https://github.com/useautumn/autumn/pull/1451)
* Vercel customer filtering when no Stripe is connected - [#1455](https://github.com/useautumn/autumn/pull/1455), [#1458](https://github.com/useautumn/autumn/pull/1458)
## Usage alerts and `balances.limit_reached` webhook
You can now configure **usage alerts** on customers and entities to get notified when usage crosses a threshold. Alerts are set via `billingControls.usageAlerts` and fire a `balances.usage_alert_triggered` webhook. Supports both absolute usage counts and percentage-of-allowance thresholds.
A new **`balances.limit_reached`** webhook fires when a customer hits a usage limit — whether it's the included allowance, a max purchase cap, or a spend limit. See the [webhooks reference](/documentation/webhooks) and [spend limits & usage alerts guide](/documentation/modelling-pricing/spend-limits) for details.
## Express, Elysia, and Web Standard adapters for `autumn-js`
The `autumn-js` SDK now ships adapters for Express, Elysia, and any framework that uses the Fetch API `Request`/`Response` objects. You can set up the `autumnHandler` in your backend with a single import — no manual request parsing required.
* **Express**: Import from `autumn-js/express` and mount with `app.use()`. Requires `express.json()` before the handler
* **Elysia / Web Standard**: Import from `autumn-js/fetch` and use with Elysia's `.mount()`, Cloudflare Workers, Deno, or any Fetch-based runtime
* **Existing adapters**: Next.js (`autumn-js/next`) and Hono (`autumn-js/hono`) continue to work as before
See the [setup guide](/documentation/getting-started/setup) for framework-specific code examples.
## Explicit customer creation required for `check` and `track`
The `/check` and `/track` endpoints no longer auto-create customers. If you call these endpoints with a `customer_id` that doesn't exist, the API now returns a `customer_not_found` error instead of silently creating the customer.
This change encourages explicit customer lifecycle management and prevents accidental customer creation from typos or stale IDs.
* **Create customers first**: Call [`customers.getOrCreate`](/documentation/customers/creating-customers) during signup or login before using `check` or `track`
* **Handle the error**: If a customer doesn't exist, the API returns error code `customer_not_found`
## `autumn-js` SDK 1.0.0
The `autumn-js` SDK has been promoted from beta to stable at version `1.0.0`.
## New framework adapters
The `autumn-js` SDK now includes adapters for Express, Elysia, and any Web Standard compatible runtime (Cloudflare Workers, Deno). Import from the adapter that matches your backend:
| Framework | Import path |
| --------------------- | ------------------- |
| Next.js | `autumn-js/next` |
| Hono | `autumn-js/hono` |
| Elysia / Web Standard | `autumn-js/fetch` |
| Express | `autumn-js/express` |
| Other | `autumn-js/backend` |
See the [setup guide](/documentation/getting-started/setup) and the [`autumnHandler` reference](/react/hooks/autumn-handler) for full examples.
* Express adapter for `autumnHandler` via `autumn-js/express` - [#979](https://github.com/useautumn/autumn/pull/979)
* Web Standard adapter for `autumnHandler` via `autumn-js/fetch` (Elysia, Cloudflare Workers, Deno) - [#979](https://github.com/useautumn/autumn/pull/979)
* Explicit customer creation required for `check` and `track` endpoints - [#968](https://github.com/useautumn/autumn/pull/968)
* `autumn-js` SDK promoted to `1.0.0` stable release - [#968](https://github.com/useautumn/autumn/pull/968)
* New Express, Elysia, and Web Standard adapters for `autumnHandler` - [#985](https://github.com/useautumn/autumn/pull/985)
* Improved API reference field descriptions for preview endpoints - [#985](https://github.com/useautumn/autumn/pull/985)
* `checkout_session_params.subscription_data` (including `metadata`) is now properly deep-merged with Autumn's internal parameters instead of being overwritten - [#996](https://github.com/useautumn/autumn/pull/996)
## Balance and usage carry-over on plan upgrades
You can now preserve a customer's remaining balances and usage when they upgrade plans. Two new parameters on `billing.attach` give you fine-grained control over what happens to consumable features during an immediate upgrade.
* **`carry_over_balances`**: Unused credits or balances from the old plan are carried forward to the new one — so customers don't lose what they've already paid for
* **`carry_over_usages`**: Prior usage is deducted from the new plan's allowance, preventing customers from getting a free reset on upgrade
* **Per-feature control**: Optionally scope carry-over to specific features using `feature_ids`
See the [attach API reference](/api-reference/billing/attach) for details.
## Feature flags in customer and entity responses
Boolean features are now returned as a dedicated `flags` object on customer and entity API responses. This makes it easier to check on/off feature access without calling the `check` endpoint separately.
* **Separate from balances**: Flags live under `flags` in the response, clearly separated from consumable balances
* **Available everywhere**: Returned on customer get, list, entity get, and entity create endpoints
* **Includes metadata**: Each flag shows the originating plan, expiration, and feature ID
See the [check endpoint](/api-reference/core/check) and [customer endpoints](/api-reference/customers/getOrCreateCustomer) for the updated response format.
* Balance carry-over on immediate plan upgrades via `carry_over_balances` - [#861](https://github.com/useautumn/autumn/pull/861)
* Usage carry-over on immediate plan upgrades via `carry_over_usages` - [#875](https://github.com/useautumn/autumn/pull/875)
* Boolean features returned as `flags` in customer and entity objects - [#950](https://github.com/useautumn/autumn/pull/950)
* Updated API, SDKs, and frontend with new flag fields - [#951](https://github.com/useautumn/autumn/pull/951)
* Fixed customer retrieval query causing errors in certain configurations - [#958](https://github.com/useautumn/autumn/pull/958), [#959](https://github.com/useautumn/autumn/pull/959)
* Fixed trial upgrade reliability when unsetting trial periods - [#958](https://github.com/useautumn/autumn/pull/958)
## Autumn Checkout
We've launched Autumn Checkout — a hosted confirm-before-charge flow that gives customers a clear preview before completing their purchase.
When a customer with a saved payment method subscribes or updates their plan, they're now sent to Autumn Checkout instead of being charged directly. This lets them review exact pricing — including prorations, usage charges, and discounts — before confirming.
* **Preview before you pay**: Customers see immediate charges and next-cycle estimates before confirming
* **Works everywhere**: Supports new subscriptions, plan upgrades, and quantity updates
* **Handles edge cases**: Built-in flows for 3DS authentication, payment failures, and action-required states
* **No API changes**: Just follow the `paymentUrl` returned by `billing.attach` or `billing.update`
When you call `billing.attach` or `billing.update`, the returned `paymentUrl` routes customers to:
* **Stripe Checkout** — if they don't have a saved payment method
* **Autumn Checkout** — if they do, so they can review and confirm the charge
After confirmation, customers are redirected to your `successUrl`.
## Volume-Based Tiered Pricing
You can now choose between graduated and volume-based tiered pricing for your plans. With volume pricing, the entire usage quantity falls into a single tier instead of splitting across tiers — useful for models where the per-unit price depends on total consumption.
* **Two tier modes**: Choose graduated (split across tiers) or volume (single tier applies to all units)
* **Backward compatible**: Existing graduated plans work without changes; volume is opt-in via `tier_behavior`
* **Full stack**: Supported in the plan editor, attach/checkout previews, Stripe invoices, and the API
## Batch Attach
Attach multiple plans to a customer in a single API request. Each plan can have its own customization, feature quantities, and trial settings — all validated and applied atomically with a distributed lock.
* **One request, multiple plans**: Attach several plans at once with per-plan customization
* **Preview support**: Preview the combined batch before committing via `/billing.preview_multi_attach`
* **Concurrency safe**: Distributed lock prevents conflicting concurrent attaches
## Lazy Entitlement Resets
Entitlement resets now happen lazily on read, so customers see fresh balances instantly without waiting for a cron cycle. An atomic Postgres function and Redis Lua script prevent double-resets under concurrency.
* **Instant resets**: Stale entitlements are reset the moment they're fetched
* **Atomic & safe**: Per-row locking in Postgres and atomic Redis Lua patching prevent double-resets
* **Hardened cron fallback**: Batch reset cron bounded with max iterations and timeouts
- Volume-based tiered pricing alongside graduated pricing - [#765](https://github.com/useautumn/autumn/pull/765)
- Batch attach: attach multiple plans in one request - [#815](https://github.com/useautumn/autumn/pull/815)
- Lazy entitlement resets for instant balance refreshes - [#800](https://github.com/useautumn/autumn/pull/800), [#802](https://github.com/useautumn/autumn/pull/802)
- Atomic Redis updates for customer data and entities (CRDT-safe) - [#812](https://github.com/useautumn/autumn/pull/812), [#813](https://github.com/useautumn/autumn/pull/813)
- Mobile navigation with sticky top bar and slide-in sidebar - [#760](https://github.com/useautumn/autumn/pull/760)
- 12/24-hour date and time picker for balance reset scheduling - [#760](https://github.com/useautumn/autumn/pull/760)
- Stripe coupon support in attach discount dropdown - [#819](https://github.com/useautumn/autumn/pull/819)
- Metadata on Stripe invoice line items (product ID, price ID, coupon IDs) - [#817](https://github.com/useautumn/autumn/pull/817)
- RPC router for Plans (create/get/update/delete) - [#750](https://github.com/useautumn/autumn/pull/750)
- RPC router for Features (list/get/create/update/delete) - [#762](https://github.com/useautumn/autumn/pull/762)
- Hardened reset cron with bounded batches and timeouts - [#808](https://github.com/useautumn/autumn/pull/808)
- Customer filter and UI cleanups - [#755](https://github.com/useautumn/autumn/pull/755)
- Unit tests GitHub Action - [#801](https://github.com/useautumn/autumn/pull/801)
* Fixed scheduled switches failing when a Stripe coupon was deleted - [#759](https://github.com/useautumn/autumn/pull/759)
* Fixed events table showing empty - [#822](https://github.com/useautumn/autumn/pull/822)
* Fixed customer balance UI - [#816](https://github.com/useautumn/autumn/pull/816)
* Fixed balance subrow to always show /granted - [#779](https://github.com/useautumn/autumn/pull/779), [#780](https://github.com/useautumn/autumn/pull/780)
* Fixed attach dashboard one-off products - [#789](https://github.com/useautumn/autumn/pull/789)
* Fixed create customer body expand - [#787](https://github.com/useautumn/autumn/pull/787)
* Fixed Vercel marketplace status not ready - [#778](https://github.com/useautumn/autumn/pull/778)
* Fixed discounts on upgrades in legacy attach - [#772](https://github.com/useautumn/autumn/pull/772)
* Fixed invoice without payment method - [#770](https://github.com/useautumn/autumn/pull/770)
* Fixed SQS client restart - [#767](https://github.com/useautumn/autumn/pull/767), [#768](https://github.com/useautumn/autumn/pull/768)
* Fixed impersonation - [#793](https://github.com/useautumn/autumn/pull/793)
* Fixed reset for past-due customer entitlements - [#805](https://github.com/useautumn/autumn/pull/805), [#806](https://github.com/useautumn/autumn/pull/806)
* Fixed zero denominator issue - [#746](https://github.com/useautumn/autumn/pull/746)
* Fixed Vercel transfer request blocking - [#744](https://github.com/useautumn/autumn/pull/744)
* Fixed discounts on scheduled subscriptions - [#742](https://github.com/useautumn/autumn/pull/742)
* Fixed invoice cron race condition - [#747](https://github.com/useautumn/autumn/pull/747)
* Fixed custom plan detection in subscription updates - [#784](https://github.com/useautumn/autumn/pull/784)
* Fixed success URL handling for v2 attach checkout - [#786](https://github.com/useautumn/autumn/pull/786)
* Fixed preview attach concurrency lock - [#758](https://github.com/useautumn/autumn/pull/758)
* New `POST /billing.multi_attach` and `POST /billing.preview_multi_attach` for batch plan attaches - [#815](https://github.com/useautumn/autumn/pull/815)
* New `POST /billing.setup_payment` for collecting payment methods before plan attach - [#797](https://github.com/useautumn/autumn/pull/797)
* New attach/update subscription V1 params: `plan_id`, `feature_quantities`, `customize`, `free_trial`, `transition_rules` - [#749](https://github.com/useautumn/autumn/pull/749), [#752](https://github.com/useautumn/autumn/pull/752)
* RPC endpoints for Plans: `/plans.create`, `/plans.get`, `/plans.update`, `/plans.delete` - [#750](https://github.com/useautumn/autumn/pull/750)
* RPC endpoints for Features: `/features.list`, `/features.get`, `/features.create`, `/features.update`, `/features.delete` - [#762](https://github.com/useautumn/autumn/pull/762)
* Added `PATCH /customers/:customer_id` for partial updates - [#774](https://github.com/useautumn/autumn/pull/774)
* Metadata added to Stripe invoice line items - [#817](https://github.com/useautumn/autumn/pull/817)
* V2 API docs with multi-version OpenAPI specs and SDK generation pipeline - [#773](https://github.com/useautumn/autumn/pull/773)
## Dynamic onboarding prompts
We've added a new in-app onboarding guide to help you get your billing set up in less than 30 minutes.
* **Docs in app**: Access documentation directly within the dashboard
* **3 prompts → full billing setup**: Complete your entire billing configuration in just 3 steps
* **Dynamic code snippets**: Get code snippets and prompts tailored to your specific pricing config
* **Real-time updates**: See your progress update as you complete each step
* Code cleanup and refactoring in Stripe billing plan evaluation system - [#525](https://github.com/useautumn/autumn/pull/525)
* Added `customerId` to request context for improved tracking and observability - [#520](https://github.com/useautumn/autumn/pull/520)
* Improved cache verification workflow with free product filtering and Sentry alert tags - [#519](https://github.com/useautumn/autumn/pull/519)
* Major Redis Lua refactor with cache versioning, filtering, and safer updates - [#512](https://github.com/useautumn/autumn/pull/512)
* Fixed multi-region cache deletion to delete from all configured regions - [#539](https://github.com/useautumn/autumn/pull/539)
* Fixed import path casing issue for createProrationinvoice - [#537](https://github.com/useautumn/autumn/pull/537)
* Fixed TypeScript type compatibility in BullMQ worker - [#538](https://github.com/useautumn/autumn/pull/538)
* Fixed type annotations in OpenAPI definitions and RevenueCat mappings - [#533](https://github.com/useautumn/autumn/pull/533), [#534](https://github.com/useautumn/autumn/pull/534)
* Fixed migration logic for product downgrades and cancellations - [#529](https://github.com/useautumn/autumn/pull/529)
* Fixed subscription migration to prevent auto-uncanceling during version updates - [#527](https://github.com/useautumn/autumn/pull/527)
* Fixed `included_usage` calculation in V1.2 API backward compatibility layer - [#526](https://github.com/useautumn/autumn/pull/526)
* Implemented Redis-first caching for add-to-balance operations - [#524](https://github.com/useautumn/autumn/pull/524)
* Simplified Stripe webhook cache refresh strategy - [#523](https://github.com/useautumn/autumn/pull/523)
* Removed redundant `plan_version` field from subscription API schema - [#522](https://github.com/useautumn/autumn/pull/522)
* Fixed duplicate features in plan editor when closing edit feature sheet - [#508](https://github.com/useautumn/autumn/pull/508)
* Added `entity_id` parameter support to legacy balance update endpoint - [#532](https://github.com/useautumn/autumn/pull/532)
* Added `/configs/push` and `/configs/nuke` endpoints for managing organization configuration in sandbox environments - [#521](https://github.com/useautumn/autumn/pull/521)
* Implemented idempotency protection for billing endpoints using `idempotency-key` header - [#516](https://github.com/useautumn/autumn/pull/516)
* Added new `POST /customers/list` V2 endpoint with plan filtering, subscription status filtering, and search functionality - [#518](https://github.com/useautumn/autumn/pull/518), [#517](https://github.com/useautumn/autumn/pull/517)
## Add to balance in the dashboard
Merry Christmas! 🎄
You can now add to a customer's balance directly from the dashboard. This is useful for giving extra credits to a customer.
You can input a positive or negative value in this field.
* Balance management enhancements with atomic "Add to Balance" feature - [#503](https://github.com/useautumn/autumn/pull/503)
* Product copy workflow streamlined with direct environment selection - [#501](https://github.com/useautumn/autumn/pull/501)
* Plan feature sheet with discard/update actions and change detection - [#499](https://github.com/useautumn/autumn/pull/499)
* Base price display logic centralized into reusable utility - [#488](https://github.com/useautumn/autumn/pull/488)
* Stripe secret key authentication always available, improved UI - [#491](https://github.com/useautumn/autumn/pull/491)
* Console logs removed from production builds for cleaner output - [#487](https://github.com/useautumn/autumn/pull/487)
* Sign-in flow simplified by removing onboarding redirect logic - [#484](https://github.com/useautumn/autumn/pull/484)
* Enter key handler added for email sign-in and cache improvements - [#483](https://github.com/useautumn/autumn/pull/483)
* Plan editor UI enhanced with better pricing configuration - [#481](https://github.com/useautumn/autumn/pull/481)
* Hono dependency pinned to exact version for build consistency - [#494](https://github.com/useautumn/autumn/pull/494)
* UI refinements and number formatting improvements - [#500](https://github.com/useautumn/autumn/pull/500)
* Add-on products no longer carry usage from main products - [#502](https://github.com/useautumn/autumn/pull/502)
* Base price display component type handling fixed - [#496](https://github.com/useautumn/autumn/pull/496)
* Invoice checkout cache invalidation fixed for null customer IDs - [#490](https://github.com/useautumn/autumn/pull/490)
* One-off products properly handled during subscription upgrades - [#489](https://github.com/useautumn/autumn/pull/489)
* Sandbox redirect logic restored for non-deployed organizations - [#486](https://github.com/useautumn/autumn/pull/486)
* Dashboard checkout success URL fixed for production environments - [#485](https://github.com/useautumn/autumn/pull/485)
* Transfer endpoint cache clearing URL pattern corrected - [#482](https://github.com/useautumn/autumn/pull/482)
* Cache race condition in attach flow resolved with timestamp guards - [#479](https://github.com/useautumn/autumn/pull/479)
* RevenueCat payment processor integration added and reverted - [#497](https://github.com/useautumn/autumn/pull/497), [#495](https://github.com/useautumn/autumn/pull/495), [#435](https://github.com/useautumn/autumn/pull/435), [#493](https://github.com/useautumn/autumn/pull/493)
* Added manual secret key override to Hono `autumnHandler`
* Added `checkoutSessionParams` to `PricingTable` component from `autumn-js/react`
* Added `new_billing_subscription` to the `attach` endpoint, allowing you to create a new Stripe subscription instead of combining with an existing one
## RevenueCat integration
We just released a new integration with RevenueCat, to let you manage your mobile app subscriptions and billing with Autumn.
This is especially helpful for users that have a mix of web and mobile users, and want to manage their billing in one place.
* **RevenueCat integration**: [Documentation](/documentation/external-providers/revenuecat)
This is currently in beta, please reach out to us on [Discord](https://discord.gg/STqxY92zuS) or email us at [hey@useautumn.com](mailto:hey@useautumn.com) to get access.
## List and aggregate events endpoints
We just released two new endpoints to retrieve usage data that your customers have sent to Autumn.
You can use this to display a billing event log, and a timeseries chart of usage data, so you can provide first-class billing observability out of the box!
* **List Events**: [React hooks](/react/hooks/useListEvents) and [API reference](/api-reference/events/list-events)
* **Aggregate Events**: [React hooks](/react/hooks/useAggregateEvents) and [API reference](/api-reference/events/aggregate-events)
## Stripe customer portal link within the customer page
You can now open a customer's Stripe customer portal directly from the customer page. You can quickly preview this and send to customers that want to manage their payment methods or see past invoices.
## Usage columns in your customer list
Preview a customer's current credit balances straight from the customer list. Now you can see who's worth peeking into!
## Autumn is live in us-east
Autumn is live on US-East! Previously all requests were hitting our us-west DB.
Now, we're reading and writing from multiple Redis caches, so both checking feature balances and tracking usage events are faster and more reliable.
More regions coming soon!
## Dark mode
Dark mode is here. No need to say more. We know you guys are all night owls.
We also shipped an entirely new design for the plan editor and customer pages, to make managing your plans and customers easier.
# Command reference
Source: https://docs.useautumn.com/cli/commands
All atmn CLI commands, flags and environment variables
Run `atmn --help` or `atmn --help` to see the latest options.
## Global flags
These work with every command.
| Flag | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-p, --prod` | Target production instead of sandbox |
| `--sandbox ` | Target a specific [sandbox](#sandboxes) |
| `-c, --config ` | Your `autumn.config.ts`, or the folder holding it. By default the CLI looks in the current folder, then at the path `atmn init` saved in your root `package.json`. |
| `--headless` | Never prompt. When a command needs an answer, it prints which flag to pass and stops. This is the default outside a terminal, eg in CI or when run by an agent. |
| `-l, --local` | Send requests to a local Autumn server on `localhost:8080` |
| `--port ` | Port of the local server. Implies `--local`. |
| `-b, --base-url ` | Send requests to this URL instead |
| `-v, -V, --version` | Print the CLI version |
## Environment variables
The CLI reads `.env.local` and then `.env` from your repo root, your config folder and the current folder. Anything already set in your shell wins over the files.
| Variable | Description |
| -------------------------------- | --------------------------------------------------------------------- |
| `AUTUMN_SECRET_KEY` | Your sandbox key. Written by `atmn login`. |
| `AUTUMN_PROD_SECRET_KEY` | Your production key, used with `-p`. Written by `atmn login`. |
| `AUTUMN_SANDBOX_ID` | Pins every command to a named sandbox. Written by `atmn sandbox use`. |
| `AUTUMN_SANDBOX__SECRET_KEY` | The key for one named sandbox. Written by `atmn sandbox create`. |
| `AUTUMN_BASE_URL` | Send requests to this URL instead of `https://api.useautumn.com`. |
In CI, set the key as a secret, install your dependencies, and push:
```yaml theme={null}
- name: Deploy pricing
run: npx atmn push --prod --yes
env:
AUTUMN_PROD_SECRET_KEY: ${{ secrets.AUTUMN_PROD_SECRET_KEY }}
```
## Setup
### `atmn init`
Set up your repo end to end: connect to Autumn, create the config folder, pull what's already in your organization, and install the agent skills. See [getting started](/cli/getting-started#set-up-a-project) for what it creates.
```bash theme={null}
atmn init
```
| Flag | Description |
| --------------- | ---------------------------------------------------------------------------- |
| `--login` | Connect by signing in on the web |
| `--keyless` | Connect by creating a sandbox with no account |
| `--path ` | Folder for the config. Default `autumn`, or `packages/autumn` in a monorepo. |
| `--name ` | Name of the config package (monorepos only) |
With no key on disk, `init` asks how you want to connect. In headless mode it prints the two flags and stops; run it again with one of them to continue. Running `init` again on a repo that's already set up is safe: it keeps your config and only fills in what's missing.
### `atmn login`
Connect to Autumn and write your organization's keys to `.env`. Opens your browser and lets you pick an organization. Outside a terminal it prints the URL for you to open.
```bash theme={null}
atmn login
```
| Flag | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `--keyless` | Create a sandbox with no account, and write its key to `.env` |
| `--claim ` | Link a keyless sandbox to an account. Prints and emails a sign-in link. The key you have keeps working. |
### `atmn env`
Show which organization, environment and key your commands will use:
```bash theme={null}
atmn env
```
```
Organization Acme (acme)
Environment Sandbox
User you@acme.com
Key AUTUMN_SECRET_KEY
```
| Flag | Description |
| -------- | --------------------------------------------------------------------- |
| `--json` | Print the same facts as JSON, with notes on anything that looks wrong |
## Config
### `atmn push`
Compare your config with what's in Autumn, and apply the difference.
```bash theme={null}
atmn push # preview
atmn push --yes # apply
```
| Flag | Description |
| --------------- | ----------------------------------- |
| `-y, --yes` | Apply the changes the preview shows |
| `-d, --dry-run` | Preview only, even with `--yes` |
A plain `push` is always a preview. It shows what would be created, updated or deleted, and nothing is sent until you add `--yes`. Deletions work the same way: a plan you remove from the config is removed from Autumn on the next `push --yes`.
If a change affects a plan version that has customers, Autumn drafts a migration and `push` prints the link to run it. After applying, the CLI writes the `internalId` of each new feature and plan back into your config files.
### `atmn pull`
Write what's in Autumn back into your config files.
```bash theme={null}
atmn pull
```
| Flag | Description |
| -------------------- | ------------------------------------------------------------------------------ |
| `--overwrite` | Rewrite the config from Autumn instead of updating it in place. Needs `--yes`. |
| `-y, --yes` | Confirm the overwrite |
| `--include-mappings` | Keep Stripe and RevenueCat mappings in the pulled config |
By default, `pull` updates in place: it adds new features and plans, updates existing ones, and removes deleted ones, keeping your formatting. If you have no config yet, it asks where to create one (pass `-c ` to skip the question).
`--overwrite --yes` rewrites `autumn.config.ts` and the `features.ts`, `plans.ts` and `rewards.ts` beside it from Autumn. Use it after switching organizations, or to move a 1.x config to the new format. Nothing is deleted, and files that don't import from `atmn` are left alone.
### `atmn reset`
Wipe a sandbox: every customer, plan, feature and migration draft. Keys and settings stay.
```bash theme={null}
atmn reset --yes
```
| Flag | Description |
| ----------- | ---------------------------------------------------------- |
| `-y, --yes` | Wipe it. Without this, `reset` only says what it would do. |
`reset` refuses to run against a production key. Run `atmn push --yes` afterwards to rebuild the sandbox from your config.
## API
### `atmn api`
Call any public API endpoint from the terminal. The command name matches the endpoint: `atmn api `.
```bash theme={null}
atmn api customers get_or_create customer_id=user_123 name="Ada Lovelace"
atmn api balances check customer_id=user_123 feature_id=messages
atmn api billing attach customer_id=user_123 plan_id=pro
atmn api plans list
```
| Flag | Description |
| ----------------------- | --------------------------------------------------------------- |
| `--body ` | The whole request body as JSON. Pass `-` to read it from stdin. |
| `-H, --header ` | An extra request header, as `"name: value"`. Repeatable. |
| `--curl` | Print the request as a `curl` command instead of sending it |
Body fields are passed as `key=value`. Numbers and booleans are converted for you, and fields that take an object or array are parsed as JSON:
```bash theme={null}
atmn api customers update customer_id=user_123 metadata='{"tier":"gold"}'
```
You can combine `--body` with `key=value` pairs; the pairs override fields in the body. Responses are printed as JSON. On an error, the status line goes to stderr, the response body goes to stdout, and the command exits with code 1.
`atmn api` uses the same key as every other command, so `-p` and `--sandbox` work with it. Run `atmn api --help` to list the groups, and `atmn api --help` to see an endpoint's fields.
Groups: `balances`, `billing`, `customers`, `entities`, `events`, `features`, `invoices`, `keys`, `licenses`, `plans`, `platform`, `referral_programs`, `referrals`, `rewards`, `sandboxes`.
## Sandboxes
Sandboxes are separate copies of your organization, each with its own plans, customers and API key. Use them to test changes without touching your main sandbox.
```bash theme={null}
atmn sandbox list # show your sandboxes
atmn sandbox create staging --use # create one and switch to it
atmn sandbox use staging # switch to one by name or id
atmn sandbox use --clear # go back to your main sandbox
atmn sandbox delete --yes # delete one, with its plans and customers
```
### `atmn sandbox list`
| Flag | Description |
| -------- | --------------------------------------- |
| `--json` | Print the response instead of the table |
### `atmn sandbox create `
Creates the sandbox and writes its key to `.env` as `AUTUMN_SANDBOX__SECRET_KEY`.
| Flag | Description |
| ----------------- | ----------------------------------------- |
| `--use` | Switch to it right away |
| `--color ` | Color the dashboard labels it with |
| `--icon ` | Icon the dashboard labels it with |
| `--json` | Print the response instead of the summary |
### `atmn sandbox use [name or id]`
Writes `AUTUMN_SANDBOX_ID` to your `.env`, so every later command targets that sandbox. With no name it asks which one. Add `-p` to any command to target production regardless of the pin.
| Flag | Description |
| --------- | ---------------------------------------------------------- |
| `--clear` | Remove the pin, so commands target your main sandbox again |
| `--json` | Print the result as JSON |
### `atmn sandbox delete `
| Flag | Description |
| ----------- | --------------------------------------- |
| `-y, --yes` | Delete it, plans and customers included |
`sandbox list`, `create` and `delete` always use your main key (`AUTUMN_SECRET_KEY`), even when a sandbox is pinned. If you want to target a sandbox for one command without pinning it, pass `--sandbox `.
## Skills
The CLI ships with skills that teach coding agents how to set up Autumn, model pricing, and integrate the API: `autumn-setup`, `autumn-catalog`, `autumn-integrate` and `autumn-concepts`.
### `atmn skills [name]`
List the bundled skills, or print one:
```bash theme={null}
atmn skills
atmn skills autumn-catalog
```
| Flag | Description |
| -------------- | ------------------------------------------------ |
| `--ref ` | Print one of the skill's reference files instead |
| `--json` | Print the skill as JSON |
### `atmn skills install`
Write the skills into a `skills/` folder next to your config, so your agent can use them. `atmn init` does this for you.
| Flag | Description |
| ------------- | ---------------------------------------------------------------------------- |
| `--dir ` | Write them somewhere else |
| `--link` | Run `npx skills add --all` afterwards to register them with your agent |
### `atmn skills update`
Bring installed skills up to the version bundled with this CLI. `push` and `pull` tell you when yours are out of date.
| Flag | Description |
| ------------- | ------------------------------------------------------------- |
| `--dir ` | The install to update. Default `skills/` next to your config. |
## Headless mode
Outside a terminal (CI, a pipe, an agent) the CLI never prompts. When a command needs an answer, it prints the flag to pass and stops, so you can run it again with that flag. Force this behavior with `--headless`.
### Exit codes
| Code | Meaning |
| ---- | ------------------------------------------------------- |
| `0` | Success, or the command stopped to ask for a flag |
| `1` | Error: network, auth, a config problem, or an API error |
# Configuration reference
Source: https://docs.useautumn.com/cli/config
Define features, plans, rewards and settings in autumn.config.ts
Your `autumn.config.ts` file is the source of truth for your pricing. It builds features, plans and rewards with helper functions from the `atmn` package, and hands them to `atmn()` as the default export.
```ts autumn.config.ts theme={null}
import { atmn, feature, plan } from "atmn";
export const messages = feature({ ... });
export const pro = plan({ ... });
export default atmn({ features: [messages], plans: [pro] });
```
Preview changes with `atmn push`, apply them with `atmn push --yes`, or pull what's in Autumn with `atmn pull`.
## File layout
`atmn init` and `atmn pull` create a folder with one file per kind of thing, and a root config that imports them:
```
autumn/
autumn.config.ts # export default atmn({ features, plans, rewards, referralPrograms, settings })
features.ts # export const features = [feature({ ... }), ...]
plans.ts # export const plans = [plan({ ... }), ...]
rewards.ts # export const rewards = [...]; export const referralPrograms = [...]
```
`atmn pull` writes into these files and keeps your formatting. A single `autumn.config.ts` with everything in it works too. Any file that imports from `atmn` is treated as part of your config.
## `atmn(config)`
The root of your config. Each list you include is the **complete** list: anything in Autumn that isn't in it gets deleted on push. Leave a list out to leave that part of Autumn alone.
Every feature, from `feature()`.
Every plan and every version of it, from `plan()`.
Coupons and feature grants, from `coupon()` and `featureGrant()`. See [rewards](#rewards).
Referral programs, from `referralProgram()`. See [referral programs](#referral-programs).
Organization settings. Only the flags you state are changed. See [settings](#settings).
The CLI checks the whole config before sending anything and reports every problem at once, with the file and line to fix.
## Features
Features define what can be gated, metered or billed in your app.
### `feature(config)`
Unique identifier used in API calls (`check`, `track`, etc).
Display name shown in the dashboard and billing UI.
`"boolean"` | `"metered"` | `"credit_system"` | `"ai_credit_system"`
**Required for `metered` features.**
* `true`: usage is used up and refilled (messages, API calls, credits)
* `false`: usage is ongoing (seats, storage, workspaces)
**Required for `credit_system` features.** The rate card: one entry per metered feature that draws from the credit balance.
Flat rate: `{ meteredFeatureId: string, creditCost: number, billingUnits?: number }`: `creditCost` credits per `billingUnits` units (default 1).
Graduated rate: `{ meteredFeatureId, billingUnits?, tierBehavior: "graduated", tiers: [{ to: number | "inf", creditCost: number }] }`: the credit cost steps as usage in the cycle grows. The last tier must be `"inf"`.
Each entry may also carry `dimensions` and `multipliers` to price by event properties. See [Rate cards and dimensions](/documentation/modelling-pricing/credit-systems#rate-cards-and-dimensions).
**For `ai_credit_system` features.** Percentage added on top of the model's cost, eg `30`. Use `-100` to make usage free.
**For `ai_credit_system` features.** Markup per provider, keyed by the first part of the model ID: `{ openrouter: { markup: 25 } }`.
**For `ai_credit_system` features.** Markup per model, keyed by model ID: `{ "openai/gpt-4o-mini": { markup: 20 } }`. For your own models, add `inputCost` and `outputCost` in dollars per million tokens. See [AI credit systems](/documentation/modelling-pricing/credit-systems#ai-credit-systems).
Archive the feature. Leave it out to keep it as is.
Written by the CLI after a push. Leave it there. Changing `featureId` next to it renames the feature.
Stripe mapping: `{ stripe: { productId, meterId } }`. Only pulled with `atmn pull --include-mappings`.
### Feature types
**Boolean**: simple on/off flag.
```ts theme={null}
export const sso = feature({
featureId: "sso",
name: "SSO Authentication",
type: "boolean",
});
```
**Metered, consumable**: used up and refilled (messages, API calls).
```ts theme={null}
export const messages = feature({
featureId: "messages",
name: "Messages",
type: "metered",
consumable: true,
});
```
**Metered, non-consumable**: ongoing usage (seats, storage).
```ts theme={null}
export const seats = feature({
featureId: "seats",
name: "Seats",
type: "metered",
consumable: false,
});
```
**Credit system**: maps several metered features to credit costs.
```ts theme={null}
export const basicModel = feature({
featureId: "basic_model",
name: "Basic Model",
type: "metered",
consumable: true,
});
export const premiumModel = feature({
featureId: "premium_model",
name: "Premium Model",
type: "metered",
consumable: true,
});
export const credits = feature({
featureId: "credits",
name: "AI Credits",
type: "credit_system",
creditSchema: [
{ meteredFeatureId: basicModel.featureId, creditCost: 1 },
{ meteredFeatureId: premiumModel.featureId, creditCost: 5 },
],
});
```
If you set the price per credit to 1 cent, credits become monetary credits (eg, 5 credits = \$0.05 per premium message).
**AI credit system**: bills LLM usage at the model's real cost plus a markup. Track usage with [`track_tokens`](/api-reference/balances/trackTokens).
```ts theme={null}
export const aiCredits = feature({
featureId: "ai_credits",
name: "AI Credits",
type: "ai_credit_system",
defaultMarkup: 30,
});
```
## Plans
Plans combine features with pricing to create your subscription tiers, add-ons and top-ups.
### `plan(config)`
Unique identifier used in checkout and subscription APIs.
Name of this version of the plan, eg `"v1"`. See [versions](#versions).
Whether this is the version new customers get. Exactly one version of each plan is active.
Display name shown in pricing tables and billing.
Optional description of the plan.
Base subscription price:
* `amount: number`: price amount (eg, `20` for \$20)
* `interval: string`: `"week"` | `"month"` | `"quarter"` | `"semi_annual"` | `"year"` | `"one_off"`
* `intervalCount?: number`: intervals per billing cycle, eg `3` with `"month"` for every 3 months. Defaults to `1`.
* `additionalCurrencies?: array`: amounts in [other currencies](/documentation/concepts/plans#multiple-currencies), eg `[{ currency: "eur", amount: 18 }]`
Array of plan items defining what's included. See [plan items](#plan-items).
Automatically assign this plan to new customers. Typically used for free plans.
Allow this plan to be bought alongside other plans (instead of replacing them).
Free trial before billing starts:
* `durationLength: number`: eg, `14`
* `durationType: string`: `"day"` | `"month"` | `"year"`
* `cardRequired: boolean`: whether a card is needed to start the trial
* `onEnd?: string`: `"bill"` (default) charges the customer when the trial ends. `"revert"` puts them back on their previous plan.
Group related plans together. Plans in the same group replace each other on upgrade/downgrade.
`variant()` entries for this plan, eg an annual version. See [plan variants](#plan-variants).
`license()` entries for plans this plan hands out per seat. See [licenses](#licenses).
Default [billing controls](/documentation/customers/billing-controls#plan-level-defaults) for every customer on this plan: `autoTopups`, `spendLimits`, `usageLimits`, `usageAlerts` and `overageAllowed`. Each is an array with one entry per feature, using the same fields as the API.
`{ ignorePastDue: true }` keeps this plan's balances resetting on schedule even when the customer is past due.
Any key-value data you want to keep on the plan. Shared by all versions.
Archive the plan. Leave it out to keep it as is.
Written by the CLI after a push. Leave it there. Changing `planId` next to it renames the plan.
Stripe and RevenueCat mappings: `{ stripe: { productId, additionalProductIds }, revenuecat: { products } }`. Only pulled with `atmn pull --include-mappings`.
### Versions
Each version of a plan is its own `plan()` entry with the same `planId` and a different `versionSlug`. One version is `active: true`; that's the one new customers get. Customers on an older version stay on it.
To change a plan's price for new customers only, add a new version and set the old one to `active: false`:
```ts theme={null}
export const proV2 = plan({
planId: "pro",
versionSlug: "v2",
active: true,
name: "Pro",
price: { amount: 25, interval: "month" },
items: [ ... ],
});
export const proV1 = plan({
planId: "pro",
versionSlug: "v1",
active: false,
name: "Pro",
price: { amount: 20, interval: "month" },
items: [ ... ],
});
```
To change a plan for everyone on it, edit its existing entry instead. If customers are on that version, Autumn drafts a migration and `atmn push` prints the link to run it.
After a push, the CLI adds an `internalId` to each plan and feature in your config. Leave it there. It's how the CLI knows to rename a plan instead of deleting and recreating it.
## Plan items
Plan items define what each plan includes: usage limits, pricing and billing behavior. They are plain objects in the plan's `items` array.
The `featureId` of the feature to include.
Amount included for free. Leave it out for boolean features.
Give unlimited usage of this feature.
How often the included amount refills:
* `interval: string`: `"minute"` | `"hour"` | `"day"` | `"week"` | `"month"` | `"quarter"` | `"semi_annual"` | `"year"` | `"one_off"`
* `intervalCount: number`: defaults to `1`
Pricing for usage beyond the included amount. See [pricing patterns](#pricing-patterns) below.
How to handle mid-cycle quantity changes on prepaid items:
* `onIncrease:` `"prorate_immediately"` | `"bill_immediately"` | `"prorate_next_cycle"` | `"bill_next_cycle"`
* `onDecrease:` `"prorate_immediately"` | `"prorate_next_cycle"` | `"no_prorations"`
Leave it out to prorate immediately on both. `pull` only writes it when a plan uses something else.
Carry unused balance forward:
* `max: number`: maximum rollover amount. Leave it out for no limit.
* `maxPercentage: number`: maximum as a percentage (0-100) of the included amount. Use this or `max`, not both.
* `expiryDurationType:` `"month"` | `"forever"`
* `expiryDurationLength: number`: ignored if type is `"forever"`
`{ threshold: number }`: bill this many units each time unpaid usage reaches it, instead of waiting for the end of the cycle. Flat usage-based prices only.
For [entity plans](/documentation/modelling-pricing/entity-plans): pool every entity's balance for this feature into one shared customer balance.
Override the feature's settings for customers on this plan. For credit systems, `{ creditSchema: [...] }` replaces the rate card. For AI credit systems, `{ markups: { defaultMarkup, providerMarkups, modelMarkups } }` replaces the markups.
### Pricing patterns
The `price` object on a plan item supports different billing models:
**Usage-based**: charge based on actual usage.
```ts theme={null}
{
featureId: messages.featureId,
included: 1000,
reset: { interval: "month" },
price: {
amount: 1,
billingUnits: 1000,
interval: "month",
billingMethod: "usage_based",
},
}
```
**Prepaid**: customer buys a fixed quantity upfront.
```ts theme={null}
{
featureId: credits.featureId,
price: {
amount: 5,
billingUnits: 100,
interval: "month",
billingMethod: "prepaid",
},
}
```
**Tiered**: price changes based on usage volume.
```ts theme={null}
{
featureId: apiCalls.featureId,
reset: { interval: "month" },
price: {
tiers: [
{ to: 1000, amount: 0.01 },
{ to: 10000, amount: 0.008 },
{ to: "inf", amount: 0.005 },
],
interval: "month",
billingMethod: "usage_based",
},
}
```
#### Price fields
Price per `billingUnits`. Use this or `tiers`, not both.
Tiered pricing. Each entry: `{ to: number | "inf", amount: number, flatAmount?: number }`. `flatAmount` adds a fixed charge for the tier. Use this or `amount`, not both.
`"graduated"`: each tier is priced at its own rate. `"volume"`: the tier the total lands in prices everything. See [volume-based tiers](/documentation/modelling-pricing/volume-based-tiers).
Amounts in [other currencies](/documentation/concepts/plans#multiple-currencies). For flat prices: `[{ currency: "eur", amount: 0.09 }]` at the price level. For tiered prices, set per tier: `{ to: 1000, amount: 0.01, additionalCurrencies: [{ currency: "eur", amount: 0.009 }] }`.
`"usage_based"` | `"prepaid"`
`"week"` | `"month"` | `"quarter"` | `"semi_annual"` | `"year"` | `"one_off"`. Use `"one_off"` for one-time charges.
Intervals per billing cycle, eg `3` with `"month"` to bill every 3 months.
Units per price. Eg, \$5 per 100 credits = `amount: 5, billingUnits: 100`.
Maximum quantity that can be bought.
## Plan variants
A variant is a plan that starts from another plan and changes a few things, eg an annual version of Pro. Each one is a `variant()` entry listed in the base plan's `variants`. See [plan variants](/documentation/modelling-pricing/plan-variants) for how they work.
### `variant(config)`
The variant's own plan ID, eg `"pro_annual"`.
Name of this version of the variant, eg `"v1"`.
Display name, eg `"Pro Annual"`.
What the variant changes from the base plan:
* `price`: a new base price, or `null` to remove it
* `items`: replaces the whole items list
* `addItems` / `removeItems`: add plan items, or remove the base plan's by `{ featureId, billingMethod?, interval? }`. Use these instead of `items` to change only some items.
* `freeTrial`: a different trial, or `null` for none
* `billingControls`: different default billing controls
* `upsertLicenses` / `removeLicenses`: change the base plan's [licenses](#licenses)
Archive the variant. Leave it out to keep it as is.
Written by the CLI after a push. Leave it there.
```ts theme={null}
export const proAnnual = variant({
variantPlanId: "pro_annual",
versionSlug: "v1",
name: "Pro Annual",
customize: {
price: { amount: 200, interval: "year" },
},
});
export const pro = plan({
planId: "pro",
versionSlug: "v1",
active: true,
name: "Pro",
price: { amount: 20, interval: "month" },
items: [ ... ],
variants: [proAnnual],
});
```
## Licenses
A license links a plan to another plan that each seat gets, eg a Team plan that hands out a Seat plan per member. Each one is a `license()` entry in the parent plan's `licenses`. See [entity plans](/documentation/modelling-pricing/entity-plans#licenses).
### `license(config)`
The `planId` of the plan each seat gets.
Which version of that plan, eg `"v1"`.
Number of seats included for free.
Cap seats at the included amount. Must be `true` for now.
Change what a seat gets on this parent plan: `price`, `addItems` and `removeItems`, with the same shapes as [variants](#plan-variants).
```ts theme={null}
export const team = plan({
planId: "team",
versionSlug: "v1",
active: true,
name: "Team",
licenses: [
license({
licensePlanId: seat.planId,
versionSlug: seat.versionSlug,
included: 1,
}),
],
});
```
## Rewards
Rewards are discounts and free usage that customers unlock with a promo code, or through a referral program. They go in the `rewards` list. See [rewards and referrals](/documentation/modelling-pricing/rewards).
### `coupon(config)`
A discount on invoices.
Unique identifier for the coupon.
Display name.
`"percentage_discount"` | `"fixed_discount"`
The percentage off (up to 100) or the fixed amount off.
How long it applies: `{ type: "one_off" | "months" | "forever", length: number | null }`. `length` is the number of months for `"months"`, and `null` otherwise.
Plans the coupon applies to, or `null` for all plans.
Codes customers can redeem: `[{ code: "SAVE20", globalMaxRedemption?: number | null, firstTimeTransaction?: boolean | null }]`.
### `featureGrant(config)`
Free usage of one or more features, unlocked with a promo code.
Unique identifier for the grant.
Display name.
What the customer gets: `[{ featureId, included: number | null, expiry: { type: "day" | "week" | "month" | "year", length: number } | null }]`. Use `included: null` for boolean features and `expiry: null` for a grant that never expires.
Codes customers can redeem: `[{ code: "WELCOME", maxUses: number | null }]`. `null` means unlimited uses.
```ts theme={null}
export const launchDiscount = coupon({
id: "launch20",
name: "Launch discount",
type: "percentage_discount",
value: 20,
duration: { type: "months", length: 3 },
planIds: null,
promoCodes: [{ code: "LAUNCH20" }],
});
export const welcomeCredits = featureGrant({
id: "welcome_credits",
name: "Welcome credits",
grants: [
{
featureId: credits.featureId,
included: 500,
expiry: { type: "month", length: 1 },
},
],
promoCodes: [{ code: "WELCOME", maxUses: null }],
});
```
## Referral programs
A referral program gives a reward to customers who bring in new customers. They go in the `referralPrograms` list.
### `referralProgram(config)`
Unique identifier, used when creating and redeeming referral codes.
The `id` of the coupon or feature grant to give, as a string. `coupon()` and `featureGrant()` return a wrapped entry, so you can't read `.id` off them.
When the reward is given: `"customer_creation"` (when the new customer signs up) or `"checkout"` (when they buy a plan).
Who gets the reward: `"referrer"` only, or `"all"` (both the referrer and the new customer).
How many times one referrer can be rewarded. `null` for no limit.
Plans that trigger the reward. Required when `redeemOn` is `"checkout"`.
Skip the reward when the new customer starts a trial.
```ts theme={null}
export const referrals = referralProgram({
id: "friend_referral",
rewardId: "launch20",
redeemOn: "customer_creation",
receivedBy: "all",
maxRedemptions: 10,
});
```
## Settings
The `settings` block manages organization-wide flags. Only the flags you state are changed. If you stop stating a flag, it keeps its current value; to turn one off, state it as `false`.
```ts theme={null}
export default atmn({
features: [...],
plans: [...],
settings: {
invoiceMemos: true,
blockOverdueEntitlements: true,
},
});
```
| Flag | What it does |
| -------------------------- | ----------------------------------------------------------- |
| `cancelOnPastDue` | Automatically cancel subscriptions when payment is past due |
| `blockOverdueEntitlements` | Block access to features while a plan is past due |
| `reverseDeductionOrder` | Deduct from the newest balance first instead of the oldest |
| `invoiceMemos` | Include line-item memos on Stripe invoices |
| `disableOverageBilling` | Stop posting usage overage line items to Stripe |
| `paydownOverages` | Let resets and top-ups pay down unbilled overages |
| `automaticTax` | Turn on Stripe Tax for automatic tax calculation |
| `multiCurrency` | Allow prices and billing in more than one currency |
All default to `false`.
## Full example
A complete config with a free plan, a paid plan with a trial, and a credits top-up add-on:
```ts autumn.config.ts theme={null}
import { atmn, feature, plan } from "atmn";
// Features
export const messages = feature({
featureId: "messages",
name: "Messages",
type: "metered",
consumable: true,
});
export const seats = feature({
featureId: "seats",
name: "Seats",
type: "metered",
consumable: false,
});
export const sso = feature({
featureId: "sso",
name: "SSO",
type: "boolean",
});
// Plans
export const free = plan({
planId: "free",
versionSlug: "v1",
active: true,
name: "Free",
autoEnable: true,
items: [
{
featureId: messages.featureId,
included: 100,
reset: { interval: "month" },
},
],
});
export const pro = plan({
planId: "pro",
versionSlug: "v1",
active: true,
name: "Pro",
price: { amount: 20, interval: "month" },
freeTrial: {
durationLength: 14,
durationType: "day",
cardRequired: true,
},
items: [
{
featureId: messages.featureId,
included: 10000,
reset: { interval: "month" },
price: {
amount: 1,
billingUnits: 1000,
interval: "month",
billingMethod: "usage_based",
},
},
{
featureId: seats.featureId,
included: 3,
price: {
amount: 10,
interval: "month",
billingMethod: "prepaid",
},
},
{ featureId: sso.featureId },
],
});
export const messageTopUp = plan({
planId: "message_top_up",
versionSlug: "v1",
active: true,
name: "Message Top-Up",
addOn: true,
items: [
{
featureId: messages.featureId,
price: {
amount: 5,
billingUnits: 1000,
interval: "one_off",
billingMethod: "prepaid",
},
},
],
});
export default atmn({
features: [messages, seats, sso],
plans: [free, pro, messageTopUp],
});
```
# Getting started
Source: https://docs.useautumn.com/cli/getting-started
Set up the CLI, connect to Autumn, and sync your pricing config
The `atmn` CLI keeps your pricing in code. You write your features and plans in an `autumn.config.ts` file, preview what would change, and push it to Autumn with one command.
This page covers `atmn` 2. If you have a config from `atmn` 1.x, see [upgrading from 1.x](#upgrading-from-1x).
## Set up a project
Run `atmn init` in the root folder of your project:
```bash bun theme={null}
bunx atmn init
```
```bash npm theme={null}
npx atmn init
```
```bash pnpm theme={null}
pnpm dlx atmn init
```
`init` does the whole setup in one go:
1. **Connects you to Autumn.** If you don't have a key yet, it asks how you want to connect: sign in (opens your browser), or go keyless (creates a sandbox for you right away, no account needed).
2. **Creates your config folder.** By default that's `autumn/`, holding `autumn.config.ts` next to `features.ts`, `plans.ts` and `rewards.ts`. In a monorepo it asks where the folder should go (default `packages/autumn`) and what to call the package.
3. **Adds `atmn` to your `package.json`** and installs it, because the config imports from it. It also adds an `atmn` script and a small `"atmn"` field to your root `package.json`, so every command can find the config from anywhere in your repo.
4. **Pulls what's already in Autumn** into the config files.
5. **Installs the Autumn skills** next to the config, so your coding agent knows how to work with the CLI.
Your keys end up in a `.env` file at the root of your repo:
```bash .env theme={null}
AUTUMN_SECRET_KEY=am_sk_test_...
AUTUMN_PROD_SECRET_KEY=am_sk_live_...
```
Went keyless? Your sandbox has no owner yet. Link it to an account within a few days with `bunx atmn login --claim you@example.com`. The key you already have keeps working.
You can check your setup at any time with `bunx atmn env`. It shows which organization, environment and key your commands will use.
## Log in on its own
You don't need `init` to connect. `atmn login` opens your browser, lets you pick an organization, and writes both keys to your `.env`:
```bash theme={null}
bunx atmn login
```
Add `--keyless` to create a sandbox without an account instead.
## Push and pull
Once you have a config, sync it with Autumn:
```bash theme={null}
# Preview what would change
bunx atmn push
# Apply the changes
bunx atmn push --yes
# Pull what's in Autumn into your local files
bunx atmn pull
```
`push` reads your config, compares it with what's in Autumn, and shows what would be created, updated or deleted. Nothing changes until you add `--yes`. If a change affects a plan that already has customers, Autumn drafts a migration for you and `push` prints the link to run it.
After a push, the CLI writes an `internalId` into each feature and plan in your config. Leave it there. It's how the CLI knows to rename something instead of deleting and recreating it.
`pull` fetches your features, plans and rewards from Autumn and writes them into `features.ts`, `plans.ts` and `rewards.ts`, keeping your formatting where it can. If you don't have a config yet, it asks where to create one.
Already made plans in the dashboard? Run `bunx atmn pull` to turn them into a config.
## Environments
All commands use your **sandbox** by default. Add `-p` to target production:
```bash theme={null}
# Push to production
bunx atmn push -p --yes
# Pull from production
bunx atmn pull -p
```
`push -p` only previews the changes. Add `--yes` to apply them to production.
You can also create extra sandboxes for testing, each with its own plans and customers:
```bash theme={null}
bunx atmn sandbox create staging --use # create one and switch to it
bunx atmn sandbox use --clear # switch back to your main sandbox
```
See the [command reference](/cli/commands#sandboxes) for the full list.
## Upgrading from 1.x
`atmn` 2 uses a new config format. If you run a 1.x config, the CLI stops and tells you so instead of guessing. To move over:
1. Note any changes you made to your config that aren't in Autumn yet.
2. Rebuild the config from your organization. This rewrites `autumn.config.ts` and the `features.ts`, `plans.ts` and `rewards.ts` beside it. Other files are left alone.
```bash theme={null}
bunx atmn pull --overwrite --yes
```
3. Re-apply your pending changes in the new format, then `bunx atmn push`.
What changed:
| 1.x | 2.x |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `feature({ id: "messages" })` | `feature({ featureId: "messages" })` |
| `plan({ id: "pro" })` | `plan({ planId: "pro", versionSlug: "v1", active: true })` |
| `item({ ... })` inside `items` | Plain objects inside `items`. There is no `item()` helper. |
| Named exports only | The file ends with `export default atmn({ features, plans })` |
| Plan versions handled by the CLI on push | Each version is its own `plan()` entry with the same `planId`. See [versions](/cli/config#versions). |
| `atmn push` applied straight away | `atmn push` only previews. `atmn push --yes` applies. |
| `atmn pull --force` | `atmn pull --overwrite --yes` |
| `atmn nuke` | `atmn reset --yes` |
| `atmn customers`, `atmn plans`, `atmn features`, `atmn events` | Removed. Use [`atmn api`](/cli/commands#api) to call any endpoint. |
| `atmn preview`, `atmn logout`, `atmn config` | Removed. |
**Next: Configuration reference**
Learn how to define features, plans and pricing in your `autumn.config.ts`.
Every builder and field available in autumn.config.ts
# Balances
Source: https://docs.useautumn.com/documentation/concepts/balances
Understanding how feature balances work in Autumn
Balances determine what features a customer can use, and track how much they have used.
Balances are created in two ways:
1. **Automatically from plans**: When a plan is attached to a customer, each feature in the plan becomes a balance for that customer.
2. **Standalone via API**: You can create balances directly using the API, independent of any plan. See [Managing Balances](/documentation/customers/managing-balances) for details.
```mermaid theme={null}
flowchart LR
F[Feature] -->|added to plan| PF[Plan Item]
PF -->|plan attached to customer| B[Customer Balance]
```
## Core Fields
Each balance has the following key fields:
| Field | Description |
| ---------------- | ------------------------------------------------------- |
| `included_usage` | The amount granted by the plan, or a purchased quantity |
| `balance` | The remaining amount available |
| `usage` | The amount that has been consumed |
When you retrieve a customer, their balances will be included in the response.
For the complete balance schema including reset configuration, overage settings, and breakdown details, see the [Get Customer API reference](/api-reference/customers/get-customer).
```json theme={null}
{
"balances": {
"messages": {
"granted_balance": 1000,
"current_balance": 750,
"usage": 250,
"unlimited": false,
"reset": {
"interval": "month",
"resets_at": 1745193600000
}
},
"premium-support": {
"unlimited": true
}
}
}
```
## Feature Types and Balances
When you create a feature, you define its type. This affects how balances behave.
### Consumable Features
Features that are used up and can be replenished. Examples: credits, API requests, AI tokens.
Consumable features support **reset intervals** - the balance resets to the granted amount on a regular schedule.
Available reset intervals:
* `hour`, `day`, `week`, `month`, `quarter`, `semi_annual`, `year`
* `one_off` - the balance never resets (useful for one-time grants or top-ups)
### Non-Consumable Features
Features with persistent, continuous usage. Examples: seats, workspaces, storage.
Non-consumable features don't reset. Instead, they support **proration** when quantities change mid-billing cycle.
### Credit Systems
A [credit system](/documentation/modelling-pricing/credit-systems) lets multiple features draw from a single shared balance.
When you check or track usage, you use the underlying feature ID (e.g., `premium_message`), but the balance is deducted from the credit system.
When you track usage for a feature in a credit system, Autumn:
1. Looks up the credit cost for that feature that you defined
2. Multiplies the usage value by the credit cost
3. Deducts from the credit system balance
For example, if you have a credit system with a credit cost of 2 credits per API request, and a customer uses 10 API requests, Autumn will deduct 20 credits from the balance.
## Positive and Negative Balances
A balance can be positive or negative:
* **Positive balance**: Customer has unused allowance remaining
* **Negative balance**: Customer has used more than their allowance (only possible if [overage](/documentation/concepts/plan-items#priced-features) is enabled)
Features can only have a negative balance if they have a usage-based price that allows overage. Otherwise, tracking stops when balance reaches 0.
## Balance Stacking
A single feature can have balances from multiple sources - different plans, add-ons, or standalone grants.
Autumn combines these into a single parent balance while tracking each source separately in a `breakdown` array, grouped by plan and interval.
> **Example**
> A customer has a feature, `messages`, with the following balances:
>
> * Pro plan: 500 messages per month
> * Top-up add-on: 200 lifetime messages
>
> Their total available balance is 700 `messages`.
### The Breakdown Array
Each balance source is tracked separately in the `breakdown` array. This lets you see exactly where the balance came from and how much remains from each source.
```json expandable theme={null}
{
"balances": {
"messages": {
"included_usage": 700,
"balance": 700,
"usage": 0,
"breakdown": [
{
"id": "ent_abc123",
"product_id": "pro",
"included_usage": 500,
"balance": 500,
"usage": 0,
"interval": "month",
"next_reset_at": 1745193600000
},
{
"id": "ent_def456",
"product_id": "top-up",
"included_usage": 200,
"balance": 200,
"usage": 0,
"interval": "one_off",
"next_reset_at": null
}
]
}
}
}
```
### Deduction Order
When usage is tracked, Autumn deducts from balances in a specific order based on their reset interval. **Shorter intervals are deducted first** by default.
The order is: `hour` (shortest) > `day` > `week` > `month` > `quarter` > `semi_annual` > `year` > `one_off` (lifetime - never resets).
Balances with the same interval are deducted by `expires_at`, soonest first. Balances without an expiry are deducted last.
This ensures that expiring balances are used before permanent ones.
If you need the deduction order reversed (longest interval first), please [contact us](https://discord.gg/STqxY92zuS).
> **Example**
> Suppose a customer has two balances for messages: 500 monthly and 200 lifetime. They have a total of 700 messages.
>
> * The customer uses 400 messages. The monthly balance (the shorter interval) is used up first, leaving 100 in monthly and 200 in lifetime (300 total).
> * The customer uses another 200 messages. The remaining 100 monthly is depleted, and the next 100 is deducted from the lifetime balance. Now, monthly is 0, lifetime is 100 (100 total).
> * On the next cycle, the monthly balance resets to 500, and the lifetime remains at 100, for a new total of 600.
# Features
Source: https://docs.useautumn.com/documentation/concepts/features
Learn about features in Autumn and how to create them
Features represent the parts of your product that you want to control access to, based on the pricing plan a customer is on. There are 2 key types of features you can create:
* **Metered features**: features that require you to keep track of a usage balance (eg, credits, API requests)
* **Boolean features**: features that can be either enabled or disabled (eg, access to a premium analytics dashboard).
When you create a feature, you can set a display name, and it's ID. This will be used to identify the feature when you make API calls to Autumn, to check or tracking usage of the feature.
## Metered features
Metered features can either be `consumable` or `non-consumable`.
* **Consumable**: features that can be used up and replenished, either by recurring resets or purchases. For example, credits, API requests.
* **Non-consumable**: features that are used persistently. For example, seats, storage, workspaces.
When adding features to a plan, you will be able to set reset cycles for `consumable` features, and proration behavior for `non-consumable` features.
Under the "advanced" section of the feature creation sheet, you can also define [event names](/documentation/customers/tracking-usage#using-event-names). This gives you more control over how events interact with customer balances in Autumn.
Metered features can each act as their own, standlone balance, or be added to a [credit system](/documentation/modelling-pricing/credit-systems). This lets you define credit costs per feature, and let many features draw from a common credit balance.
## Boolean features
Boolean features are for your features that can be either enabled or disabled. Think of them like feature flags to gate specific parts of your application based on what product a user has (eg, access to a premium analytics dashboard).
For these features, there is no configuration needed to be set. If you add them to a product, users on that product will be granted [access to the feature](/documentation/customers/check#checking-boolean-features).
# How It Works
Source: https://docs.useautumn.com/documentation/concepts/overview
How features, plans, subscriptions and balances fit together
Autumn's data model has a clear pipeline: you define **features**, bundle them into **plans** with pricing, and when a plan is attached to a customer, it creates a **subscription** and provisions **balances** that you can check and track in real-time.
```mermaid actions={false} theme={null}
%%{init: {'flowchart': {'padding': 6, 'nodeSpacing': 10, 'rankSpacing': 20, 'subGraphTitleMargin': {'top': 4, 'bottom': 12}}} }%%
flowchart LR
subgraph features["**Features**"]
F3["AI Credits"]:::credit
end
subgraph plan["**Plan**"]
direction TB
subgraph price["Price"]
P1["$200/year"]:::pricing
end
subgraph planItems["Plan items"]
PI1["200 AI credits/month"]:::credit
end
price ~~~ planItems
end
subgraph customer["**Customer**"]
direction TB
subgraph customerPlans["Subscription"]
C1["$200/year"]:::pricing
end
subgraph balances["Balances"]
B1["146/200 AI credits left"]:::credit
end
customerPlans ~~~ balances
end
features ~~~ plan ~~~ customer
classDef credit fill:#22c55e30,stroke:#22c55e
classDef pricing fill:#ec489930,stroke:#ec4899
style features fill:#eab30820,stroke:#eab308
style plan fill:#7c3aed10,stroke:#7c3aed
style customer fill:#0ea5e910,stroke:#0ea5e9
style price fill:none,stroke:none
style planItems fill:none,stroke:none
style customerPlans fill:none,stroke:none
style balances fill:none,stroke:none
```
## Features
Features represent the parts of your product you want to control access to. There are three types: **boolean** (on/off flags like premium analytics), **consumable** (usage that resets, like API requests or credits), and **non-consumable** (persistent quantities like seats or storage).
Features are the atomic building blocks — everything else is built on top of them.
Learn about feature types and how to create them
## Plans
Plans bundle features together with a base price. Each plan represents a distinct pricing tier or package you offer — free, pro, enterprise, or any add-on. You define which features are included, how they're priced, and any properties like trials or auto-enable.
Learn about plan pricing, properties and groups
## Plan Items
When you add a feature to a plan, it becomes a **plan item** with its own configuration. Included items grant a usage amount at no extra cost. Priced items add billing — either prepaid or usage-based — with options for billing units, tiers, and proration.
Plan items are where the "what" (features) meets the "how much" (pricing).
Configure grants, pricing and usage models
## Subscriptions
When you attach a plan to a customer, Autumn creates a Stripe subscription under the hood and provisions balances for each feature in the plan. Subscriptions track status (active, trialing, past\_due, etc.) and handle the payment lifecycle.
How Autumn manages Stripe subscriptions
## Balances
Balances are the customer-facing result of everything above. Each plan item becomes a balance that tracks what the customer has been granted, what they've used, and what remains. Balances from multiple sources (plans, add-ons, top-ups) stack together, with shorter-interval balances consumed first.
Your app interacts with Autumn primarily through balances — calling `/check` to gate access and `/track` to record usage.
Understand balance stacking, resets and deduction order
## Runtime
Once your features, plans and pricing are configured, your app interacts with Autumn through a few core endpoints.
Model your pricing plans in the Autumn UI, or through a config file. Define your free, paid and any add-on pricing tiers.
You can link features to these plans and define their usage limits: both recurring (monthly, yearly), one-time top ups, rollovers, etc.
The [attach](/api-reference/billing/attach) endpoint subscribes a customer to a plan or purchases a one-time product. It handles new subscriptions, upgrades, downgrades and add-ons — creating the Stripe subscription and provisioning balances automatically.
Once paid, Autumn grants access to the features on their plan.
When a customer tries to do something (eg, use a credit), [check](/api-reference/core/check) in real-time whether they're allowed to based on their active plans and remaining balance.
Set `send_event` to atomically deduct usage while checking.
If the customer is allowed access, let them use the feature. Afterwards, [track](/api-reference/core/track) the usage to update their balance, or bill them for any usage-pricing.
Autumn also provides endpoints to [get customer billing data](/api-reference/customers/getOrCreateCustomer) (subscriptions, balances, invoices, payment methods), open Stripe billing portal, display usage analytics, handle org billing, and more.
# Plan Items
Source: https://docs.useautumn.com/documentation/concepts/plan-items
Configure what customers get access to when they purchase a plan
When you add a feature to a plan, you define what customers on that plan can use, and how they should be charged for it.
There are 2 types of plan features:
* **Included Features**: features provided at no additional cost, either as a granted usage limit or a boolean flag
* **Priced Features**: features that are billed for, either as a prepaid quantity or a usage-based price. Priced features can also have an included amount.
When a customer purchases a plan, the items in the plan become [balances](/documentation/concepts/balances) under the customer.
## Included Features
#### Grant amount
For metered features, you can set a grant amount. This is how much of the feature can be used before the user hits their limit.
When the plan is enabled for a customer, their balance for this feature will be set to the grant amount. It can either be a fixed amount, or "unlimited".
Tracking usage will decrement the feature's balance, and once it's fully consumed, checking access will return `allowed: false`.
#### Reset interval
For metered features that are `consumable`, you can also set a reset interval. This is how often the feature's balance will be reset to the grant amount.
Reset intervals can be: `no reset`, `hour`, `day`, `week`, `month`, `quarter`, `semi_annual`, or `year`. You can also customize the `interval count` to be a custom number of intervals between resets (eg, 4 hours).
`no reset` can be used to grant one-time grants that never expire. This is commonly used for top-ups or one-time purchases.
You cannot set a reset interval for `non-consumable` features (eg, seats).
#### Advanced
You can additionally configure the following properties when adding a `consumable` included feature:
* **Reset existing usage when plan is enabled**: when the plan is enabled (eg on upgrade), their usage cycle will reset, and customer's balance will be reset to full grant amount. This is `true` by default.
**Example**
You have a free plan that allows users to send 10 messages per month. A user on this plan has used 3 messages so in the current month. Then, they upgrade to a pro plan that grants 100 messages per month.
If `Reset existing usage when plan is enabled` is set to `true`, their balance will be reset to 100 messages. If it's set to `false`, the 3 messages used will be carried over, and their new balance will be 97 messages.
* **Rollovers**: configure whether granted usage should rollover to the next cycle. You can configure rollover duration, and a maximum rollover cap. Rollover balances can be retrieved from the `balances` object.
* **Pooled**: on plans attached per entity (eg, per workspace), setting `pooled: true` makes each entity's grant join one shared customer-level balance instead of a per-entity one. A pooled item cannot carry a usage-based price — to charge overage on a pooled balance, add a separate usage-priced item (with no grant) alongside the pooled grant item.
Features that are `non-consumable` have no advanced configuration options.
## Priced Features
Priced features can be used to model usage-based pricing, where the price of the product is variable and tied to how much of a feature a user consumes. This combines the configuration options of a feature with a price.
#### Grant amount
Priced features can also have an optional grant amount. This is how much of the feature can be used before being billed.
Tracking usage for a feature will first decrement the grant amount. The price will then be applied to the remaining usage.
#### Price
A feature's price consists of:
* **Price**: the price of the feature per billing units of usage, or tiered by usage
* **Billing Units**: the packages of units that the price is defined for (eg, \$5 for 1000 credits)
* **Billing Interval**: how often the price is applied. This can be one-time, or recurring (eg, monthly, annually).
#### Usage model
When charging for a feature, you can choose between 2 methods:
* **Usage-based**: charge for how much of the feature is used end of billing period
* **Prepaid**: charge for a fixed quantity of the feature upfront, and draw from it as usage occurs.
#### Advanced
You can additionally configure the following properties when adding a priced feature:
* **Max purchase limit**: the maximum quantity of the feature that can be purchased. Once this limit is reached, checking access will return `allowed: false`. It includes the grant amount, if it exists.
* **Proration behavior**: for `non-consumable` features, you can choose whether to prorate the price when the quantity is increased or decreased. You can also choose whether to charge for that change immediately, or at the end of the billing period.
For priced `consumable` features, you can also set the `reset existing usage when plan is enabled` and `rollovers` properties, in the same way as included features.
# Plans
Source: https://docs.useautumn.com/documentation/concepts/plans
Learn about plans in Autumn and how to create them
Plans are the separate packages that define what your customers get and how much they should be billed for it. Each plan you create is a distinct combination of these features and prices.
For example, you can define a separate plan for all the pricing tiers (eg free plan, team plan, enterprise tier) you offer, or all your different price variations (annual billing, monthly billing, usage-based billing)
## Plan Price
When you create a plan, you can set its price:
* **Free** - no price, free to use
* **Paid, one-off** - a fixed amount a user will be charged. This is often used for one-time topups.
* **Paid, recurring** - a fixed amount a user will be charged per unit of time. This is often used for subscriptions.
* **Variable** - there is no fixed price for this plan. The plan is priced purely based on feature usage or quantity purchased.
## Multiple Currencies
Multi-currency pricing is currently in preview - contact us to enable it for your organization.
Plan prices are in your organization's default currency. To sell the same plan in other currencies, add `additional_currencies` wherever a price is defined - the base price, a priced feature, or each tier of a tiered price:
```json theme={null}
{
"plan_id": "pro",
"price": {
"amount": 20,
"interval": "month",
"additional_currencies": [
{ "currency": "eur", "amount": 18 },
{ "currency": "gbp", "amount": 16 }
]
}
}
```
Each amount is set explicitly per currency - Autumn does not apply exchange rates. Tier boundaries stay the same across currencies; only the amounts differ.
Each customer is billed in a single currency. You can set it when creating the customer, pass it on their first `attach`, or let it default to your organization's currency. Once a customer has paid in a currency, they're locked to it (Stripe requires this), and attaching a plan that doesn't offer a price in their currency fails with a `currency_mismatch` error.
Under the hood, Autumn creates a separate Stripe price per currency under the same Stripe product, on demand when a customer first attaches in that currency.
## Plan Features
Plans are made up of a list of [features](/documentation/concepts/features). These can be:
* **Included Features** - features that come with the plan for no additional cost. These can be boolean flags, or metered features with a limit.
* **Priced Features** - features that are billable based on usage of a feature. These can also have an included amount, and a prepaid or usage-based price.
When a plan is enabled for a customer, they will be granted access to the features defined in the plan.
## Plan Properties
**Auto-enable**
Set this is the plan should be automatically applied to a customer when they're created. This is typically for free plans that give customers access to a limited set of features without paying.
**Add ons**
Set this if the plan is an add on. This will mean it can be purchased together with other plans. If this flag is not set, then enabling a plan will replace the existing plan.
**Plan Groups**
If you have multiple groups of plans, and customers can have an active plan from each of these subscription groups at the same time, group the plans together. All plan tiers from the same group should have the same value.
**Example**
Let's say you have two different types of chatbots - one for customer support and one for sales. You want customers to be able to have both types of chatbots at the same time, but only one tier from each type.
You would create two plan groups:
1. "Customer Support Chatbots" (group: "support")
* Basic (\$49/month - 1,000 tickets)
* Advanced (\$149/month - 5,000 tickets)
* Enterprise (\$399/month - Unlimited tickets)
2. "Sales Chatbots" (group: "sales")
* Starter (\$79/month - 500 leads)
* Growth (\$199/month - 2,000 leads)
* Enterprise (\$499/month - Unlimited leads)
This way, a customer could have both the "Advanced Support" chatbot and the "Starter Sales" chatbot active at the same time, but they couldn't have both "Basic Support" and "Advanced Support" active together.
## Trials
Under plan settings, you can set a free trial for a plan. This will give customers a set amount of days to try the plan for free.
You can set whether a card is required for the free trial. If a card is not required, you can `attach` the plan to a customer without them having to go through a checkout flow or have a card on file. It will be automatically expired after the free trial period.
Each customer can only have access to a plan's trial **once**. If they try to attach the plan again, the trial will be ignored.
For a step-by-step guide on enabling, cancelling and ending trials, see our examples:
* [Trial - card required](/examples/trial-card-required)
* [Trial - card not required](/examples/trial-card-not-required)
When creating an Autumn customer, you can set the `customer.fingerprint` field (eg. device ID, browser fingerprint). This will limit the customer to one trial of the plan per fingerprint to prevent abuse.
## Plan Variants
Plan variants are named alternatives of a base plan. They inherit the base plan and store only the differences, such as a different billing interval, a different experiment package, or a different included usage ladder.
For example, an annual Pro plan can be modeled as a variant of monthly Pro:
```json theme={null}
{
"variant_plan_id": "pro_annual",
"name": "Pro Annual",
"customize": {
"price": { "amount": 200, "interval": "year" }
}
}
```
Variants are useful for monthly/annual pricing, A/B testing plan packages, and volume-based offers that share most of the same features.
# Stripe Sync
Source: https://docs.useautumn.com/documentation/concepts/stripe
How Autumn creates and manages Stripe objects under the hood
Autumn uses Stripe to create subscriptions and charge customers. You define plans, features and pricing in Autumn, and Stripe objects (customers, products, prices, subscriptions, invoices) are created automatically as they're needed.
You never need to manually create or interact with these objects in Stripe. Autumn handles the full lifecycle, and owns the customer state.
## Autumn and Stripe responsibilities
Autumn is the source of truth for a customer's state and what they can do. Stripe handles subscriptions and payments.
| Feature | Managed by | Details |
| -------------------------- | ---------- | ---------------------------------------------------------------------------- |
| Pricing and features | **Autumn** | Define and update in Autumn dashboard or API |
| Balances & credit ledgers | **Autumn** | Tracked in real-time via `/check` and `/track` |
| Usage metering | **Autumn** | Tracks usage internally, posts totals to Stripe at cycle end (if configured) |
| Feature gating | **Autumn** | `/check` evaluates access from Autumn's balances |
| Subscriptions and payments | **Stripe** | Autumn creates Stripe subscriptions and charges customers |
| Invoices & receipts | **Stripe** | Generated and delivered by Stripe |
| Checkout pages | **Stripe** | Keep Stripe Checkout pages for payment method collection |
| Refunds & disputes | **Stripe** | Issue refunds directly in Stripe dashboard |
Autumn syncs from Stripe automatically. If you update or cancel a subscription directly in the Stripe dashboard, Autumn will attempt to apply the same change to the corresponding customer state.
## Connecting Stripe
There are three ways to connect your Stripe account to Autumn:
| Method | When to use |
| ------------------- | ------------------------------------------------------------------------------------------- |
| **Default sandbox** | Automatic — every new Autumn org gets a Stripe Connect sandbox account with no setup needed |
| **OAuth** | Recommended for production. Connect via the deploy dialog in the Autumn dashboard |
| **Secret key** | Paste your Stripe secret key directly. Autumn creates a webhook endpoint automatically |
When disconnecting and reconnecting a different Stripe account, existing Stripe IDs on your plans become invalid. Autumn will recreate the products and prices in the new account when you `attach` it, but old customers and subscriptions will no longer be linked.
## Currency
Currency is set at the organization level and defaults to `usd`. You can change it when connecting Stripe or from the developer settings page.
All new Stripe prices are created in your configured currency. Changing the currency does not migrate existing subscriptions — those remain in the original currency. New prices and subscriptions going forward will use the updated currency.
## How customers map
When you create a customer in Autumn, you pass your own user ID (from your auth system, database, or any unique identifier) as the `customer_id`. This is the only ID you need — there's no separate "auth ID" concept.
```mermaid theme={null}
flowchart LR
A["Your app user_123"] -->|customers.getOrCreate| B["Autumn Customer user_123"]
B -->|on first billing call| C["Stripe Customer cus_abc123"]
```
By default, a Stripe customer is **not** created when you create an Autumn customer. The Stripe customer is created lazily — the first time a billing operation needs one (attaching a plan, opening the billing portal, setting up a payment method, etc.).
You can change this behavior:
* Pass `createInStripe: true` to create the Stripe customer immediately when the Autumn customer is created
* Pass `stripeId: "cus_abc123"` to link an existing Stripe customer instead of creating a new one
See [Creating Customers](/documentation/customers/creating-customers#stripe-integration) for details.
Once linked, the mapping is bidirectional:
* **Autumn → Stripe**: the Stripe customer ID is stored on the Autumn customer
* **Stripe → Autumn**: the Autumn customer ID is stored in the Stripe customer's `metadata`
## How products and prices map
The table below shows what maps to what:
| Autumn object | Stripe object |
| ----------------------------- | ------------------------------------ |
| Plan | Product |
| Fixed price (on a plan) | Price |
| Usage-based price (on a plan) | Separate Product + Price per feature |
| Customer | Customer |
| Subscription | Subscription |
In production, Stripe products and prices are lazily created — only on the first `attach` that uses them, not when you create or update a plan in Autumn. This means you can pre-map an Autumn plan to an existing Stripe product/price before the first attach, and Autumn will reuse it instead of creating a duplicate.
### Fixed prices
Each fixed price on a plan maps 1:1 to a Stripe price, attached to the plan's Stripe product.
### Usage-based prices
Usage-based prices are more complex. For each priced feature, Autumn creates a **separate Stripe product** (named `"Plan Name - Feature Name"`) with its own Stripe price. Depending on the billing model, Autumn may also create:
* An empty placeholder price to anchor the subscription
* A billing meter for in-arrear usage reporting
* A prepaid price for upfront usage billing
These are all managed automatically — you don't need to configure them.
### Renaming in Stripe
You can rename products and update their descriptions directly in the Stripe dashboard for display purposes (e.g., on invoices or the customer portal). Autumn won't overwrite these cosmetic changes.
Renaming in Stripe is purely cosmetic. The plan's ID and configuration are still managed in Autumn. For structural changes (prices, features, billing model), always use Autumn.
## Webhooks
Autumn automatically creates and manages webhook endpoints when you connect Stripe. You don't need to configure these manually.
Autumn listens for key Stripe events to keep state in sync:
| Event | What Autumn does |
| ------------------------------- | ----------------------------------------------------------------- |
| `checkout.session.completed` | Finalizes the plan attachment and provisions balances |
| `invoice.paid` | Records payment, triggers balance provisioning for deferred plans |
| `invoice.created` | Captures usage line items for arrear billing on renewal |
| `customer.subscription.updated` | Syncs subscription status (active, past\_due, canceled, etc.) |
| `customer.subscription.deleted` | Expires the plan and activates default plans if configured |
## Direct vs deferred execution
When you call `billing.attach`, Autumn takes one of two paths depending on whether the customer can be charged immediately:
**Direct (immediate):** The customer already has a payment method. Autumn creates the Stripe subscription, charges the customer, and provisions balances — all in a single API call.
**Deferred (checkout):** The customer doesn't have a payment method, or the payment requires additional action (like 3DS). Autumn creates a Stripe Checkout Session (or returns a `required_action`), stores the pending billing plan, and completes everything when the webhook confirms payment.
See [Payment Flow](/documentation/customers/payment-flow) for the full breakdown of redirect modes and checkout behavior.
## What to do in Stripe directly
While Autumn manages most of the Stripe lifecycle, there are a few things you should handle in Stripe:
| Task | Where |
| ---------------------------------------------------------- | ---------------- |
| Rename products for invoice display | Stripe dashboard |
| View payment logs and disputes | Stripe dashboard |
| Advanced subscription alterations (eg cycle anchors) | Stripe dashboard |
| Everything else (plans, pricing, subscriptions, customers) | **Autumn** |
# Subscriptions
Source: https://docs.useautumn.com/documentation/concepts/subscriptions
How Autumn manages customer subscriptions
Autumn uses Stripe subscriptions under the hood to handle recurring billing. When you attach a plan to a customer, Autumn creates the Stripe subscription and provisions feature balances automatically.
```mermaid theme={null}
flowchart LR
P[Plan] -->|attach| C[Customer]
C -->|creates| S[Stripe Subscription]
S -->|provisions| B[Balances]
```
When a subscription is created, Autumn provisions [balances](/documentation/concepts/balances) for each feature in the plan. Balances determine what the customer can access and track how much they've used. For example, a Pro plan might grant 1,000 API requests per month—this becomes a balance that decrements as the customer uses your product.
Balances can also be created for [credit systems](/documentation/modelling-pricing/credit-systems) (eg, \$10 credits per month) and boolean toggle features (eg, access to a premium analytics dashboard).
## Subscription statuses
| Status | Description |
| ----------- | ------------------------------------------------------ |
| `active` | Subscription is in good standing |
| `trialing` | Customer is in a free trial period |
| `past_due` | Payment failed, subscription needs attention |
| `scheduled` | Product will activate at end of current billing period |
| `expired` | Subscription has ended |
Learn about the checkout and payment flow
Handle upgrades, downgrades and cancellations
# Balance Locking
Source: https://docs.useautumn.com/documentation/customers/balance-locking
Reserve balance upfront with locks, then confirm or release when the operation completes
For operations where you don't know the final cost upfront — like AI completions, batch processing, or long-running jobs — you can **reserve** balance before the work starts, then **finalize** the reservation when it's done.
This is a three-step flow:
1. **Check with lock** — atomically check access and hold balance
2. **Do work** — run your operation
3. **Finalize** — confirm the deduction, adjust it, or release the hold
```mermaid theme={null}
sequenceDiagram
participant App
participant Autumn
App->>Autumn: check (lock: { enabled: true, lock_id })
Autumn-->>App: allowed: true (balance held)
App->>App: Do work (e.g. AI completion)
App->>Autumn: balances.finalize (lock_id, action)
Autumn-->>App: success: true
```
## Step 1: Check with lock
Pass the `lock` parameter to the check endpoint. This atomically checks if the customer has enough balance and reserves it in a single call.
```typescript TypeScript theme={null}
const response = await autumn.check({
customerId: "user_123",
featureId: "ai-tokens",
requiredBalance: 1000,
sendEvent: true,
lock: {
enabled: true,
lockId: "completion_abc123",
expiresAt: Date.now() + 5 * 60 * 1000, // 5 minutes
},
});
if (!response.allowed) {
// Customer doesn't have enough balance
}
// Balance is now held — proceed with the operation
```
```python Python theme={null}
response = await autumn.check(
customer_id="user_123",
feature_id="ai-tokens",
required_balance=1000,
send_event=True,
lock={
"enabled": True,
"lock_id": "completion_abc123",
"expires_at": int(time.time() * 1000) + 5 * 60 * 1000,
},
)
if not response.allowed:
# Customer doesn't have enough balance
pass
# Balance is now held — proceed with the operation
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/check" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"feature_id": "ai-tokens",
"required_balance": 1000,
"send_event": true,
"lock": {
"enabled": true,
"lock_id": "completion_abc123",
"expires_at": 1735689600000
}
}'
```
### Lock parameters
| Parameter | Type | Description |
| ------------ | --------- | ------------------------------------------------------------------------------------------------------- |
| `enabled` | `boolean` | Must be `true` to enable locking |
| `lock_id` | `string` | A unique identifier for this lock. You'll use this to finalize later. If omitted, Autumn generates one. |
| `expires_at` | `number` | Unix timestamp (ms) when the lock auto-expires and releases the held balance. Max 24 hours from now. |
Always set an `expires_at` to prevent balance from being held indefinitely if your finalize call fails. If a lock expires, the held balance is automatically released back to the customer.
## Step 2: Do your work
Run whatever operation you reserved balance for. The held balance is guaranteed to be available — no other concurrent request can consume it.
## Step 3: Finalize the lock
When the operation completes, call `balances.finalize` to resolve the held balance.
### Confirm the full amount
If the operation used exactly the amount you reserved, confirm the lock:
```typescript TypeScript theme={null}
await autumn.balances.finalize({
lockId: "completion_abc123",
action: "confirm",
});
```
```python Python theme={null}
await autumn.balances.finalize(
lock_id="completion_abc123",
action="confirm",
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/balances.finalize" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"lock_id": "completion_abc123",
"action": "confirm"
}'
```
### Release the hold
If the operation failed or was canceled, release the lock to return the held balance:
```typescript TypeScript theme={null}
await autumn.balances.finalize({
lockId: "completion_abc123",
action: "release",
});
```
```python Python theme={null}
await autumn.balances.finalize(
lock_id="completion_abc123",
action="release",
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/balances.finalize" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"lock_id": "completion_abc123",
"action": "release"
}'
```
### Adjust the final amount
If the actual usage differs from the reserved amount (common with AI tokens), pass `overrideValue` to adjust:
```typescript TypeScript theme={null}
// Reserved 1000 tokens, but only used 743
await autumn.balances.finalize({
lockId: "completion_abc123",
action: "confirm",
overrideValue: 743,
});
```
```python Python theme={null}
# Reserved 1000 tokens, but only used 743
await autumn.balances.finalize(
lock_id="completion_abc123",
action="confirm",
override_value=743,
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/balances.finalize" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"lock_id": "completion_abc123",
"action": "confirm",
"override_value": 743
}'
```
Autumn will reconcile the difference — returning the unused 257 tokens back to the customer's balance.
## Use cases
### AI completions
Reserve a token budget before starting generation, then finalize with the actual token count:
```typescript theme={null}
const lockId = `completion_${generateId()}`;
const { allowed } = await autumn.check({
customerId: "user_123",
featureId: "ai-tokens",
requiredBalance: 4000, // max_tokens
sendEvent: true,
lock: {
enabled: true,
lockId,
expiresAt: Date.now() + 60_000,
},
});
if (!allowed) return showUpgradePrompt();
const completion = await openai.chat.completions.create({
model: "gpt-4",
max_tokens: 4000,
messages: [{ role: "user", content: prompt }],
});
await autumn.balances.finalize({
lockId,
action: "confirm",
overrideValue: completion.usage.total_tokens,
});
```
### Long-running jobs
Reserve credits before queuing a job, release if the job fails:
```typescript theme={null}
const lockId = `job_${jobId}`;
const { allowed } = await autumn.check({
customerId: "user_123",
featureId: "compute-credits",
requiredBalance: 10,
sendEvent: true,
lock: {
enabled: true,
lockId,
expiresAt: Date.now() + 30 * 60_000, // 30 min timeout
},
});
if (!allowed) throw new Error("Insufficient credits");
try {
await runJob(jobId);
await autumn.balances.finalize({ lockId, action: "confirm" });
} catch (error) {
await autumn.balances.finalize({ lockId, action: "release" });
throw error;
}
```
## Compared to check + track
For simple operations where you know the cost upfront and the operation is fast, [check with `sendEvent`](/documentation/customers/check#checking-and-reserving-usage) is simpler — it deducts immediately in one call.
Use reservations when:
* The final usage amount is unknown at check time (e.g., AI token counts)
* The operation can fail after balance is deducted
* The operation takes significant time and you don't want another request to consume the same balance
# Billing Controls
Source: https://docs.useautumn.com/documentation/customers/billing-controls
Configure overage behavior, spend limits, usage alerts, and auto top-ups per customer or entity
Billing controls let you manage how individual customers (or [entities](/documentation/customers/feature-entities)) consume usage-based features. You can toggle whether overage is allowed, cap how much overage accumulates, hard-cap how much a feature can be used per time window, get notified when usage crosses a threshold, and automatically replenish prepaid balances — all configured per-customer via the API or viewed in the dashboard.
All billing controls are set through the `billingControls` field when [updating a customer](/api-reference/customers/updateCustomer) or [updating an entity](/api-reference/entities/updateEntity).
```typescript TypeScript theme={null}
await autumn.customers.update({
customerId: "user_123",
billingControls: {
overageAllowed: [{ featureId: "api_calls", enabled: true }],
spendLimits: [{ featureId: "api_calls", enabled: true, overageLimit: 5000 }],
usageLimits: [{ featureId: "api_calls", limit: 50, interval: "day" }],
usageAlerts: [{ featureId: "api_calls", threshold: 80, thresholdType: "usage_percentage", enabled: true }],
autoTopups: [{ featureId: "credits", enabled: true, threshold: 500, quantity: 1000 }],
},
});
```
```python Python theme={null}
await autumn.customers.update(
customer_id="user_123",
billing_controls={
"overage_allowed": [{"feature_id": "api_calls", "enabled": True}],
"spend_limits": [{"feature_id": "api_calls", "enabled": True, "overage_limit": 5000}],
"usage_limits": [{"feature_id": "api_calls", "limit": 50, "interval": "day"}],
"usage_alerts": [{"feature_id": "api_calls", "threshold": 80, "threshold_type": "usage_percentage", "enabled": True}],
"auto_topups": [{"feature_id": "credits", "enabled": True, "threshold": 500, "quantity": 1000}],
},
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers/update" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"billing_controls": {
"overage_allowed": [{"feature_id": "api_calls", "enabled": true}],
"spend_limits": [{"feature_id": "api_calls", "enabled": true, "overage_limit": 5000}],
"usage_limits": [{"feature_id": "api_calls", "limit": 50, "interval": "day"}],
"usage_alerts": [{"feature_id": "api_calls", "threshold": 80, "threshold_type": "usage_percentage", "enabled": true}],
"auto_topups": [{"feature_id": "credits", "enabled": true, "threshold": 500, "quantity": 1000}]
}
}'
```
## Overage Allowed
By default, whether a customer can use a feature beyond their included balance depends on the plan's pricing model. Features with [usage-based pricing](/documentation/modelling-pricing/usage-based-pricing) (pay-per-use) automatically allow overage — the customer keeps using and gets billed for the extra. Features without usage-based pricing (like a flat included allowance) block usage once the balance hits zero.
The `overageAllowed` control lets you override this default per customer or entity.
#### Default behavior (no override)
| Plan item pricing | Overage? |
| ------------------------------------- | ---------------------------------------------------------- |
| Usage-based (pay-per-use) | Allowed — customer is billed for overage |
| Included / prepaid (no overage price) | Blocked — `check` returns `allowed: false` at zero balance |
#### With `overageAllowed` enabled
Setting `overageAllowed` to `true` on a feature lets a customer consume beyond their included balance **even when the plan doesn't have usage-based pricing** for that feature. The balance goes negative, meaning you can track how much overage occurred, though no automatic overage charge is created.
> **Example**
> A customer is on a free plan with 100 API calls included (no overage pricing). Normally they'd be blocked at 0 remaining. You set `overageAllowed: true` for `api_calls`. Now they can keep using beyond 100, and you can decide how to handle the overage in your application (prompt an upgrade, bill manually, etc.).
```typescript TypeScript theme={null}
await autumn.customers.update({
customerId: "user_123",
billingControls: {
overageAllowed: [{
featureId: "api_calls",
enabled: true,
}],
},
});
```
```python Python theme={null}
await autumn.customers.update(
customer_id="user_123",
billing_controls={
"overage_allowed": [{
"feature_id": "api_calls",
"enabled": True,
}],
},
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers/update" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"billing_controls": {
"overage_allowed": [{
"feature_id": "api_calls",
"enabled": true
}]
}
}'
```
| Field | Type | Description |
| ------------ | ------- | -------------------------------------------- |
| `feature_id` | string | The feature to override overage behavior for |
| `enabled` | boolean | `true` to allow overage, `false` to block it |
#### Disabling overage on a pay-per-use feature
You can also use `overageAllowed` to **block** overage on a feature that would normally allow it. Setting `enabled: false` forces a hard cap at the included balance — even if the plan has usage-based pricing for that feature.
> **Example**
> A customer's plan includes 1,000 API calls with pay-per-use overage at \$1/1,000 calls. You set `overageAllowed: false` for `api_calls`. The customer is now blocked at 1,000 total calls — no overage charges will occur.
Setting `overageAllowed: false` is a hard override. It takes precedence over usage-based pricing on the plan. The customer will be blocked at zero remaining balance regardless of whether overage pricing exists.
#### How it interacts with spend limits
`overageAllowed` and [spend limits](#spend-limits) are complementary:
* **`overageAllowed`** answers: *can* usage go beyond the included balance?
* **Spend limits** answer: *how far* can overage go?
If both are set, `overageAllowed` is checked first. If overage is blocked (`enabled: false`), the spend limit is irrelevant. If overage is allowed, the spend limit caps how much overage can accumulate.
## Spend Limits
Spend limits cap how much overage a customer can accumulate on a usage-based feature. Once the cap is reached, `check` returns `allowed: false` and `track` stops deducting.
> **Example**
> A customer's plan includes 1,000 API calls with \$1 per 1,000 overage calls. You set a spend limit of 5,000 on `api_calls`. The customer can use up to 6,000 total calls (1,000 included + 5,000 overage), then they're blocked.
```typescript TypeScript theme={null}
await autumn.customers.update({
customerId: "user_123",
billingControls: {
spendLimits: [{
featureId: "api_calls",
enabled: true,
overageLimit: 5000,
}],
},
});
```
```python Python theme={null}
await autumn.customers.update(
customer_id="user_123",
billing_controls={
"spend_limits": [{
"feature_id": "api_calls",
"enabled": True,
"overage_limit": 5000,
}],
},
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers/update" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"billing_controls": {
"spend_limits": [{
"feature_id": "api_calls",
"enabled": true,
"overage_limit": 5000
}]
}
}'
```
| Field | Type | Description |
| --------------- | ------- | ------------------------------------------------ |
| `feature_id` | string | The feature to cap |
| `enabled` | boolean | Whether the spend limit is active |
| `overage_limit` | number | Maximum overage units beyond the included amount |
The `overage_limit` is measured in feature units, not dollars. An `overage_limit` of 5,000 on "API calls" means 5,000 additional API calls beyond the included allowance.
When both a spend limit and a plan-level max purchase exist for the same feature, the **spend limit takes precedence**. This lets you use max purchase as a default for all customers, then selectively raise or lower the cap per-customer.
For a deeper dive, see [Spend Limits & Usage Alerts](/documentation/modelling-pricing/spend-limits).
## Usage Limits
A usage limit is a **windowed hard cap**: at most `limit` units of a feature per `interval` window (day, week, month, or year), regardless of how much balance the customer has left or how the plan is priced. It's a throttle, that you or your customer may set.
Once usage reaches the cap inside the active window, `check` returns `allowed: false` and `track` stops deducting.
Usage limits cap *total usage* of a feature within a period: a sub-limit within an existing balance. They sit on top of the plan's allowance and apply even when there's balance remaining and even when the feature has no overage pricing.
`set_usage` sets a feature's balance but never touches usage-window counters. A capped feature stays capped: after `set_usage`, a customer whose window is exhausted still gets `allowed: false` until the window resets. To count usage against a window (including limits with conditions, which match on event properties), record usage normally with `track`.
The consumed counter belongs to the window, not to the limit's configuration — editing the limit never resets what's already been counted. To unblock a capped customer mid-window: **disable** the limit (`enabled: false`) to stop it gating while keeping its configuration, **raise** the limit (headroom becomes the new limit minus usage already counted), or **delete** it.
> **Example**
> A customer's plan includes **300 credits per month**, but you want to stop any single day from burning through them. Set a usage limit of **50 on `credits` with a `day` interval**. The customer still gets their 300 monthly credits, but can never spend more than 50 in a day.
```typescript TypeScript theme={null}
await autumn.customers.update({
customerId: "user_123",
billingControls: {
usageLimits: [{
featureId: "credits",
limit: 50,
interval: "day",
}],
},
});
```
```python Python theme={null}
await autumn.customers.update(
customer_id="user_123",
billing_controls={
"usage_limits": [{
"feature_id": "credits",
"limit": 50,
"interval": "day",
}],
},
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers/update" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"billing_controls": {
"usage_limits": [{
"feature_id": "credits",
"limit": 50,
"interval": "day"
}]
}
}'
```
| Field | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------------------ |
| `feature_id` | string | The feature to cap |
| `limit` | number | Maximum units allowed per window |
| `interval` | string | Window length: `"day"`, `"week"`, `"month"`, or `"year"`. Cannot be `one_off`. |
Each customer/entity feature in a `get` response carries a `usage_limits` array where every entry also reports the `usage` consumed in the current window, so you can show "12 / 50 used today" without a separate call.
### Window reset and plan changes
Each window aligns to the **customer's billing cycle**, not the UTC calendar. A `day` cap rolls at the customer's billing time-of-day; a `month` cap rolls on their billing-cycle anchor. When there's no billing cycle to anchor to (e.g. a feature with no backing plan), the window falls back to UTC calendar alignment — daily windows roll at UTC midnight, monthly on the 1st.
Because the window is tied to the feature's reset cycle, **a plan change that restarts that cycle also restarts the window.** If a customer upgrades mid-month and their billing anchor moves, the usage limit's window re-anchors to the new cycle and the consumed counter starts fresh.
### Caps on credit systems
When a feature is part of a [credit system](/documentation/modelling-pricing/credit-systems), you can cap usage at either level:
* **Cap the credit balance** — e.g. limit total `credits` spend per window across every feature that draws from it.
* **Cap an individual feature** — e.g. give a credit system shared by features A, B, and C, but limit how many units of B specifically can be used per window. The per-feature cap is converted into credits using B's credit cost, so both caps are enforced together.
> **Example — per-feature cap inside a credit system**
> Your `credits` system is spent by `images`, `transcriptions`, and `exports`. Customers can spend credits freely across all three, but you cap `exports` at **10 per day** so one feature can't drain the whole balance. A check or track on `exports` is blocked at 10/day even if plenty of credits remain.
When more than one cap applies to a check (the cap on the evaluated feature and a cap on its parent credit system), Autumn enforces the **tightest** one — the remaining headroom is the minimum across all armed caps.
## Usage Alerts
Usage alerts fire a webhook when a customer's usage crosses a threshold. They don't block usage — they notify, so you can take action like sending a warning email or prompting an upgrade.
There are two threshold types:
* **`usage`** — fires when absolute usage reaches a specific count
* **`usage_percentage`** — fires when usage reaches a percentage of the included allowance
```typescript TypeScript theme={null}
await autumn.customers.update({
customerId: "user_123",
billingControls: {
usageAlerts: [
{
featureId: "api_calls",
threshold: 80,
thresholdType: "usage_percentage",
enabled: true,
name: "80% usage warning",
},
{
featureId: "api_calls",
threshold: 900,
thresholdType: "usage",
enabled: true,
name: "Approaching limit",
},
],
},
});
```
```python Python theme={null}
await autumn.customers.update(
customer_id="user_123",
billing_controls={
"usage_alerts": [
{
"feature_id": "api_calls",
"threshold": 80,
"threshold_type": "usage_percentage",
"enabled": True,
"name": "80% usage warning",
},
{
"feature_id": "api_calls",
"threshold": 900,
"threshold_type": "usage",
"enabled": True,
"name": "Approaching limit",
},
],
},
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers/update" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"billing_controls": {
"usage_alerts": [
{
"feature_id": "api_calls",
"threshold": 80,
"threshold_type": "usage_percentage",
"enabled": true,
"name": "80% usage warning"
},
{
"feature_id": "api_calls",
"threshold": 900,
"threshold_type": "usage",
"enabled": true,
"name": "Approaching limit"
}
]
}
}'
```
| Field | Type | Description |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------- |
| `feature_id` | string | The feature to monitor |
| `threshold` | number | Trigger value — absolute count or percentage (0–100) |
| `threshold_type` | string | `"usage"` for absolute count, `"usage_percentage"` for percentage of included allowance |
| `enabled` | boolean | Whether the alert is active (defaults to `true`) |
| `name` | string (optional) | A label to distinguish multiple alerts |
Each alert fires **once** per threshold crossing. It won't re-fire unless usage drops below the threshold and crosses it again.
When triggered, Autumn sends a `balances.usage_alert_triggered` [webhook](/documentation/webhooks). See the [webhook schema](/api-reference/webhooks/balancesUsageAlertTriggered) for the full payload.
For more details and examples, see [Spend Limits & Usage Alerts](/documentation/modelling-pricing/spend-limits#usage-alerts).
## Auto Top-Ups
Auto top-ups automatically replenish a customer's prepaid balance when it drops below a configured threshold. This prevents service interruptions for customers who don't want to manually manage their credits.
> **Example**
> A customer gets 5,000 credits per month. When their balance drops below 500, Autumn automatically purchases 1,000 more credits using the plan's one-off prepaid price.
Auto top-ups require a plan with a [one-off prepaid](/documentation/modelling-pricing/one-off-purchases) item for the feature, and the customer must have a payment method on file.
```typescript TypeScript theme={null}
await autumn.customers.update({
customerId: "user_123",
billingControls: {
autoTopups: [{
featureId: "credits",
enabled: true,
threshold: 500,
quantity: 1000,
}],
},
});
```
```python Python theme={null}
await autumn.customers.update(
customer_id="user_123",
billing_controls={
"auto_topups": [{
"feature_id": "credits",
"enabled": True,
"threshold": 500,
"quantity": 1000,
}],
},
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers/update" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"billing_controls": {
"auto_topups": [{
"feature_id": "credits",
"enabled": true,
"threshold": 500,
"quantity": 1000
}]
}
}'
```
| Field | Type | Description |
| ---------------- | ----------------- | ----------------------------------------- |
| `feature_id` | string | The feature (credit balance) to monitor |
| `enabled` | boolean | Whether auto top-up is active |
| `threshold` | number | Balance level that triggers a top-up |
| `quantity` | number | Units to purchase each time |
| `purchase_limit` | object (optional) | Rate limit on how often top-ups can occur |
To prevent runaway spending, you can set a purchase limit:
```json theme={null}
{
"purchase_limit": {
"interval": "month",
"interval_count": 1,
"limit": 5
}
}
```
This limits the customer to 5 auto top-ups per month. Supported intervals: `hour`, `day`, `week`, `month`.
For setup instructions and how it works end-to-end, see [Auto Top-Ups](/documentation/modelling-pricing/auto-top-ups).
## Customer vs Entity Controls
Billing controls can be set at two levels:
| Control | Customer-level | Entity-level |
| ------------------- | -------------- | ------------ |
| **Overage allowed** | Yes | Yes |
| **Spend limits** | Yes | Yes |
| **Usage limits** | Yes | Yes |
| **Usage alerts** | Yes | Yes |
| **Auto top-ups** | Yes | No |
**Entity-level** controls are configured by updating the entity instead of the customer. Entity-level controls override customer-level controls for that entity — for example, an entity overage override takes precedence over the customer-level setting, and entity spend limits override the customer-level limit.
Overrides are resolved **per feature**: an entity's own entry for a feature wins, and the customer's entries fill in any features the entity doesn't set. For usage limits specifically, an inherited (customer-level) cap counts usage against the **shared customer window** — it's the same aggregate cap, not a separate per-entity copy. An entity-level usage limit, by contrast, gets its own per-entity window and counter.
> **Example — per-entity cap**
> An org (the customer) has 1,000 monthly API calls shared across its workspaces (entities). You set a customer-level usage limit of 1,000/month so the org can't exceed its plan, and an entity-level limit of 200/day on a noisy workspace so it can't starve the others. The workspace is blocked at 200/day; the org is blocked at 1,000/month.
```typescript TypeScript theme={null}
await autumn.entities.update({
customerId: "org_123",
entityId: "workspace_a",
billingControls: {
overageAllowed: [{
featureId: "api_calls",
enabled: true,
}],
spendLimits: [{
featureId: "api_calls",
enabled: true,
overageLimit: 2000,
}],
usageLimits: [{
featureId: "api_calls",
limit: 200,
interval: "day",
}],
usageAlerts: [{
featureId: "api_calls",
threshold: 90,
thresholdType: "usage_percentage",
enabled: true,
}],
},
});
```
```python Python theme={null}
await autumn.entities.update(
customer_id="org_123",
entity_id="workspace_a",
billing_controls={
"overage_allowed": [{
"feature_id": "api_calls",
"enabled": True,
}],
"spend_limits": [{
"feature_id": "api_calls",
"enabled": True,
"overage_limit": 2000,
}],
"usage_limits": [{
"feature_id": "api_calls",
"limit": 200,
"interval": "day",
}],
"usage_alerts": [{
"feature_id": "api_calls",
"threshold": 90,
"threshold_type": "usage_percentage",
"enabled": True,
}],
},
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/entities/update" \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "org_123",
"entity_id": "workspace_a",
"billing_controls": {
"overage_allowed": [{
"feature_id": "api_calls",
"enabled": true
}],
"spend_limits": [{
"feature_id": "api_calls",
"enabled": true,
"overage_limit": 2000
}],
"usage_limits": [{
"feature_id": "api_calls",
"limit": 200,
"interval": "day"
}],
"usage_alerts": [{
"feature_id": "api_calls",
"threshold": 90,
"threshold_type": "usage_percentage",
"enabled": true
}]
}
}'
```
Auto top-ups are customer-level only because they create invoices and charge a payment method, which is tied to the customer account — not individual entities.
## Plan-Level Defaults
Every billing control can also be defined on a **plan** (in the dashboard under plan settings → billing controls, via the `billingControls` field when creating or updating a plan, or in the [CLI config](/cli/config#plans) with the same field). Plan-level controls act as defaults for every customer on that plan — set a daily usage limit once on your free tier instead of on each customer.
```ts autumn.config.ts theme={null}
export const free = plan({
planId: "free",
versionSlug: "v1",
active: true,
name: "Free",
autoEnable: true,
items: [{ featureId: "emails", included: 200, reset: { interval: "month" } }],
billingControls: {
usageLimits: [{ featureId: "emails", limit: 200, interval: "day" }],
},
});
```
Resolution when a customer is on one or more plans:
* A **customer-level entry shadows the plan's entry** for the same feature (for usage limits, the same feature *and* conditions). Setting a control on the customer is how you override the plan default — and a disabled customer entry still shadows the plan's, it doesn't resurface it.
* With **multiple attached plans** defining the same control, the most restrictive wins (auto top-ups: the most recently attached plan's config).
### Reading effective controls
From API version `2.3.0`, [fetching a customer](/api-reference/customers/getCustomer) returns the **effective** controls: plan defaults are merged into `billing_controls`, and every entry carries a `source` field so you can tell overrides from inherited defaults. Inherited usage limits include the live window `usage`, so you can render "X of 200 used today" without extra calls.
```json theme={null}
"billing_controls": {
"usage_limits": [
{
"feature_id": "emails",
"enabled": true,
"limit": 200,
"interval": "day",
"usage": 37,
"source": "plan"
}
]
}
```
On earlier API versions, `billing_controls` contains only customer-level entries. Entity responses always show the entity's own controls.
## Related Webhooks
Billing controls tie into three webhook events that fire automatically based on usage:
| Event | When it fires |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`balances.limit_reached`](/api-reference/webhooks/balancesLimitReached) | Customer transitions from allowed to not allowed on a feature (included allowance exhausted, max purchase hit, spend limit reached, or usage limit hit). The payload's `limit_type` distinguishes `included`, `max_purchase`, `spend_limit`, and `usage_limit`. |
| [`balances.usage_alert_triggered`](/api-reference/webhooks/balancesUsageAlertTriggered) | Customer's usage crosses a configured alert threshold |
| [`customer.products.updated`](/documentation/webhooks#customerproductsupdated) | Customer's subscription changes (new, upgrade, downgrade, cancel, etc.) |
For webhook setup and security details, see [Webhooks](/documentation/webhooks).
# Checking access
Source: https://docs.useautumn.com/documentation/customers/check
Learn how to check feature access with the `check` endpoint
When you create a plan in Autumn, you define what features your customers on that plan get access to.
The `check` method returns the `allowed` field in real-time to check if a customer should have access to a feature. You can use this to block access and prompt an upsell.
## The `allowed` field
The `allowed` field will return `true` for a given feature if:
* The customer has an active plan with this feature
* The customer has an active plan with a `credit_system` that grants this feature
* The plan feature is included or prepaid, and the current balance is greater than the `required_balance` parameter
* The plan feature is usage-based, and the user has not exceeded their max spend limit
* The plan feature is unlimited or a boolean feature
Under these conditions, you should allow your customer to use the feature. You can then [record the usage event](/documentation/customers/tracking-usage/) so Autumn can update the `allowed` field as necessary.
The customer must already exist before calling `check`. If the `customer_id` doesn't match an existing customer, the API returns a `customer_not_found` error. Create customers using [`customers.getOrCreate`](/documentation/customers/creating-customers) during signup or login.
## Checking metered features
Before your customer uses a feature, you can check if the customer is allowed to use it and their current usage.
**Example**
Let's imagine you have a free plan for a chatbot that allows 5 messages per month. Before your customer sends an AI message, you can check if they have any left.
If they still have messages remaining, they'll be allowed to send an AI message.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const response = await autumn.check({
customerId: "user_123",
featureId: "messages",
});
console.log(response.allowed);
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
response = await autumn.check(
customer_id="user_123",
feature_id="messages",
)
print(response.allowed)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/check" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"feature_id": "messages"
}'
```
```json theme={null}
{
"allowed": true,
"customerId": "user_123",
"requiredBalance": 1,
"balance": {
"featureId": "messages",
"granted": 5,
"remaining": 5,
"usage": 0,
"unlimited": false,
"overageAllowed": false,
"nextResetAt": 1767610960519
}
}
```
Even if your product doesn't have usage limits (ie your feature is purely usage-based), you can still use the above method to prevent usage if a customer's payment fails.
## Checking for a required balance
If you know the balance a user will consume in advance, you can specify it with the `requiredBalance` parameter. This means you can prevent a user from starting a process that would consume more than their current balance.
By default, `requiredBalance` is 1, so not passing this parameter will return `allowed: true` as long as the customer has a feature balance of 1 or more.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const response = await autumn.check({
customerId: "user_123",
featureId: "messages",
requiredBalance: 3,
});
console.log(response.allowed);
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
response = await autumn.check(
customer_id="user_123",
feature_id="messages",
required_balance=3,
)
print(response.allowed)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/check" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"feature_id": "messages",
"required_balance": 3
}'
```
## Checking and reserving usage
When you don't know the final cost upfront — like AI completions or long-running jobs — reserve balance with a `lock` on the check call, then finalize it once the operation completes.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const response = await autumn.check({
customerId: "user_123",
featureId: "api_calls",
requiredBalance: 3,
sendEvent: true,
lock: {
enabled: true,
lockId: "request_abc123",
expiresAt: Date.now() + 5 * 60 * 1000, // 5 minutes
},
});
console.log(response.allowed);
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
response = await autumn.check(
customer_id="user_123",
feature_id="api_calls",
required_balance=3,
send_event=True,
lock={
"enabled": True,
"lock_id": "request_abc123",
"expires_at": int(time.time() * 1000) + 5 * 60 * 1000,
},
)
print(response.allowed)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/check" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"feature_id": "api_calls",
"required_balance": 3,
"send_event": true,
"lock": {
"enabled": true,
"lock_id": "request_abc123",
"expires_at": 1735689600000
}
}'
```
Once the operation completes, finalize the lock — `confirm` it to keep the deduction, or `release` it if the operation failed.
```typescript TypeScript theme={null}
await autumn.balances.finalize({
lockId: "request_abc123",
action: "confirm",
});
```
```python Python theme={null}
await autumn.balances.finalize(
lock_id="request_abc123",
action="confirm",
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/balances.finalize" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"lock_id": "request_abc123",
"action": "confirm"
}'
```
See [Balance Locking](/documentation/customers/balance-locking) for the full guide, including releasing a lock and adjusting the final amount when actual usage differs from what you reserved.
## Checking boolean features
For simple on/off features, use the check method to determine if a customer has access:
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const response = await autumn.check({
customerId: "user_123",
featureId: "premium-dashboard",
});
if (response.allowed) {
// Show premium dashboard
}
```
### Feature flags in customer responses
Boolean features are also returned as a `flags` object on customer and entity API responses. This lets you check on/off feature access directly from the customer object without calling the `check` endpoint separately.
```json theme={null}
{
"balances": {
"credits": { "featureId": "credits", "granted": 1000, "remaining": 800, "usage": 200 }
},
"flags": {
"premiumDashboard": {
"id": "cus_ent_abc123",
"planId": "pro_plan",
"expiresAt": null,
"featureId": "premiumDashboard"
}
}
}
```
* **Flags** are separate from **balances** — boolean features appear under `flags`, while metered and credit system features remain under `balances`
* Each flag shows which `planId` it originates from and when it expires
* Use `expand: ["flags.feature"]` to include the full feature object on each flag
```typescript TypeScript theme={null}
const customer = await autumn.customers.getOrCreate({
customerId: "user_123",
expand: ["flags.feature"],
});
if (customer.flags?.["premiumDashboard"]) {
// Customer has the premium dashboard feature
}
```
```python Python theme={null}
customer = await autumn.customers.get_or_create(
customer_id="user_123",
expand=["flags.feature"],
)
if customer.flags and "premium_dashboard" in customer.flags:
# Customer has the premium dashboard feature
pass
```
# Creating Customers
Source: https://docs.useautumn.com/documentation/customers/creating-customers
Create customers via API or dashboard, link to Stripe, and pre-create for enterprise deals
Customers represent the entities — usually users or organizations — of your application that can use and pay for your products.
For each customer, Autumn will:
* Keep record of the products they've purchased
* Track the features they've used and have access to
* Bill them through Stripe for the prices you've set
## Creating a customer via API
Use the `customers.getOrCreate` method to create a customer. This is idempotent — it creates the customer if they don't exist, or returns the existing one if they do.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const customer = await autumn.customers.getOrCreate({
customerId: "user_123",
name: "John Doe",
email: "john@example.com",
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
customer = await autumn.customers.get_or_create(
customer_id="user_123",
name="John Doe",
email="john@example.com",
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"name": "John Doe",
"email": "john@example.com"
}'
```
Only the `customerId` field is required — this should be your unique identifier for the customer that you'll use in all future API calls.
A common pattern is to call `customers.getOrCreate` on every login or signup in your application, so Autumn always has the latest customer information.
Customers must be created before calling the [`check`](/documentation/customers/check) or [`track`](/documentation/customers/tracking-usage) endpoints. If you call these endpoints with a `customer_id` that doesn't exist, the API will return a `customer_not_found` error. Make sure to call `customers.getOrCreate` during signup or login before checking access or tracking usage.
## Pre-creating customers via the dashboard
You can create a customer in the Autumn dashboard before they've ever interacted with your application. This is useful for enterprise or sales-led deals where you want to provision access before the customer signs up.
1. Navigate to the [Customers page](https://app.useautumn.com/customers)
2. Click "Create Customer"
3. Fill in the customer's details (name, email). **Leave the `id` field blank** — it will be assigned when the customer first logs in.
4. Click "Create Customer"
Once the customer is created, you can enable products and configure their features from the customer details page. When the customer eventually signs up in your application, Autumn will match them by email and link the pre-created customer record.
The email you provide must match the email the customer will use to sign up or log in. You can update the email from the customer details page if needed.
**Example: Enterprise onboarding**
You've closed an enterprise deal with Acme Corp. Before their team starts using your product:
1. Create a customer in the dashboard with the billing contact's email
2. Enable a custom Enterprise plan with negotiated pricing
3. When the Acme team signs up, Autumn matches the email and they immediately have their plan active — no checkout needed
## Customer properties
#### Customer ID
Your unique identifier for the customer. This is the only required field. It could be:
* Your database ID for the user
* Their email address
* Any other unique identifier in your system
#### Name and Email
Optional fields that help identify the customer in the Autumn dashboard and on Stripe invoices.
## Stripe integration
By default, Autumn does **not** create a Stripe customer when you create an Autumn customer. A Stripe customer is created lazily — only when the first billing operation needs one (like `billing.attach`, `billing.openCustomerPortal`, or `billing.setupPayment`).
```mermaid theme={null}
flowchart LR
A["Your app user_123"] -->|customers.getOrCreate| B["Autumn Customer user_123"]
B -->|on first billing call| C["Stripe Customer cus_abc123"]
```
You can change this behavior:
#### Create in Stripe immediately
Pass `createInStripe: true` to create the Stripe customer at the same time as the Autumn customer. This is useful if you need the Stripe customer ID upfront (e.g., for your own Stripe integration).
```typescript TypeScript theme={null}
await autumn.customers.getOrCreate({
customerId: "user_123",
name: "John Doe",
email: "john@example.com",
createInStripe: true,
});
```
```python Python theme={null}
await autumn.customers.get_or_create(
customer_id="user_123",
name="John Doe",
email="john@example.com",
create_in_stripe=True,
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"name": "John Doe",
"email": "john@example.com",
"create_in_stripe": true
}'
```
#### Link to an existing Stripe customer
If you already have a Stripe customer (e.g., you're migrating to Autumn), pass `stripeId` to link it instead of creating a new one:
```typescript TypeScript theme={null}
await autumn.customers.getOrCreate({
customerId: "user_123",
stripeId: "cus_abc123",
});
```
```python Python theme={null}
await autumn.customers.get_or_create(
customer_id="user_123",
stripe_id="cus_abc123",
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"stripe_id": "cus_abc123"
}'
```
Once linked, the mapping is bidirectional — the Stripe customer ID is stored on the Autumn customer, and the Autumn customer ID is stored in the Stripe customer's metadata.
For more details on how Autumn and Stripe work together, see [Stripe Sync](/documentation/concepts/stripe).
# Custom Plans
Source: https://docs.useautumn.com/documentation/customers/custom-plans
Create one-off plan variations for individual customers
Sometimes a customer needs a plan that doesn't match any of your standard offerings — extra credits, different pricing, or access to features not in their current tier. Custom plans let you create a one-off variation of any product for a specific customer, without changing the product for everyone else.
## When to use custom plans
Custom plans are useful when:
* An enterprise customer negotiates a different price or feature set
* You want to give a customer extra allowance as a one-time accommodation
* A customer needs access to a feature that isn't in their current plan
* You're closing a deal that doesn't fit neatly into your standard tiers
## Creating a custom plan via the dashboard
1. Navigate to the [Customer details page](https://app.useautumn.com/customers) for the customer
2. Click "Enable Product" (or click the existing product to modify it)
3. Make changes to the product items before enabling:
* Adjust feature allowances (e.g., increase included credits from 100 to 500)
* Add or remove features
* Change pricing (fixed or usage-based)
4. Click "Enable"
This creates a custom version of the product — only this customer will have it. The original product remains unchanged for all other customers.
## What happens when you enable a custom plan
The behavior depends on what you changed:
| Change type | Behavior |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Features only** (allowances, adding/removing features) | Takes effect immediately. New balances are provisioned while keeping existing reset dates. |
| **Pricing changes** (higher price) | Treated as an upgrade — prorated charges apply for the remainder of the billing cycle. |
| **Pricing changes** (lower price) | Treated as a downgrade — scheduled for end of current billing cycle. |
## Custom plans vs editing balances
If you just need a temporary adjustment (e.g., granting a customer extra credits this month), you can [edit their balance directly](/documentation/customers/managing-customers#editing-feature-balances) instead. Balance edits reset at the next billing cycle.
Custom plans are better when you want the change to persist across billing cycles.
**Example**
A customer on your Pro plan (100 credits/month, \$50/month) needs 250 credits/month at the same price. Create a custom plan with 250 included credits. They'll get 250 credits every month going forward, while all other Pro customers continue getting 100.
## Custom plans and versioning
Custom plans are tracked as separate versions of the product. When you [update the base product](/documentation/customers/versioning), customers on custom plans are not affected — they stay on their custom version.
If you want to migrate a customer off a custom plan and onto the latest standard version, you can do so from the [customer details page](https://app.useautumn.com/customers) by re-enabling the standard product.
# Billing Reliability
Source: https://docs.useautumn.com/documentation/customers/edge-cases
How Autumn handles 3DS, payment failures, and other uncommon states
In addition to the subscription lifecycle, Autumn automatically handles a number of edge cases to make sure your customers are always billed correctly.
## 3D Secure (3DS)
When a payment requires 3D Secure authentication, the `attach` response returns:
```json theme={null}
{
"required_action": {
"code": "3ds_required",
"reason": "Payment requires 3D Secure authentication"
},
"payment_url": "https://invoice.stripe.com/..."
}
```
As normal, redirect the customer to the `payment_url` to complete authentication. Once they authenticate, Autumn processes the payment and activates the plan automatically via the `invoice.paid` webhook.
The invoice URL expires after **10 minutes**. If the customer doesn't complete authentication in time, the invoice is automatically voided and the attach must be retried.
## Payment Failures
If the customer's payment method is declined during `attach`, the response returns:
```json theme={null}
{
"required_action": {
"code": "payment_failed",
"reason": "Card was declined"
},
"payment_url": "https://invoice.stripe.com/..."
}
```
The `payment_url` links to Stripe's hosted invoice page where the customer can update their payment method and retry. As with 3DS, the invoice is auto-voided after 10 minutes if left unresolved.
A third code, `payment_method_required`, is returned when no payment method is on file at all. In this case, redirect the customer to the `payment_url` which points to a Stripe Checkout session.
## Past Due Subscriptions
If a recurring payment fails (e.g. card expired between billing cycles), the subscription status becomes `past_due`. To resolve this:
1. Direct the customer to the [billing portal](/api-reference/billing/openCustomerPortal) to update their payment method
2. Once updated, Stripe automatically retries the failed invoice
```typescript Node.js theme={null}
const { data } = await autumn.billing.openCustomerPortal("user_123", {
returnUrl: "https://your-app.com/billing",
});
// Redirect to data.url
```
```python Python theme={null}
response = await autumn.billing.open_customer_portal(
"user_123",
return_url="https://your-app.com/billing",
)
# Redirect to response.url
```
If you'd like to block feature access when a subscription is `past_due`, please contact us. We can enable a configuration flag to do this for you.
## Subscription Expiry
When a subscription is deleted or expires, any open invoices associated with it are automatically voided. This prevents a scenario where a customer could pay a stale invoice for a subscription that no longer exists — the payment would go through but have no effect.
This also applies when a subscription transitions to `past_due` and is automatically canceled (if that behavior is enabled for your organization).
## Proration Failures
When an upgrade generates a proration invoice that fails to pay, Autumn automatically **rolls back the subscription update** to the customer's previous plan. The open invoice is then handled through the same 3DS / payment failure flow described above — the customer receives an invoice URL to resolve the payment.
## Concurrent Requests
Autumn uses distributed locking to prevent race conditions across billing operations. All mutating billing endpoints — `attach`, `multi_attach`, and `update_subscription` — share a per-customer lock. If two requests arrive simultaneously for the same customer, the second request receives a `429` response. This prevents duplicate subscriptions, double charges, or conflicting subscription updates.
The same lock is shared with auto top-ups, so a top-up triggered by usage can't race against a manual attach for the same customer.
## Duplicate Webhook Delivery
Stripe may deliver the same webhook event multiple times. Autumn deduplicates webhooks using a per-event idempotency key — if the same Stripe event ID is received more than once within a 5-minute window, the duplicate is acknowledged without reprocessing.
Additionally, when Autumn initiates a subscription change (e.g. a cancellation or upgrade), it sets a short-lived lock on the subscription. This prevents the resulting Stripe webhook from re-processing the change that Autumn already applied, avoiding double-counting or conflicting state updates.
## API Idempotency
All API requests support an `Idempotency-Key` header. If the same key is sent within 24 hours, the duplicate request is rejected with a `409` response. This is useful when retrying requests after network failures — you won't accidentally attach the same plan twice.
Event tracking (`track`) uses the same header. Pass it as a request option rather than a body field:
```typescript theme={null}
await autumn.track(
{ customerId: "cus_123", featureId: "api_calls", value: 1 },
{ headers: { "Idempotency-Key": "request_abc123" } }
);
```
# Entities
Source: https://docs.useautumn.com/documentation/customers/feature-entities
Learn how to use feature entities to track balances per separate entity, such as a user or a workspace
Entities are sub accounts of a customer. For example, you may have a product that allows 500 credits **per user** per month.
## Product setup
An entity can hold its own plan, with its own balances, while the parent customer pays. There are two ways to provision that, differing in where capacity comes from:
1. **Attach directly**: pass the [entity ID](/api-reference/billing/attach#body-entity-id) into an attach call. The entity gets its own subscription in Stripe, with billing cycles synced to the parent. Use this when entities appear and you bill for them as they do.
2. **Licenses**: the parent plan offers a pool of seats that the customer buys upfront, and you assign one to an entity to give it its plan. Use this when customers commit to a seat count before you know who fills it.
Both support different tiers per entity. See [entity plans](/documentation/modelling-pricing/entity-plans) for the full setup of either.
**Example**
Max has a team product where each seat gets 30 meeting note summaries per month, and teams buy their seat count upfront. He creates a Seat license plan holding the 30 summaries, offers it under his Team plan, and assigns a license each time someone joins.
Jamie also has a team product, but workspaces are created ad hoc and each can be on a Free or Pro tier. She creates the two tiers as normal and attaches them at the entity level as workspaces appear.
## Creating entities
You can manage feature entities via the `entities` route. This can be used to create, update and delete entities, such as when a seat or workspace is added or removed.
When you create an entity, a **usage event** will automatically be sent that increments the count of the number of entities (eg seats) being used.
This means if you create 2 entities for "seats", your usage of "seats" will be 2, allowing Autumn to bill accordingly if there's a price set.
This is how seats are counted when you attach plans directly. With [licenses](/documentation/modelling-pricing/entity-plans#licenses), seats are counted by the license pool instead, and the entity's feature only identifies its type.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
await autumn.entities.create({
customerId: "org_123",
entityId: "user_abc",
featureId: "seats",
name: "John Doe",
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
await autumn.entities.create(
customer_id="org_123",
entity_id="user_abc",
feature_id="seats",
name="John Doe",
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/entities" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "org_123",
"entity_id": "user_abc",
"feature_id": "seats",
"name": "John Doe"
}'
```
## Managing entity balances
Just like with normal features, you can check feature access and track usage events for each entity.
#### Check feature access
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const response = await autumn.check({
customerId: "org_123",
featureId: "ai-messages",
entityId: "user_abc",
});
console.log(response.allowed);
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
response = await autumn.check(
customer_id="org_123",
feature_id="ai-messages",
entity_id="user_abc",
)
print(response.allowed)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/check" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "org_123",
"feature_id": "ai-messages",
"entity_id": "user_abc"
}'
```
#### Send usage event
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
await autumn.track({
customerId: "org_123",
featureId: "ai-messages",
entityId: "user_abc",
value: 10,
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
await autumn.track(
customer_id="org_123",
feature_id="ai-messages",
entity_id="user_abc",
value=10,
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/track" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "org_123",
"feature_id": "ai-messages",
"entity_id": "user_abc",
"value": 10
}'
```
#### Customer-level vs entity-level balances
A customer-level balance is the total balance for the feature across all entities. Entity-level balances are the balance for a specific entity. You can check access and track usage events either at the customer-level or entity-level.
**Example**
You have a product that allows 500 credits per user per month. However, the credits are shared across all users in the account.
You can create a feature entity for "seats" and then check access and send usage events at the top-level.
To use top-level balances, just omit the `entityId` from your check request.
This will increment the usage counter for the top-level balance, and also
deduct from the first-created entity so that the sum of the the entity
balances is always the same as the top-level balance.
## Deleting Entities
Just as creating an entity sent a usage event for the associated feature,
deleting an entity will decrease the usage.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
await autumn.entities.delete({
customerId: "org_123",
entityId: "user_abc",
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
await autumn.entities.delete(
customer_id="org_123",
entity_id="user_abc",
)
```
```bash cURL theme={null}
curl -X DELETE "https://api.useautumn.com/v1/entities/user_abc" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{ "customer_id": "org_123" }'
```
# Managing Balances
Source: https://docs.useautumn.com/documentation/customers/managing-balances
Create, update, and manage balances via the dashboard or API
You can manage customer balances through the Autumn dashboard or programmatically via the API.
## From the Dashboard
### Viewing Balances
1. Go to the [Customers page](https://app.useautumn.com/customers)
2. Click on a customer to view their details
3. Their balances are displayed in the **Balances** section, including breakdown by source
### Modifying a Balance
To set or add to a feature's balance:
1. Navigate to the customer's detail page
2. Under the balances section, click on the feature you want to modify. If there are [stacked balances](/documentation/concepts/balances#balance-stacking), choose the one you want to modify.
3. Choose whether to **set the balance** to a specific value or **add to the balance**
4. Enter the amount and save
## Creating Standalone Balances (API)
You can use the `/balances/create` endpoint to grant balances independent of any plan, for example to issue one-time promotional credits, referral rewards, or make manual customer adjustments.
You can also set expiration dates for promotional usage grants and configure reset intervals.
```typescript Node.js theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_..." });
await autumn.balances.create({
customer_id: "user_123",
feature_id: "credits",
granted_balance: 500,
reset: {
interval: "one_off"
}
});
```
```python Python theme={null}
from autumn import Autumn
autumn = Autumn(secret_key="am_sk_...")
autumn.balances.create(
customer_id="user_123",
feature_id="credits",
granted_balance=500,
reset={
"interval": "one_off"
}
)
```
```bash cURL theme={null}
curl -X POST https://api.useautumn.com/v1/balances/create \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"feature_id": "credits",
"granted_balance": 500,
"reset": {
"interval": "one_off"
}
}'
```
See the [Create Balance API reference](/api-reference/balances/createBalance) for all available parameters.
## Updating Balances (API)
Use the `/customers/{customer_id}/balances` endpoint to set balances for a customer.
```typescript Node.js theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_..." });
await autumn.customers.updateBalances("user_123", {
balances: [{ feature_id: "credits", balance: 750 }]
});
```
```python Python theme={null}
from autumn import Autumn
autumn = Autumn(secret_key="am_sk_...")
autumn.customers.update_balances(
"user_123",
balances=[{"feature_id": "credits", "balance": 750}]
)
```
```bash cURL theme={null}
curl -X POST https://api.useautumn.com/v1/customers/user_123/balances \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"balances": [{ "feature_id": "credits", "balance": 750 }]
}'
```
See the [Set Feature Balance API reference](/api-reference/balances/updateBalance) for all available parameters.
## Querying Balances
### Via Get Customer
Retrieve all balances for a customer:
```typescript Node.js theme={null}
const customer = await autumn.customers.get("user_123");
console.log(customer.balances);
```
```python Python theme={null}
customer = autumn.customers.get("user_123")
print(customer.balances)
```
```bash cURL theme={null}
curl https://api.useautumn.com/v1/customers/user_123 \
-H "Authorization: Bearer am_sk_..."
```
See the [Get Customer API reference](/api-reference/customers/get-customer) for the full response schema.
### Via Check Endpoint
Check access and get the current balance for a specific feature:
```typescript Node.js theme={null}
const result = await autumn.check({
customer_id: "user_123",
feature_id: "credits"
});
console.log(result.allowed);
console.log(result.balance);
```
```python Python theme={null}
result = autumn.check(
customer_id="user_123",
feature_id="credits"
)
print(result.allowed)
print(result.balance)
```
```bash cURL theme={null}
curl -X POST https://api.useautumn.com/v1/check \
-H "Authorization: Bearer am_sk_..." \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"feature_id": "credits"
}'
```
See the [Check API reference](/api-reference/core/check) for more details.
# Managing Customers
Source: https://docs.useautumn.com/documentation/customers/managing-customers
Learn how to view and manage customer information in Autumn
The customer details page provides a comprehensive view of a customer's information, subscriptions, and usage. You can access this by clicking on any customer from the [Customers page](https://app.useautumn.com/customers).
The customer details page shows:
* **Products**: View active subscriptions, status, billing dates, and feature limits
* **Features**: Track usage, limits, reset dates and history graphs
* **Invoices**: See billing history, payment status, amounts and hosted invoice pages
* **Events**: View feature usage events that have been tracked for the customer
## Editing Feature Balances
You can directly edit a customer's feature balances via the dashboard, to give them additional allowance or alter how much they'll be charged for their next invoice (typically in case of errors).
1. Navigate to the Customer details page
2. Under "Available Features", click on the feature you want to edit the balance for.
3. In the popup, enter the new balance value:
* If you're giving them more allowance (`granted`) of a feature, enter a **positive** number
* If you're changing how much usage they'll be charged for, enter a **negative** number
4. Optionally, set a new usage reset date for the feature
5. Click "Update"
Editing a balance will only last until the next reset date of the feature. If
you want to permanently set a new allowance, you should create a custom
product with the new allowance.
If you want to give a customer access to a feature that isn't present in the
product they're on, you can create a custom product with the new feature.
## Adding a Coupon
To apply a discount to a customer:
1. Go to the customer's details page
2. Under the "Rewards" section of the sidebar, click "Add Coupon"
3. Select a reward from the available options
4. Click "Add Reward"
The discount will show up when a Checkout URL is generated for the customer via `attach`, or from their next invoice.
## Updating Customer Properties
You can update a customer's basic information through either the dashboard or API:
#### Via Dashboard
1. Navigate to the customer's details page
2. On the right-hand side, you'll see a "Details" section in the sidebar. Click on any of the fields.
3. Update the desired fields (name, email, etc.)
4. Click "Update"
#### Via API
You can also update a customer's properties via the API, useful for when a customer changes their details in your application.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
await autumn.customers.update({
customerId: "user_123",
name: "Mr New Name",
email: "newemail@example.com",
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
await autumn.customers.update(
customer_id="user_123",
name="Mr New Name",
email="newemail@example.com",
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/customers/update" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"name": "Mr New Name",
"email": "newemail@example.com"
}'
```
#### Deleting a Customer
To delete a customer:
1. Go to the customer's details page
2. Click the "Settings" icon in the top right
3. Click "Delete"
Deleting a customer will not delete it in Stripe. If they have existing
subscriptions, you should cancel them from Stripe if needed.
# Payment Flow
Source: https://docs.useautumn.com/documentation/customers/payment-flow
Hosted checkout pages vs building your own payment flow
## Using hosted pages
Pass `redirectMode: "always"` and `billing.attach` will always return a `paymentUrl` — just redirect the customer and Autumn handles payment collection, confirmation, and activation.
```typescript TypeScript theme={null}
const response = await autumn.billing.attach({
customerId: "user_123",
planId: "pro",
redirectMode: "always",
});
redirect(response.paymentUrl);
```
```python Python theme={null}
response = await autumn.billing.attach(
customer_id="user_123",
plan_id="pro",
redirect_mode="always",
)
# Redirect to response.payment_url
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing.attach' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro",
"redirect_mode": "always"
}'
```
New customers without a payment method are sent to **Stripe Checkout**. Existing customers are sent to **Autumn Checkout** to review and confirm. After checkout, the customer is redirected to your `successUrl` (or the default URL in your Autumn dashboard).
## Building your own checkout
For full control over the checkout experience, use `redirectMode: "if_required"`. This charges the saved payment method directly instead of redirecting — the customer is only sent to Stripe Checkout if they don't have a payment method yet.
```mermaid actions={false} theme={null}
graph LR
A["previewAttach"] --> B["user confirms"] --> C["attach"] --> D{"Payment method?"}
D -->|Yes| E["Charged"]
D -->|No| F["Stripe Checkout"]
E --> G["Plan enabled"]
F --> G
style A fill:#f472b622,stroke:#f472b6
style C fill:#f472b622,stroke:#f472b6
```
### Step 1: Preview the charge
Call `billing.previewAttach` to get line items, totals, and proration details to display in your UI.
```typescript TypeScript theme={null}
const preview = await autumn.billing.previewAttach({
customerId: "user_123",
planId: "pro",
});
// preview.lineItems — array of charges and credits
// preview.total — net amount
// preview.currency — e.g. "usd"
```
```python Python theme={null}
preview = await autumn.billing.preview_attach(
customer_id="user_123",
plan_id="pro",
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing.preview_attach' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro"
}'
```
```json theme={null}
{
"customerId": "user_123",
"lineItems": [
{
"title": "Pro Plan",
"description": "Monthly subscription",
"amount": 20
},
{
"title": "Credit for Free Plan",
"description": "Unused time on current plan",
"amount": -5
}
],
"total": 15,
"currency": "usd",
"nextCycle": {
"startsAt": 1735689600000,
"total": 20
}
}
```
### Step 2: Confirm and charge
Once the customer confirms, call `billing.attach` with `redirectMode: "if_required"`.
```typescript TypeScript theme={null}
const response = await autumn.billing.attach({
customerId: "user_123",
planId: "pro",
redirectMode: "if_required",
});
if (response.paymentUrl) {
redirect(response.paymentUrl);
} else {
showSuccess();
}
```
```python Python theme={null}
response = await autumn.billing.attach(
customer_id="user_123",
plan_id="pro",
redirect_mode="if_required",
)
if response.payment_url:
redirect(response.payment_url)
else:
show_success()
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing.attach' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro",
"redirect_mode": "if_required"
}'
```
## Handling the response
The `billing.attach` response has two key fields:
**`payment_url`** — a URL the customer should be redirected to, or `null` if no redirect is needed.
**`required_action`** — present when payment couldn't be processed automatically. See [Edge Cases](/documentation/customers/edge-cases) for details on handling 3DS, payment failures, and retries.
# Subscription Lifecycle
Source: https://docs.useautumn.com/documentation/customers/subscription-lifecycle
Handle upgrades, downgrades, and cancellations
## Upgrades
Upgrades happen when you attach a plan with a higher price than the customer's current plan. Use `billing.attach` — Autumn handles the rest.
If a payment method exists, attaching the plan will immediately charge the customer. If upgrading from a free to a paid plan, a checkout URL is generated instead.
**Pricing behavior:**
* **Fixed prices** are prorated based on time remaining in the billing period
* **Usage-based prices** bill outstanding usage at the old rate immediately, then apply the new rate going forward
## Downgrades
Downgrades happen when you attach a plan with a lower price. Unlike upgrades, downgrades are **scheduled** to take effect at the end of the current billing period.
The new plan will have status `scheduled` until it activates. Customers can cancel a scheduled downgrade by re-attaching their current plan.
If you've set a [`group`](/documentation/concepts/plans#plan-properties) when creating plans, upgrades and downgrades only apply between plans in the same group. Attaching a plan from a different group adds it alongside the existing plan.
## Cancellations
Cancel a subscription using `billing.update` with the `cancelAction` parameter. By default, cancellations take effect at the end of the billing period.
### Cancel at end of billing period
```typescript TypeScript theme={null}
const response = await autumn.billing.update({
customerId: "user_123",
planId: "pro",
cancelAction: "cancel_end_of_cycle",
});
```
```python Python theme={null}
response = await autumn.billing.update(
customer_id="user_123",
plan_id="pro",
cancel_action="cancel_end_of_cycle",
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing.update' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro",
"cancel_action": "cancel_end_of_cycle"
}'
```
The subscription remains active until the end of the current billing period. If you have a default plan (with `is_default` set), it will be activated after the cancellation takes effect.
### Cancel immediately
To cancel a subscription right away with a prorated refund:
```typescript TypeScript theme={null}
const response = await autumn.billing.update({
customerId: "user_123",
planId: "pro",
cancelAction: "cancel_immediately",
});
```
```python Python theme={null}
response = await autumn.billing.update(
customer_id="user_123",
plan_id="pro",
cancel_action="cancel_immediately",
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing.update' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro",
"cancel_action": "cancel_immediately"
}'
```
This ends the subscription immediately and issues a prorated refund for the remaining time in the billing period.
## Uncanceling
If a subscription was scheduled for cancellation (via `cancel_end_of_cycle`), you can reverse it before the period ends using `uncancel`:
```typescript TypeScript theme={null}
const response = await autumn.billing.update({
customerId: "user_123",
planId: "pro",
cancelAction: "uncancel",
});
```
```python Python theme={null}
response = await autumn.billing.update(
customer_id="user_123",
plan_id="pro",
cancel_action="uncancel",
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing.update' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro",
"cancel_action": "uncancel"
}'
```
This clears the pending cancellation and the subscription continues as normal. Any default plan that was scheduled to activate after cancellation is also removed.
You cannot uncancel a subscription that was already canceled immediately — only pending cancellations (scheduled for end of cycle) can be reversed.
## Canceling a scheduled plan change
When a downgrade or other plan change is **scheduled** for the end of the billing period, canceling it works the same way as uncanceling. Call `billing.update` with `cancelAction: "uncancel"` on the customer's **active** plan:
```typescript TypeScript theme={null}
// Customer is on Pro with a scheduled downgrade to Basic.
// Cancel the scheduled change and keep Pro.
const response = await autumn.billing.update({
customerId: "user_123",
planId: "pro",
cancelAction: "uncancel",
});
```
```python Python theme={null}
# Customer is on Pro with a scheduled downgrade to Basic.
# Cancel the scheduled change and keep Pro.
response = await autumn.billing.update(
customer_id="user_123",
plan_id="pro",
cancel_action="uncancel",
)
```
```bash cURL theme={null}
# Customer is on Pro with a scheduled downgrade to Basic.
# Cancel the scheduled change and keep Pro.
curl -X POST 'https://api.useautumn.com/v1/billing.update' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro",
"cancel_action": "uncancel"
}'
```
This removes the scheduled replacement plan and keeps the customer on their current plan.
## `cancel_action` reference
| Value | Behavior |
| --------------------- | ------------------------------------------------------------------------------------------------------ |
| `cancel_end_of_cycle` | Schedules cancellation at the end of the current billing period. Subscription stays active until then. |
| `cancel_immediately` | Cancels immediately with a prorated refund for remaining time. |
| `uncancel` | Reverses a pending cancellation or removes a scheduled plan change. |
## Usage reset behavior
When a new plan is enabled, you can control what happens to existing feature usage with the `reset_usage_when_enabled` property on the plan item:
* `true`: Usage resets to 0 (typical for consumable features like credits)
* `false`: Usage carries over to the new plan (typical for continuous features like seats)
**Example:** A customer on Free has used 20 of their 100 credits. They upgrade to Pro which includes 500 credits.
* If `reset_usage_when_enabled = true`: They get 500 credits
* If `reset_usage_when_enabled = false`: They get 480 credits (500 - 20 used)
## Carry-over on plan upgrades
When a customer upgrades plans, you can preserve their unused balances or account for their existing usage. Two parameters on [`billing.attach`](/api-reference/billing/attach) give you fine-grained control over what happens to consumable features during an immediate upgrade.
Carry-over only works with **immediate** upgrades (`planSchedule: "immediate"` or default upgrade behavior). Scheduled plan changes and downgrades do not support carry-over.
### Carrying over unused balances
Use `carryOverBalances` to preserve a customer's remaining balance from the old plan. The unused credits are added as a one-off balance on the new plan, so the customer doesn't lose what they've already paid for.
```typescript TypeScript theme={null}
const response = await autumn.billing.attach({
customerId: "user_123",
planId: "enterprise",
carryOverBalances: {
enabled: true,
},
});
```
```python Python theme={null}
response = await autumn.billing.attach(
customer_id="user_123",
plan_id="enterprise",
carry_over_balances={
"enabled": True,
},
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing.attach' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "enterprise",
"carry_over_balances": {
"enabled": true
}
}'
```
**Example:** A customer on Pro has 300 of 1,000 credits remaining. They upgrade to Enterprise (2,000 credits/month). With `carryOverBalances` enabled, the 300 unused credits carry forward — giving them 2,300 credits on the new plan. The carried-over balance expires at the next reset or end of cycle.
### Carrying over prior usage
Use `carryOverUsages` to deduct prior usage from the new plan's allowance, preventing customers from getting a free reset on upgrade.
```typescript TypeScript theme={null}
const response = await autumn.billing.attach({
customerId: "user_123",
planId: "enterprise",
carryOverUsages: {
enabled: true,
},
});
```
```python Python theme={null}
response = await autumn.billing.attach(
customer_id="user_123",
plan_id="enterprise",
carry_over_usages={
"enabled": True,
},
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing.attach' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "enterprise",
"carry_over_usages": {
"enabled": true
}
}'
```
**Example:** A customer on Pro has used 700 of 1,000 credits this month. They upgrade to Enterprise (2,000 credits/month). With `carryOverUsages` enabled, 700 usage is deducted from the new allowance — giving them 1,300 remaining instead of a full 2,000.
### Scoping to specific features
Both parameters accept an optional `featureIds` array to limit carry-over to specific features:
```typescript TypeScript theme={null}
const response = await autumn.billing.attach({
customerId: "user_123",
planId: "enterprise",
carryOverBalances: {
enabled: true,
featureIds: ["credits", "api_calls"],
},
carryOverUsages: {
enabled: true,
featureIds: ["credits"],
},
});
```
Only consumable metered features support carry-over. Boolean features, unlimited features, and allocated (non-consumable) features are not eligible.
# Tracking usage
Source: https://docs.useautumn.com/documentation/customers/tracking-usage
Keep track of your customer's feature usage with the `track` route
When customers use features in your product, you'll need to record their usage so Autumn can track it against their limits or bill them for usage.
There are two ways to record usage: sending events or setting usage directly.
The customer must already exist before calling `track`. If the `customer_id` doesn't match an existing customer, the API returns a `customer_not_found` error. Create customers using [`customers.getOrCreate`](/documentation/customers/creating-customers) during signup or login.
## Sending Events
The track route is recommended for tracking consumable features, like AI messages, credits or API calls. Each time a customer uses a feature, send an event to count their usage.
Before recording usage, you may want to check if the customer is [allowed to
use the feature](/documentation/customers/check). This prevents them from exceeding usage
limits defined in the product.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
await autumn.track({
customerId: "user_123",
featureId: "ai-messages",
value: 1,
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
await autumn.track(
customer_id="user_123",
feature_id="ai-messages",
value=1,
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/track" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"feature_id": "ai-messages",
"value": 1
}'
```
```json theme={null}
{
"customerId": "user_123",
"value": 1,
"balance": {
"featureId": "ai-messages",
"granted": 100,
"remaining": 99,
"usage": 1,
"unlimited": false,
"overageAllowed": false,
"nextResetAt": 1767610960519
}
}
```
You can also send a negative `value` to increase the balance counter, which is
useful for increasing a feature limit (eg, if a customer removes a seat).
## Setting Usage Directly
For non-consumable features (such as seats or workspaces), you may prefer to set usage directly, rather than incrementing Autumn's feature balance. This enables you to sync a source of truth up on your side with Autumn, preventing any discrepancies.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
await autumn.balances.update({
customerId: "user_123",
featureId: "seats",
usage: 3,
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
await autumn.balances.update(
customer_id="user_123",
feature_id="seats",
usage=3,
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/balances/update" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"feature_id": "seats",
"usage": 3
}'
```
The usage route overwrites the current usage value. Use this carefully, as it
can reset or override incremental usage recorded through events.
## Tracking AI Token Usage
If you're using an [AI credit system](/examples/monetary-credits), you can track token usage directly with `trackTokens`. This automatically converts token counts to a dollar cost using [Models.dev](https://models.dev) pricing and your configured markup, then deducts from the customer's credit balance.
The `modelId` must be in `provider/model` format, matching the provider and model keys from [Models.dev](https://models.dev). For example:
* `anthropic/claude-sonnet-4-5-20250514`
* `openai/gpt-4o`
* `google/gemini-2.5-pro`
For providers with nested model paths (like OpenRouter), include the full path after the provider: `openrouter/anthropic/claude-opus-4.6`.
Token counts are **exclusive pools**: `inputTokens` should exclude cached tokens (pass those as `cacheReadTokens` / `cacheWriteTokens`) and `outputTokens` should exclude reasoning tokens (pass those as `reasoningTokens`). Audio tokens go in `audioInputTokens` / `audioOutputTokens`. See the [API reference](/api-reference/balances/trackTokens) for the full parameter list.
`autumn.balances.trackTokens` requires an autumn-js release that includes
the method. On older versions, call the REST endpoint directly — see the
cURL tab below.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
await autumn.balances.trackTokens({
customerId: "user_123",
modelId: "anthropic/claude-opus-4-6",
inputTokens: 1000,
outputTokens: 500,
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
await autumn.balances.track_tokens(
customer_id="user_123",
model_id="anthropic/claude-opus-4-6",
input_tokens=1000,
output_tokens=500,
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/balances.track_tokens" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"model_id": "anthropic/claude-opus-4-6",
"input_tokens": 1000,
"output_tokens": 500
}'
```
If the customer has exactly one AI credit system feature, you can omit the
`featureId` parameter — it will be auto-detected. The request fails with an
error if the customer has no AI credit system, or has more than one and no
`featureId` is provided.
### Vercel AI SDK integration
If you're using the [Vercel AI SDK](https://sdk.vercel.ai), the `@useautumn/gateway` package can automatically track token usage for every `generateText` or `streamText` call — no manual `trackTokens` calls needed.
## Using Event Names
In the above examples, we used the `featureId` to identify the feature. You can instead use the `eventName` parameter to link balances to different events in your application. This can be useful when:
* Multiple balances are affected by the same user action
* Different user actions should be tracked against the same balance
**Example Use Case:**
Your AI chatbot has a daily limit of 10 messages, with a maximum monthly limit of 100 messages. Recording a message in Autumn should decrease both balances simultaneously.
In Autumn, you can create two features: `daily-messages` and `monthly-messages`. You can add the same event name to both features: `message-sent`. Then, assign both features to a plan with the correct included amounts.
Every time that event name is recorded, both the daily-messages and monthly-messages balances will be decremented.
If you were to use the same feature for both in this case, the daily and monthly balances would sum, allowing the user to send 10 messages a day, with an "overage" balance of 100 messages per month if they go over the daily limit.
You can define event names in the Autumn dashboard:
1. Go to the [Features Page](https://app.useautumn.com/sandbox/products?tab=features).
2. Click on the feature you want to add an event to.
3. In the sheet, under the "advanced" section, add your event names.
4. Save the feature.
You can then record usage for these events from your application:
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
await autumn.track({
customerId: "user_123",
eventName: "blog_post_generation",
value: 1,
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
await autumn.track(
customer_id="user_123",
event_name="blog_post_generation",
value=1,
)
```
```bash cURL theme={null}
curl -X POST "https://api.useautumn.com/v1/track" \
-H "Authorization: Bearer am_sk_test_1234" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "user_123",
"event_name": "blog_post_generation",
"value": 1
}'
```
You can only use one of `eventName` or `featureId` when recording usage.
Check that you're sending the correct one in the request, especially if you're
using a mix of `snake_case` and `kebab-case`.
# Updating Subscriptions
Source: https://docs.useautumn.com/documentation/customers/updating-subscriptions
Modify existing subscriptions - update quantities, cancel, or customize
Use `billing.update` to modify an existing subscription. This is different from `billing.attach` which is for attaching new plans or changing between plans.
**When to use `billing.update`:**
* **Update feature quantities** — if your plan contains prepaid features (like seats)
* **Cancel or uncancel** — cancel a subscription immediately or at end of cycle
* **Customize the plan** — modify pricing or feature configuration (advanced)
## Updating prepaid feature quantities
Prepaid features are features where customers pay upfront for a quantity (e.g., seats, team members). Here's an example plan with a prepaid `seats` feature:
```typescript autumn.config.ts theme={null}
import { atmn, feature, plan } from "atmn";
export const seats = feature({
featureId: "seats",
name: "Seats",
type: "metered",
consumable: false, // Non-consumable = doesn't reset
});
export const team = plan({
planId: "team",
versionSlug: "v1",
active: true,
name: "Team Plan",
price: {
amount: 49,
interval: "month",
},
items: [
{
featureId: seats.featureId,
included: 5, // 5 seats included
price: {
amount: 10, // $10 per additional seat
interval: "month",
billingMethod: "prepaid",
},
},
],
});
export default atmn({ features: [seats], plans: [team] });
```
To update the quantity of seats for a customer:
```typescript TypeScript theme={null}
const response = await autumn.billing.update({
customerId: "user_123",
planId: "team",
featureQuantities: [
{ featureId: "seats", quantity: 10 }
],
});
```
```python Python theme={null}
response = await autumn.billing.update(
customer_id="user_123",
plan_id="team",
feature_quantities=[
{ "feature_id": "seats", "quantity": 10 }
],
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing/update' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "team",
"feature_quantities": [
{ "feature_id": "seats", "quantity": 10 }
]
}'
```
## Canceling a subscription
Use `cancelAction` to cancel or uncancel a subscription:
| Action | Description |
| --------------------- | ------------------------------------------------------------------------------------ |
| `cancel_end_of_cycle` | Cancel at the end of the current billing period. Customer retains access until then. |
| `cancel_immediately` | Cancel immediately with a prorated refund. |
| `uncancel` | Reverse a pending cancellation (only works if not yet expired). |
```typescript TypeScript theme={null}
// Cancel at end of billing cycle
await autumn.billing.update({
customerId: "user_123",
planId: "pro",
cancelAction: "cancel_end_of_cycle",
});
// Uncancel a pending cancellation
await autumn.billing.update({
customerId: "user_123",
planId: "pro",
cancelAction: "uncancel",
});
```
```python Python theme={null}
# Cancel at end of billing cycle
await autumn.billing.update(
customer_id="user_123",
plan_id="pro",
cancel_action="cancel_end_of_cycle",
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing/update' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro",
"cancel_action": "cancel_end_of_cycle"
}'
```
## How billing works
By default, updating a subscription with billing changes will generate an invoice:
* **Increasing quantity** (e.g., adding seats) charges a prorated amount for the remainder of the billing cycle
* **Decreasing quantity** (e.g., removing seats) generates a credit applied to the next invoice
* **Canceling immediately** generates a negative invoice granting credits to the customer
### Previewing changes before executing
Similar to [`billing.previewAttach`](/documentation/customers/payment-flow#step-1-preview-the-charge), you can use `billing.previewUpdate` to see exactly what will be charged before making changes. This returns line items and totals that you can display in a confirmation UI.
```typescript TypeScript theme={null}
const preview = await autumn.billing.previewUpdate({
customerId: "user_123",
planId: "team",
featureQuantities: [
{ featureId: "seats", quantity: 10 }
],
});
// Display preview.lineItems, preview.total, preview.currency
// Then call billing.update to execute
```
```python Python theme={null}
preview = await autumn.billing.preview_update(
customer_id="user_123",
plan_id="team",
feature_quantities=[
{ "feature_id": "seats", "quantity": 10 }
],
)
# Display preview.line_items, preview.total
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing/preview-update' \
-H 'Authorization: Bearer am_sk_...' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "team",
"feature_quantities": [
{ "feature_id": "seats", "quantity": 10 }
]
}'
```
### Skipping charges
If you want to update a subscription without creating any charges or credits, pass `prorationBehavior: "none"`:
```typescript theme={null}
await autumn.billing.update({
customerId: "user_123",
planId: "team",
featureQuantities: [
{ featureId: "seats", quantity: 10 }
],
prorationBehavior: "none", // No charges or credits created
});
```
This is useful for administrative adjustments or when you want to handle billing separately.
# Versioning Plans
Source: https://docs.useautumn.com/documentation/customers/versioning
How to update and migrate customers between product versions
## Updating Products
You can update products through the Autumn UI:
1. Navigate to the [products page](https://app.useautumn.com/products)
2. Select the product you want to modify
3. Make your changes to the product items or properties
4. Click "Update Product "
When you update a product, Autumn will create a new version of the product, and immediately apply this version to any new customers who purchase the product.
A new version will only be created if there are customers on the current
version.
Existing customers will remain on the previous version (known as "grandfathering"). You'll be able to see which customers are on which version in your [customer page](https://app.useautumn.com/customers).
## Migrating customers between product versions
When you're ready, you can migrate customers to the latest verion of a product.
1. Go to the [product details page](https://app.useautumn.com/products) of the product you want to migrate customers from
2. On the right-hand side, you'll see a "Versions" section in the sidebar. Use the version history selector to find the version you want to migrate customers from
3. Navigate to the old version, and click the "Migrate Customers" button
When migrating customers to a new product version:
* Feature balances are updated immediately. Customer's existing usage will carry over (not reset) to the new product.
* Outstanding billable usage will be added as a line item to the customer's next invoice. Any further usage will be billed at the new price.
* Fixed pricing changes will only take effect from the customer's next billing cycle, as no proration is applied to price differences between versions.
**Example**
Our existing product gives customers 10 credits per month, 1 USD per additional credit, and a 10 USD per month price.
We're updating the product to give customers 20 credits per month, 2 USD per additional credit, and a 200 USD per month price.
We have a customer, Mark, who has used 5 credits in the current month. We also have Helly who has used 20 credits.
Here's what will happen to Mark:
* Mark will be immediately have 15 credits available (20 in the new product minus 5 used)
* Mark was 5 credits under the limit in the old product, so has no line items added to his next invoice.
* Mark will be charged 20 USD from his next billing cycle.
Here's what will happen to Helly:
* Helly will be immediately have 0 credits remaining (20 in the new product minus 20 used)
* Helly was 10 credits over the limit in the old product, so she'll have a 10 USD line item (10 credits \* 1 USD) added to her next invoice.
* Any further credit usage will be charged at the new rate of 2 USD per credit.
* Helly will be charged 20 USD from her next billing cycle.
# Vercel AI SDK
Source: https://docs.useautumn.com/documentation/external-providers/ai-sdk
Automatically track AI token usage with the Vercel AI SDK
The `@useautumn/gateway` package integrates Autumn with the [Vercel AI SDK](https://sdk.vercel.ai), automatically tracking token usage for every `generateText` or `streamText` call. No manual `trackTokens` calls needed.
## Setup
#### 1. Install the package
```bash npm theme={null}
npm install @useautumn/gateway
```
```bash pnpm theme={null}
pnpm add @useautumn/gateway
```
```bash yarn theme={null}
yarn add @useautumn/gateway
```
```bash bun theme={null}
bun add @useautumn/gateway
```
Requires `autumn-js` and `ai` (v6+) as peer dependencies.
#### 2. Wrap your model
Use `withAutumn` to wrap any AI SDK language model. It intercepts generate and stream calls, reads the token usage from the response, and reports it to Autumn automatically.
```typescript theme={null}
import { Autumn } from "autumn-js";
import { anthropic } from "@ai-sdk/anthropic";
import { withAutumn } from "@useautumn/gateway/ai-sdk";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const model = withAutumn({
autumn,
model: anthropic("claude-sonnet-4-5-20250514"),
customerId: "user_123",
});
```
#### 3. Use as normal
The wrapped model works exactly like a regular AI SDK model. Token usage is tracked in the background after each call.
```typescript theme={null}
import { generateText, streamText } from "ai";
// Generate — usage tracked automatically
const { text } = await generateText({
model,
prompt: "Explain quantum computing in one paragraph",
});
// Stream — usage tracked when the stream finishes
const result = streamText({
model,
prompt: "Write a short poem about recursion",
});
for await (const chunk of result.textStream) {
process.stdout.write(chunk);
}
```
## Token pools
The wrapper normalizes the AI SDK's usage object into the exclusive token pools that [trackTokens](/api-reference/balances/trackTokens) expects: text input (excluding cached tokens), text output (excluding reasoning tokens), cache reads, cache writes, and reasoning tokens. Each pool is billed at the model's published rate, so cached and reasoning-heavy requests are priced correctly without any extra work.
## Model ID format
The wrapped model constructs the `modelId` sent to Autumn using `provider/model` format, derived from the AI SDK model's `provider` and `modelId` fields. This must match a valid provider and model key from [Models.dev](https://models.dev).
For example:
* `@ai-sdk/anthropic` → `anthropic/claude-sonnet-4-5-20250514`
* `@ai-sdk/openai` → `openai/gpt-4o`
* `@ai-sdk/google` → `google/gemini-2.5-pro`
If the AI SDK provider name doesn't match the Models.dev provider key, use the `providerId` option to override it:
```typescript theme={null}
import { createOpenRouter } from "@openrouter/ai-sdk-provider";
const openrouter = createOpenRouter();
const model = withAutumn({
autumn,
model: openrouter("anthropic/claude-opus-4.6"),
customerId: "user_123",
providerId: "openrouter", // Override provider prefix
});
// Sends modelId as "openrouter/anthropic/claude-opus-4.6"
```
## Options
| Parameter | Type | Required | Description |
| ------------ | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `autumn` | `Autumn` | Yes | Your Autumn SDK client instance |
| `model` | `LanguageModelV3` | Yes | The AI SDK language model to wrap |
| `customerId` | `string` | Yes | The Autumn customer ID to attribute usage to |
| `providerId` | `string` | No | Override the provider prefix in the model name sent to Autumn. Falls back to the model's `provider` field |
| `featureId` | `string` | No | Target a specific AI credit system feature. Auto-detected if you only have one |
| `entityId` | `string` | No | Entity ID for entity-scoped balance tracking |
| `properties` | `Record` | No | Additional properties to attach to each usage event |
## Full example
```typescript theme={null}
import { Autumn } from "autumn-js";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";
import { withAutumn } from "@useautumn/gateway/ai-sdk";
const autumn = new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY! });
async function chat(customerId: string, message: string) {
const model = withAutumn({
autumn,
model: openai("gpt-4o"),
customerId,
});
const { text } = await generateText({
model,
prompt: message,
});
return text;
}
```
Tracking failures are caught and logged to the console — they won't break your AI features. Check your server logs if usage isn't appearing in Autumn.
# OpenRouter
Source: https://docs.useautumn.com/documentation/external-providers/openrouter
Automatically track AI token usage with the OpenRouter SDK
The `@useautumn/gateway` package integrates Autumn with the [OpenRouter SDK](https://openrouter.ai/docs), automatically tracking token usage for every `chat.send` call. No manual `trackTokens` calls needed.
Using OpenRouter through the Vercel AI SDK (`@openrouter/ai-sdk-provider`)? Use the [AI SDK wrapper](/documentation/external-providers/ai-sdk) with `providerId: "openrouter"` instead.
## Setup
#### 1. Install the package
```bash npm theme={null}
npm install @useautumn/gateway
```
```bash pnpm theme={null}
pnpm add @useautumn/gateway
```
```bash yarn theme={null}
yarn add @useautumn/gateway
```
```bash bun theme={null}
bun add @useautumn/gateway
```
Requires `autumn-js` and `@openrouter/sdk` as peer dependencies.
#### 2. Wrap your client
Use `withAutumn` to wrap your OpenRouter client. It intercepts `chat.send` calls, enables OpenRouter's [usage accounting](https://openrouter.ai/docs/use-cases/usage-accounting) on every request, reads the token usage from the response, and reports it to Autumn automatically.
```typescript theme={null}
import { Autumn } from "autumn-js";
import { OpenRouter } from "@openrouter/sdk";
import { withAutumn } from "@useautumn/gateway/openrouter";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const openRouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
const client = withAutumn({
autumn,
openRouter,
customerId: "user_123",
});
```
#### 3. Use as normal
The wrapped client works exactly like a regular OpenRouter client — streaming and non-streaming. Token usage is tracked in the background after each call.
```typescript theme={null}
// Non-streaming — usage tracked automatically
const result = await client.chat.send({
model: "openai/gpt-4o",
messages: [{ role: "user", content: "Explain quantum computing" }],
});
// Streaming — usage tracked when the stream finishes
const stream = await client.chat.send({
model: "anthropic/claude-sonnet-4-5",
messages: [{ role: "user", content: "Write a short poem" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```
## Token pools
The wrapper normalizes OpenRouter's usage accounting into the exclusive token pools that [trackTokens](/api-reference/balances/trackTokens) expects: text input (excluding cached and audio tokens), text output (excluding reasoning tokens), cache reads, cache writes, audio input, and reasoning tokens. Each pool is billed at the model's published rate.
The model is reported to Autumn as `openrouter/` (e.g. `openrouter/openai/gpt-4o`), using the resolved model from the response — so router aliases like `openrouter/auto` bill against the model that actually served the request. Autumn prices usage with OpenRouter's rates from [Models.dev](https://models.dev), and OpenRouter's own reported cost is attached to each event as the `openrouter_cost` property for reconciliation.
## Options
| Parameter | Type | Required | Description |
| ------------ | ------------------------- | -------- | ------------------------------------------------------------------------------ |
| `autumn` | `Autumn` | Yes | Your Autumn SDK client instance |
| `openRouter` | `OpenRouter` | Yes | The OpenRouter SDK client to wrap |
| `customerId` | `string` | Yes | The Autumn customer ID to attribute usage to |
| `featureId` | `string` | No | Target a specific AI credit system feature. Auto-detected if you only have one |
| `entityId` | `string` | No | Entity ID for entity-scoped balance tracking |
| `properties` | `Record` | No | Additional properties to attach to each usage event |
## Manual tracking
If you consume OpenRouter through a path the wrapper doesn't cover (e.g. `callModel`, or raw `fetch` against the REST API), use `trackOpenRouterUsage` directly with the response's usage object — it accepts both the SDK's camelCase models and the raw snake\_case API shape:
```typescript theme={null}
import { trackOpenRouterUsage } from "@useautumn/gateway/openrouter";
await trackOpenRouterUsage({
autumn,
customerId: "user_123",
model: response.model, // e.g. "openai/gpt-4o"
usage: response.usage,
});
```
Tracking failures are caught and logged to the console — they won't break your AI features. Check your server logs if usage isn't appearing in Autumn.
# RevenueCat
Source: https://docs.useautumn.com/documentation/external-providers/revenuecat
Integrate Autumn with RevenueCat for mobile app billing
RevenueCat integration allows you to use Autumn alongside RevenueCat for managing mobile app subscriptions and billing. This is a *read-only* integration, which means that you will handle billing through RevenueCat.
Autumn will receive webhook updates from RevenueCat to update the customer's plan and features. You keep the benefits of RevenueCat's paywalls, AB testing and SDK.
This is currently in beta, please reach out to us on [Discord](https://discord.gg/STqxY92zuS) or email us at [support@useautumn.com](mailto:support@useautumn.com) to get access.
## Setup Guide
#### Connect RevenueCat to Autumn
To connect RevenueCat to Autumn, you'll need:
* A RevenueCat project ID
* A RevenueCat API key
To get your RevenueCat project ID, visit your RevenueCat dashboard and copy the project ID from the URL. e.g. `https://app.revenuecat.com/projects/1234567890/overview` will have a project ID of `1234567890`.
To get your RevenueCat API key, visit the API keys section on your dashboard, select "New secret API key", and select the following configuration:
* API Version: V2
* Charts metrics permissions: No access
* Customer information permissions: Read only
* Project configuration permissions: Read only
Then, visit your Autumn dashboard, and in the "Developer > RevenueCat" section,
set up your RevenueCat project ID and API key.
#### Map your RevenueCat products to Autumn products
When a RevenueCat product is purchased, define which Autumn product should be enabled for the customer.
RevenueCat is managing billing, so any plan prices in Autumn will be ignored.
Since RevenueCat does not support usage-based or quantity-based pricing, any Autumn plans with these price types will not display in the mapping screen for safety.
RevenueCat products are mapped at the store-level into Autumn. This means instead of mapping a Package or an Offering, you will be mapping Products from Google Play, Apple Store, Roku or etc... instead.
You can still use this in conjunction with RevenueCat's paywalls, packages and offerings however you wish.
#### Set up the webhook integration
For Autumn to recieve updates from RevenueCat, you'll need to set up a webhook integration.
In RevenueCat, visit "Integrations > Webhooks", and click "Add new configuration". Use the following configuration:
* Webhook URL: paste this from the Autumn dashboard
* Authorization header value: paste this from the Autumn dashboard
* Environments: Depending on your Autumn environment, you are given two different URLs. This means you should also separate your RevenueCat webhooks for test and live environments.
* Events filter: All apps, all events.
#### Integration
**You should not call Autumn's `attach()` or `checkout()` functions. Instead you should either use RevenueCat's SDK or RevenueCat's paywalls.**
When the user pays via mobile, the plan will automatically sync into Autumn. Once you have purchased a product or an add-on, you may then continue using `check()` or `track()` to manage your features.
Any existing Autumn customers (that have purchased a plan via Stripe / Web) can still access their balances and features as normal on mobile. They will have an active plan in their `customer` object.
You should handle blocking existing Autumn customers from initiating subscriptions with RevenueCat on mobile, by checking for an active plan in their `customer` object.
When integrating RevenueCat and initiating your `Purchases` instance, you must use the `appUserID` parameter to pass in the customer ID from your auth system.
This will allow you to sync the customer ID into Autumn, whether its a new user or an existing user from Stripe.
```typescript RevenueCatProvider.tsx theme={null}
import { useEffect } from "react";
import Purchases, { LOG_LEVEL } from "react-native-purchases";
export default function RevenueCatProvider({ userID }: { userID: string }) {
useEffect(() => {
Purchases.setLogLevel(LOG_LEVEL.VERBOSE);
Purchases.configure({
apiKey:
process.env.EXPO_PUBLIC_REVENUE_CAT_API_KEY || "",
appUserID: userID,
});
}, [userID]);
return null;
}
```
```typescript app/api/autumn/[...all]+api.ts theme={null}
// Expo also supports better-auth :)
import { auth } from "@/lib/auth";
import { autumnHandler } from "autumn-js/backend";
export async function GET(request: Request, { all }: { all: string }) {
// Get the session from Better Auth
const session = await auth.api.getSession({ headers: request.headers });
if (!session?.user?.id) {
return Response.json(
{ error: "Unauthorized - Please sign in" },
{ status: 401 },
);
}
// Extract user data from session
const customerId = session.user.id;
const customerData = {
name: session.user.name || "Unknown User",
email: session.user.email || "",
};
const autumnResponse = await autumnHandler({
request,
customerId,
customerData
});
return Response.json(autumnResponse.response, { status: autumnResponse.statusCode });
}
export const POST = GET;
export const PUT = GET;
export const DELETE = GET;
export const PATCH = GET;
export const OPTIONS = GET;
```
Then to initiate a purchase, you can use the `purchasePackage` function from the `Purchases` SDK, or open a paywall.
```typescript PurchaseProduct.tsx theme={null}
```
```typescript RCPaywall.tsx theme={null}
import { useRouter } from "expo-router";
import { View } from "react-native";
import RevenueCatUI from "react-native-purchases-ui";
export default function RCPaywall() {
const router = useRouter();
return (
{
router.back();
}}
/>
);
}
```
#### Congratulations!
You have now successfully integrated Autumn with RevenueCat.
You can now use the `check()` and `track()` functions to manage your features as usual.
```typescript check.ts theme={null}
const { data } = await autumn.check({
customer_id: "user_or_org_id_from_auth",
feature_id: "pro",
});
if (data.allowed) {
// User has access to the feature
} else {
// User does not have access to the feature
}
```
```typescript track.ts theme={null}
const { data } = await autumn.track({
customer_id: "john_doe",
feature_id: "messages",
value: 1,
});
// This will decrement the messages balance by 1
```
## Versioning Plans
Autumn's [plan versioning](/documentation/concepts/versioning) feature allows you to update your pricing and migrate customers between versions. However, since mobile billing has specific limitations and is handled by RevenueCat, you should keep the following in mind:
* Whenever a RevenueCat product is purchased, the latest version of the Autumn plan will be enabled for the customer.
* Any price set in Autumn is ignored: only the price set in RevenueCat will be used
* If you migrate a customer from one plan version to another, the plan features will be immediately updated -- just as with the standard migration process. Prices will **not** be updated. You should handle this in [RevenueCat](https://www.revenuecat.com/docs/subscription-guidance/price-changes) (your customers may need to opt-in to the new pricing).
# Vercel Marketplace
Source: https://docs.useautumn.com/documentation/external-providers/vercel-marketplace
Set up the Vercel Marketplace integration in Autumn
Autumn lets you add your product to [Vercel's Marketplace](https://vercel.com/marketplace) without any additional code. This guide walks through connecting the Autumn partner API and webhooks to Vercel, and setting up Stripe's custom payment method for accurate billing.
This is currently in beta. Reach out on [Discord](https://discord.gg/STqxY92zuS) or email [hey@useautumn.com](mailto:hey@useautumn.com) to get access.
## Prerequisites
* An Autumn account with a connected Stripe account
* A Vercel integration entry in the [Vercel Integration Console](https://vercel.com/dashboard/integrations)
## Setup
### Open the Integration Console
Navigate to the Vercel dashboard, then go to **Integrations → Browse Marketplace → Integration Console**.
### Copy your Vercel credentials
Scroll to the bottom of the Integration Console page to find your **Client (Integration) ID** and **Client (Integration) Secret**. You'll need both of these for the Autumn dashboard.
### Copy the Base URL from Autumn
In the Autumn dashboard, open **Developer → Vercel**. Enter the Client ID and Client Secret from the previous step, then copy the **Base URL** that Autumn generates for you.
### Set the Webhook URL in Vercel
Back in the Vercel Integration Console, paste the Autumn Base URL into the **External Integration Settings → Webhook URL** field.
### Set the Marketplace Base URL in Vercel
Paste the same Autumn Base URL into **Marketplace Integration Settings → Base URL**.
### Create a Stripe custom payment method
Autumn uses Stripe's billing clock for accurate billing cycles and invoice reporting via the **Custom Payment Methods** system. In the Stripe dashboard, go to **Settings → Payments → Custom payment methods**, then click **Create a custom payment method**.
### Provide a custom name and icon
Select **Provide a custom name and icon** at the bottom of the payment method selection dialog.
### Name the payment method
Enter **Vercel Marketplace** as the display name and upload the Vercel logo.
### Copy the custom payment method ID
After creating the payment method, Stripe will display a `custom.type ID` (starting with `cpmt_`). Copy this ID and paste it into the **Custom Payment Method ID** field in the Autumn dashboard.
### Configure webhook events
Finally, set up the webhook endpoint for events that Autumn sends to your application. In the Autumn dashboard under **Developer → Vercel**, use the Svix webhook iframe to create a new endpoint. Set your endpoint URL and subscribe to all **Vercel** events. You can ignore the standalone "Webhook URL" setting and leave it empty — the Svix iframe handles this instead.
## Validation
Once everything is configured, trigger a test event flow in Vercel to confirm end-to-end delivery. Verify that:
* Vercel receives callback requests for key lifecycle events
* Autumn logs the incoming payload and processes it correctly
* Your application receives the forwarded webhook events
If events aren't being delivered, double-check that the Base URL is identical in both the Webhook URL and Marketplace Base URL fields in Vercel.
# Fail-Open Defaults
Source: https://docs.useautumn.com/documentation/fail-open
Keep your app running even when Autumn is unreachable
Autumn's SDKs include a **fail-open** mechanism that prevents your application from going down if Autumn is temporarily unreachable. When enabled, critical SDK methods return safe default responses instead of throwing errors.
## Why fail-open?
As a billing engine, Autumn sits in the critical path of your application. If your app calls `check()` to gate access to a feature, and Autumn is unreachable, that call would throw an error -- effectively blocking your users from accessing your product.
Fail-open ensures your users are never blocked by an Autumn outage. Usage events may be lost during the outage, but your customers stay unaffected.
## Behavior
Fail-open is **enabled by default**. When Autumn is unreachable (network errors, timeouts, or server errors returning 5XX status codes), the SDK returns safe defaults:
| Method | Default response | Effect |
| ------------------------- | --------------------------------- | ----------------------------------------- |
| `check()` | `{ allowed: true }` | Users retain access to features |
| `track()` | `{ value: 0, balance: null }` | Usage event is silently dropped |
| `customers.getOrCreate()` | Sentinel customer with `id: null` | Returns a valid but empty customer object |
When fail-open triggers, the SDK logs a prominent error to your console so you're immediately aware of the issue.
## When fail-open triggers
Fail-open activates when the SDK encounters:
* **Server errors** -- Autumn returns a 5XX status code (500, 502, 503, etc.)
* **Network failures** -- DNS resolution failure, connection refused, connection reset
* **Timeouts** -- The request to Autumn times out
Fail-open does **not** activate for client errors (4XX). If you receive a 400 (bad request), 401 (unauthorized), or 404 (not found), those errors propagate normally since they indicate a problem with your integration, not an Autumn outage.
## Configuration
### Disabling fail-open
If you prefer strict error handling and want all Autumn errors to propagate:
```typescript TypeScript theme={null}
import { Autumn } from "@useautumn/sdk";
const autumn = new Autumn({
secretKey: "sk_...",
failOpen: false,
});
```
```python Python theme={null}
# Coming soon
```
### Detecting fail-open responses
When `check()` fails open, the response will have `allowed: true` with empty values:
```typescript theme={null}
const result = await autumn.check({
customerId: "cus_123",
featureId: "messages",
});
// Normal response: allowed is based on actual balance
// Fail-open response: allowed is always true, customerId is ""
```
When `customers.getOrCreate()` fails open, the returned customer will have `id: null`:
```typescript theme={null}
const customer = await autumn.customers.getOrCreate({
customerId: "cus_123",
});
if (customer.id === null) {
// Autumn was unreachable, handle gracefully
}
```
## Console output
When fail-open triggers, you'll see this in your server logs:
```
FATAL AUTUMN ERROR DETECTED; FAILING OPEN; LEARN MORE: https://docs.useautumn.com/docs/fail-open; STATUS PAGE: status.useautumn.com
Operation: check | Status: 503 | Error: Server error
```
Monitor your logs for this message. If you see it, check [status.useautumn.com](https://status.useautumn.com) for ongoing incidents.
## SDK support
| SDK | Fail-open support |
| ----------------------------- | ----------------- |
| `@useautumn/sdk` (TypeScript) | Supported |
| `autumn-python` (Python) | Coming soon |
| `autumn-js` (framework SDK) | Coming soon |
# Deploy to production
Source: https://docs.useautumn.com/documentation/getting-started/deploy
A checklist to go live with confidence
Once you've tested your integration in sandbox, follow this checklist to go live with real payments.
### Connect your live Stripe account
In the Autumn dashboard, open the **Deploy to Production** dialog from the sidebar.
Connect your live Stripe account via OAuth — this links Autumn to your real Stripe environment.
Your sandbox uses a shared Stripe test account by default. Production requires your own Stripe account.
### Push your plans to production
If you're using the [CLI](/cli/getting-started), add `-p` to target production. It uses `AUTUMN_PROD_SECRET_KEY`. `push -p` only previews the change. Add `--yes` to apply it:
```bash theme={null}
bunx atmn push -p
bunx atmn push -p --yes
```
`atmn login` writes `AUTUMN_PROD_SECRET_KEY` next to your sandbox key, so you can use both.
Alternatively, the Deploy dialog in the dashboard can copy your sandbox plans to production for you.
### Swap your API key
Point your server-side code at a live secret key. Create a production key from [Developer Settings](https://app.useautumn.com/production/dev?tab=api_keys), and set it in your production environment:
```bash .env theme={null}
AUTUMN_SECRET_KEY=am_sk_live_...
```
Only set the live key in your production environment. Keep your local `AUTUMN_SECRET_KEY` as the sandbox key. CLI commands with `-p` read `AUTUMN_PROD_SECRET_KEY`, so you never need to overwrite it.
Double check that:
* Your **server-side** code uses the live secret key (`am_sk_live_*`)
* If you're using a publishable key client-side, it's the live one (`am_pk_live_*`)
The key prefix determines the environment automatically — `_test_` routes to sandbox, `_live_` routes to production. There's no separate "environment" config to flip.
### Verify fail-open behavior
Autumn's SDK is **fail-open by default** — if Autumn is unreachable, `check`, `track`, and customer fetches return safe dummy responses instead of throwing errors. This means Autumn can never take your app down.
You should verify this before going live. The easiest way is to point the SDK at a non-existent URL and exercise your app's core flows:
```typescript TypeScript theme={null}
const autumn = new Autumn({
secretKey: process.env.AUTUMN_SECRET_KEY,
serverURL: "https://localhost:9999", // simulate outage
});
```
```python Python theme={null}
autumn = Autumn(
secret_key=os.environ["AUTUMN_SECRET_KEY"],
server_url="https://localhost:9999", # simulate outage
)
```
With this in place:
1. Trigger actions that call `check` — they should return `allowed: true`
2. Trigger actions that call `track` — they should not crash
3. Confirm your core user flows work as normal
4. Remove the `serverURL` override when done
While the SDK gracefully handles outages for read-path calls, write operations like `attach` (which initiate checkout or subscription changes) will still fail when Autumn is unreachable.
### Set up webhooks (if applicable)
If you're listening for Autumn [webhook events](/documentation/webhooks) (e.g. `customer.products.updated`), make sure your production webhook endpoint is configured in the dashboard. Verify you can receive a test event.
### Monitor your first users
After deploying, keep an eye on the [Customers](https://app.useautumn.com/production/customers) page in the Autumn dashboard. Verify that:
* New customers are created correctly
* Subscriptions are attached as expected
* Usage is being tracked
* Invoices are generated in Stripe
***
Once you've completed this checklist, you're live. Your sandbox environment remains available for testing new plans and pricing changes before pushing them to production.
# Build your billing page
Source: https://docs.useautumn.com/documentation/getting-started/display-billing
Display usage and billing data in your app for your users
Software applications typically ship with a billing page. This allows customers to change plan, cancel subscription and view their usage.
The customer endpoint returns the current state of the customer, including their active subscriptions, one-time purchases, and feature balances.
## Pricing table
When building a pricing table, you need to know what each plan means for the current customer — is it an upgrade, a downgrade, or their current plan? Is a free trial available?
Pass a `customerId` when listing plans and each plan will include a `customerEligibility` object:
| Field | Type | Description |
| ---------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------- |
| `attachAction` | `"activate"` \| `"upgrade"` \| `"downgrade"` \| `"purchase"` \| `"none"` | What happens when this plan is attached |
| `status` | `"active"` \| `"scheduled"` \| undefined | The customer's current relationship to this plan |
| `trialAvailable` | boolean | Whether the customer is eligible for the plan's free trial |
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const { list: plans } = await autumn.plans.list({
customerId: "user_123",
});
for (const plan of plans) {
console.log(plan.name, plan.customerEligibility?.attachAction);
// e.g. "Free" "downgrade", "Pro" "none", "Enterprise" "upgrade"
}
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
plans = await autumn.plans.list(customer_id="user_123")
for plan in plans.list:
print(plan.name, plan.customer_eligibility.attach_action)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/plans.list' \
-H 'Authorization: Bearer am_sk_test_1234' \
-H 'Content-Type: application/json' \
-d '{ "customer_id": "user_123" }'
# Each plan in the response includes customer_eligibility
```
## Switching plans
Switching plans uses `billing.attach`. See [Attaching Plans](/documentation/customers/payment-flow) for the full guide.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const response = await autumn.billing.attach({
customerId: "user_123",
planId: "pro",
});
// Redirect to complete payment or confirm plan change
redirect(response.paymentUrl);
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
response = await autumn.billing.attach(
customer_id="user_123",
plan_id="pro",
)
# Redirect to response.payment_url
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/attach' \
-H 'Authorization: Bearer am_sk_test_1234' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro"
}'
```
## Cancelling a plan
Cancel a subscription using `billing.update` with a `cancelAction`. See [Subscription Lifecycle](/documentation/customers/subscription-lifecycle#cancellations) for the full guide on immediate vs end-of-cycle cancellations.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
// Cancel at end of billing cycle
await autumn.billing.update({
customerId: "user_123",
planId: "pro",
cancelAction: "cancel_end_of_cycle",
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
# Cancel at end of billing cycle
await autumn.billing.update(
customer_id="user_123",
plan_id="pro",
cancel_action="cancel_end_of_cycle",
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing/update' \
-H 'Authorization: Bearer am_sk_test_1234' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro",
"cancel_action": "cancel_end_of_cycle"
}'
```
## Uncancelling a plan
If a subscription has a pending cancellation, a scheduled downgrade, or a scheduled plan switch, you can reverse it with `cancelAction: "uncancel"`.
A subscription is pending cancellation when `canceledAt` is not null while the subscription is still `active`.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const customer = await autumn.customers.getOrCreate({
customerId: "user_123",
});
const cancellingSub = customer.subscriptions?.find(
(sub) => sub.status === "active" && sub.canceledAt !== null
);
if (cancellingSub) {
await autumn.billing.update({
customerId: "user_123",
planId: cancellingSub.planId,
cancelAction: "uncancel",
});
}
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
customer = await autumn.customers.get_or_create(
customer_id="user_123"
)
cancelling_sub = next(
(s for s in customer.subscriptions
if s.status == "active" and s.canceled_at is not None),
None,
)
if cancelling_sub:
await autumn.billing.update(
customer_id="user_123",
plan_id=cancelling_sub.plan_id,
cancel_action="uncancel",
)
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing/update' \
-H 'Authorization: Bearer am_sk_test_1234' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"plan_id": "pro",
"cancel_action": "uncancel"
}'
```
## Active plans
Display the plan the user is currently on. Users can have multiple active subscriptions and purchases (e.g., main plan and add-ons).
* **`subscriptions`** - Free and paid recurring plans
* **`purchases`** - One-off plans (e.g., credit top-ups)
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const customer = await autumn.customers.getOrCreate({
customerId: "user_123",
});
const active = customer.subscriptions?.filter(
(sub) => sub.status === "active"
);
console.log(active?.map((sub) => sub.planId).join(", "));
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
customer = await autumn.customers.get_or_create(
customer_id="user_123"
)
active = [s for s in customer.subscriptions if s.status == "active"]
print([s.plan_id for s in active])
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/customers' \
-H 'Authorization: Bearer am_sk_test_1234' \
-H 'Content-Type: application/json' \
-d '{ "customer_id": "user_123" }'
# Response includes subscriptions array
```
## Usage balances
Metered features have `granted`, `usage`, and `remaining` fields. Use these to display current usage and remaining balance.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const customer = await autumn.customers.getOrCreate({
customerId: "user_123",
});
const messages = customer.balances?.messages;
console.log(`${messages?.remaining} / ${messages?.granted}`);
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
customer = await autumn.customers.get_or_create(
customer_id="user_123"
)
messages = customer.balances.get("messages")
print(f"{messages.remaining} / {messages.granted}")
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/customers' \
-H 'Authorization: Bearer am_sk_test_1234' \
-H 'Content-Type: application/json' \
-d '{ "customer_id": "user_123" }'
# Response includes balances.[feature_id]
```
## Stripe billing portal
The Stripe billing portal lets users manage their payment method, view past invoices, and cancel their plan.
Enable the billing portal in your [Stripe settings](https://dashboard.stripe.com/settings/billing/portal).
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const { url } = await autumn.billing.openCustomerPortal({
customerId: "user_123",
returnUrl: "https://your-app.com/billing",
});
redirect(url);
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
response = await autumn.billing.open_customer_portal(
customer_id="user_123",
return_url="https://your-app.com/billing",
)
# Redirect to response.url
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/billing.open_customer_portal' \
-H 'Authorization: Bearer am_sk_test_1234' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"return_url": "https://your-app.com/billing"
}'
```
## Usage timeseries chart
Autumn provides aggregate time series queries for usage data. Pass the response to a charting library like Recharts.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({ secretKey: "am_sk_test_1234" });
const { list, total } = await autumn.events.aggregate({
customerId: "user_123",
featureId: "messages",
range: "30d",
});
```
```python Python theme={null}
from autumn_sdk import Autumn
autumn = Autumn("am_sk_test_1234")
response = await autumn.events.aggregate(
customer_id="user_123",
feature_id="messages",
range="30d",
)
# response.list, response.total
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/events.aggregate' \
-H 'Authorization: Bearer am_sk_test_1234' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"feature_id": "messages",
"range": "30d"
}'
```
You can also use the [`events.list`](/api-reference/events/listEvents) method to get the raw event data and display it in a table.
***
**Next: Deploy to production**
Once your billing page is in place, go through the production checklist to launch with real payments.
A checklist to go live with confidence
# Checking and tracking
Source: https://docs.useautumn.com/documentation/getting-started/gating
Give customers access to the right features and limits based on their plan
Typically, your users should get access to different features and usage limits, depending on their plan.
Autumn handles your customer's payments and grants them the features defined in your plan configuration. There are 2 functions you need to enforce limits and gating:
* `check` for feature access, before allowing a user to do something
* `track` the usage in Autumn afterwards (if needed)
This example will continue from before: a 2-tier pricing model for a chatbot.
This guide shows an asynchronous approach to checking and tracking. You can also [check and reserve](/documentation/customers/check#checking-and-reserving-usage) balance in a single, atomic API call for concurrent events.
### Checking feature access
Check if a user has enough remaining balance of messages, before executing the action. The `feature_id` used here is defined by you when you create the feature in Autumn.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({
secretKey: 'am_sk_42424242',
});
// Check if user can send 1 message
const { allowed } = await autumn.check({
customerId: "user_or_org_id_from_auth",
featureId: "messages",
requiredBalance: 1,
});
if (!allowed) {
console.log("User has run out of messages");
return;
}
```
```python Python theme={null}
import asyncio
from autumn_sdk import Autumn
autumn = Autumn('am_sk_42424242')
async def main():
# Check feature access
response = await autumn.check(
customer_id='user_or_org_id_from_auth',
feature_id='messages',
required_balance=1,
)
asyncio.run(main())
```
```bash cURL theme={null}
# Check feature access
curl -X POST 'https://api.useautumn.com/v1/check' \
-H 'Authorization: Bearer am_sk_42424242' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_123",
"feature_id": "messages",
"required_balance": 1
}'
```
You can also use `check` to [gate boolean features](/documentation/customers/check#checking-boolean-features) (non-metered features), such as access to "premium AI models".
### Tracking usage
After the user has successfully used a chatbot message, you can record the usage in Autumn. This will decrement the user's message balance.
```typescript TypeScript theme={null}
// Your own function to send the chat message
// Then record 1 message used
await autumn.track({
customerId: "user_or_org_id_from_auth",
featureId: "messages",
value: 1,
});
```
```python Python theme={null}
import asyncio
from autumn_sdk import Autumn
autumn = Autumn('am_sk_42424242')
# Your own function to send the chat message
# Then record 1 message used
async def main():
await autumn.track(
customer_id='user_or_org_id_from_auth',
feature_id='messages',
value=1,
)
asyncio.run(main())
```
```bash cURL theme={null}
# Your own function to send the chat message
# Then record 1 message used
curl -X POST 'https://api.useautumn.com/v1/track' \
-H 'Authorization: Bearer am_sk_42424242' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_or_org_id_from_auth",
"feature_id": "messages",
"value": 1
}'
```
Once you send usage events, you can verify their receipt in the Autumn dashboard, on the [customer](https://app.useautumn.com/customers) detail page.
You should always handle access checks and usage tracking server-side for security. Users can manipulate client-side code using devtools.
***
**Next: Build your billing page**
Now, whenever your customers change their plan, they will automatically have the correct access and limits. Next, build a billing page for your customers.
Display plan, balance and usage information to your customers using Autumn's `customer` state
# Migrating to Autumn
Source: https://docs.useautumn.com/documentation/getting-started/migration
How to migrate your existing Stripe customers to Autumn
It's easy to move your existing customers to Autumn. The Autumn team will help you move your subscriptions and purchases over without any disruption. The main reasons teams migrate are:
* **Speed** - Team-based billing, multi-interval usage limits, auto-topups, timeseries charts: all handled by Autumn out of the box.
* **Flexibility** — Plan versioning, custom deals, and pricing changes without code deploys
* **Reliability** — No webhook edge cases, race conditions, or state sync issues to debug
Planning a complex migration? [Reach out to us](https://cal.com/ayrod) — we can help you plan and execute it.
## Migration Steps
Start by integrating Autumn in your development environment. Replace your existing Stripe billing logic with Autumn's SDK:
* Set up your pricing plans in the [Autumn dashboard](https://app.useautumn.com)
* Install the Autumn SDK and configure your API keys
* Replace Stripe checkout, subscription management, and usage tracking with Autumn equivalents
See our [setup guide](/documentation/getting-started/setup) for detailed integration instructions.
Connect your existing Stripe account to Autumn in your production environment. This gives us access to your active subscriptions so we can link them during migration.
Before importing any customers, make sure every plan your Stripe customers are currently on has a matching plan set up in your Autumn production environment. Each customer you import will reference one of these plans by its `plan_id`, so this mapping needs to be in place first.
For each customer, call [`billing.import`](/api-reference/billing/import) with their existing Stripe customer ID, their current subscription, and the Autumn plan it maps to. This links their live Stripe subscription so Autumn can manage it going forward — **there will be no change or disruption to your customers' billing**.
```typescript theme={null}
const autumn = new Autumn({ secretKey: "am_sk_..." });
await autumn.billing.import({
customerId: "user_123",
processors: [{ type: "stripe", id: "cus_ABC123" }],
billables: [
{
processor: "stripe",
link: { subscriptionId: "sub_XYZ789" },
plan: { planId: "pro" },
},
],
});
```
If you need to preserve a customer's exact usage counts rather than have their balances reset on import, follow up with [`balances.update`](/api-reference/balances/updateBalance) to set the correct remaining balance for each feature:
```typescript theme={null}
await autumn.balances.update({
customerId: "user_123",
featureId: "messages",
remaining: 42,
});
```
Once your customers are imported, you can deploy your Autumn integration to production. Your existing customers will be seamlessly linked to their Stripe subscriptions through Autumn.
# Setup and payments
Source: https://docs.useautumn.com/documentation/getting-started/setup
Implement your app's payments and pricing model
In this example we'll create the pricing for a premium AI chatbot. We're going to have:
* A Free plan that gives users 5 chat messages per month for free
* A Pro plan that gives users 100 chat messages per month for \$20 per month.
Create a plan for each pricing tier that your app offers. In our example we'll create a "Free" and "Pro" plan, and assign them features.
Browse our [Examples](/examples) for guides on setting up credit systems, top ups and other common pricing models.
Run the following command in your root directory:
```bash bun theme={null}
bunx atmn init
```
```bash npm theme={null}
npx atmn init
```
```bash pnpm theme={null}
pnpm dlx atmn init
```
This asks how you want to connect (sign in, or create a sandbox with no account), then creates an `autumn/` folder with an `autumn.config.ts` inside. Replace the contents of that file with the code below, or view our [config reference](/cli/config) to build your own.
```typescript autumn.config.ts [expandable] theme={null}
import { atmn, feature, plan } from "atmn";
// Features
export const messages = feature({
featureId: "messages",
name: "Messages",
type: "metered",
consumable: true,
});
// Plans
export const free = plan({
planId: "free",
versionSlug: "v1",
active: true,
name: "Free",
autoEnable: true,
items: [
// 5 messages per month
{
featureId: messages.featureId,
included: 5,
reset: { interval: "month" },
},
],
});
export const pro = plan({
planId: "pro",
versionSlug: "v1",
active: true,
name: "Pro",
price: {
amount: 20,
interval: "month",
},
items: [
// 100 messages per month
{
featureId: messages.featureId,
included: 100,
reset: { interval: "month" },
},
],
});
export default atmn({ features: [messages], plans: [free, pro] });
```
Then, preview your changes against Autumn's sandbox environment.
```bash bun theme={null}
bunx atmn push
```
```bash npm theme={null}
npx atmn push
```
```bash pnpm theme={null}
pnpm dlx atmn push
```
Once the preview looks right, apply it:
```bash bun theme={null}
bunx atmn push --yes
```
```bash npm theme={null}
npx atmn push --yes
```
```bash pnpm theme={null}
pnpm dlx atmn push --yes
```
If you already have plans created in the dashboard, `atmn init` pulls them
into your config for you. Run `atmn pull` at any time to do it again.
Create your [Autumn account](https://app.useautumn.com/), and the Free and Pro plans in the [Plans](https://app.useautumn.com/products) tab.
* On the [Plans](https://app.useautumn.com/products) page, click **Create Plan**.
* Name the plan (eg, "Free") and select plan type `Free`
* Toggle the `auto-enable` flag, so that the plan is assigned whenever customers are created
* In the plan editor, click **Add Feature to Plan**, and create a `Metered`, `Consumable` feature for "messages"
* Configure the plan to grant `5` messages, and set the interval to `per month`
* Click **Save**
* On the [Plans](https://app.useautumn.com/products) page, click **Create Plan**.
* Name the plan (eg, "Pro") and select plan type `Paid`, `Recurring`, and set the price to `$20` per month
* In the plan editor, click **Add Feature to Plan**, and add the `messages` feature that you created in the Free plan
* Configure the plan to grant `100` messages, and set the interval to `per month`
* Click **Save**
[Create an Autumn Secret key](https://app.useautumn.com/sandbox/dev?tab=api_keys), and paste it in your `.env` variables. Then, install the Autumn SDK. If you're using the CLI, this will be done for you.
```bash .env theme={null}
AUTUMN_SECRET_KEY=am_sk_test_42424242...
```
```bash bun theme={null}
bun add autumn-js
```
```bash npm theme={null}
npm install autumn-js
```
```bash pnpm theme={null}
pnpm add autumn-js
```
```bash yarn theme={null}
yarn add autumn-js
```
```bash pip theme={null}
pip install autumn-sdk
```
When the customer signs up, create an Autumn customer for them. Autumn will automatically enable the Free plan, since you marked it with the `auto-enable` flag.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({
secretKey: "am_sk_42424242",
});
const customer = await autumn.customers.getOrCreate({
customerId: "user_or_org_id_from_auth",
name: "John Doe",
email: "john@example.com",
});
```
```python Python theme={null}
import asyncio
from autumn_sdk import Autumn
autumn = Autumn('am_sk_42424242')
async def main():
customer = await autumn.customers.get_or_create(
customer_id="user_or_org_id_from_auth",
name="John Doe",
email="john@example.com",
)
asyncio.run(main())
```
```bash cURL theme={null}
curl --request POST \
--url https://api.useautumn.com/v1/customers \
--header 'Authorization: Bearer am_sk_42424242' \
--header 'Content-Type: application/json' \
--data '{
"customer_id": "user_or_org_id_from_auth",
"name": "John Doe",
"email": "john@example.com"
}'
```
Autumn's customer ID is the same as your internal user or org ID generated
from your auth provider. No need to store any extra IDs.
In the Autumn dashboard, you will see your user under the [customers](https://app.useautumn.com/customers) page.
Call `attach` when the customer wants to purchase the Pro plan. This will return a Stripe payment URL. Once they've paid, Autumn will grant access to "100 messages per month" defined in Step 1.
```typescript TypeScript theme={null}
import { Autumn } from "autumn-js";
const autumn = new Autumn({
secretKey: "am_sk_42424242",
});
const response = await autumn.billing.attach({
customerId: "user_or_org_id_from_auth",
planId: "pro",
redirectMode: "always",
});
// Redirect customer to complete payment or confirm plan change
redirect(response.paymentUrl);
```
```python Python theme={null}
import asyncio
from autumn_sdk import Autumn
autumn = Autumn('am_sk_42424242')
async def main():
response = await autumn.billing.attach(
customer_id='user_or_org_id_from_auth',
plan_id='pro',
redirect_mode='always',
)
asyncio.run(main())
```
```bash cURL theme={null}
curl -X POST 'https://api.useautumn.com/v1/attach' \
-H 'Authorization: Bearer am_sk_42424242' \
-H 'Content-Type: application/json' \
-d '{
"customer_id": "user_or_org_id_from_auth",
"plan_id": "pro",
"redirect_mode": "always"
}'
```
Use Stripe's test card `4242 4242 4242 4242` to make a purchase in sandbox.
You can enter any Expiry and CVV.
This can be used for any plan changes scenario (upgrades, downgrades, one-time topups, renewals, etc).
Upgrades will happen immediately, and downgrades will be scheduled for the next billing cycle.
The **`redirectMode: "always"`** flag will always return a payment URL.
New purchases redirect to Stripe Checkout to enter payment details, and subsequent charges redirect to an Autumn hosted, one-click confirmation page.
You can build your own billing confirmation flows by using the [previewAttach](/api-reference/billing/previewAttach) function.
**Next: Track and limit usage**
Now that the plan is enabled and you've handled payments, you can now make sure that customers have the access to the right features and limits based on their plan.
Enforce usage limits and feature permissions using Autumn's `check` and
`track` functions
# Working with balances
Source: https://docs.useautumn.com/documentation/lakehouse/balance-semantics
What v2_3_balances, v2_3_breakdowns, and v2_3_rollovers actually mean — and how to reconstruct the figures the API and dashboard show.
**Available on request** — The Autumn Lakehouse is provisioned per customer. Contact us at [hey@useautumn.com](mailto:hey@useautumn.com) to get access.
`v2_3_balances` and `v2_3_breakdowns` look like a tidy relational schema, but they aren't one. They are **denormalized snapshots of Autumn's read-time balance computation** — the same computation behind `GET /customers/:id` and the dashboard. Read them as columns named after their source values rather than as a schema you can do naive arithmetic on, and the surprises below disappear.
If you only take one thing from this page: **the warehouse keeps every entitlement row, the API does not.** To reproduce an API or dashboard figure you must re-apply the filter the API applies — active products, non-expired entitlements, current cycle. And **add the rollovers back in**, because they live in their own table now.
## The model in one paragraph
For each feature, the API gathers a customer's **active** `customer_entitlement` rows, computes a small set of values per row (`included_grant`, `prepaid_grant`, `remaining`, `usage`, `overage`), and sums them into one balance. The ETL materializes exactly this: `v2_3_breakdowns` is one row **per entitlement** (the per-row values), and `v2_3_balances` is the `GROUP BY customer × feature × scope` sum over it. Two differences matter: the ETL aggregates over **all** entitlement rows in your database while the API first filters to the active, current set, and the ETL leaves rollover balances out of both tables entirely.
## Why your numbers look inflated
`v2_3_breakdowns` is built from a plain join over `customer_entitlements` with **no status, expiry, or cycle filter**. Every entitlement row your account has ever held is in there:
* superseded / cancelled product **versions**,
* past reset **cycles** that already rolled over,
* pre-seeded **future** cycles.
The API, by contrast, keeps only entitlements whose product is **active** (status `active`, or `past_due` if your org enables `include_past_due`) and whose `expires_at` is in the future, then dedups and sums.
So a single `v2_3_balances` row can sum *many lifetimes* of `usage` for one customer × feature. This is **not** because `usage` is a lifetime accumulator — each entitlement's `usage` is its own current value. It's because the row aggregates over entitlements the API would have thrown away. A pooled balance that reads `granted = 53,000`, `usage = 3,408,161`, `remaining = +10,312` is not a corrupted row — it is dozens of historical entitlements summed together. Filter to the active, current-cycle set and it reconciles.
## Per-column meaning
These are the values the ETL writes, verbatim from the read-time math.
| Column (both tables unless noted) | Definition |
| --------------------------------- | -------------------------------------------------------------------------------- |
| `included_grant` *(breakdowns)* | `allowance × plan quantity + adjustment` |
| `prepaid_grant` *(breakdowns)* | prepaid quantity × billing units (0 unless a prepaid price is linked) |
| `granted` *(balances)* | `Σ(included_grant + prepaid_grant)` |
| `usage` | `included_grant + prepaid_grant - balance` per row (signed balance), then summed |
| `remaining` | `max(0, balance)` per row — **floored at 0** — then summed |
| `overage` | **not stored** — see below |
| rollover balance | **not on either table** — join `v2_3_rollovers`, see below |
Two consequences fall straight out of these definitions:
1. **`remaining` is floored.** Each entitlement contributes `max(0, balance)`, never a negative. You cannot recover how far a balance went negative from `remaining` — that information lives only in `usage`.
2. **`usage` carries the sign.** Because `usage = granted - balance` (per row), `usage - granted = -balance`. When a balance goes negative (overage), `usage` exceeds `granted` by exactly that amount. This is the hook used to reconstruct overage.
### `granted`, `remaining`, `usage` are not a closed triple
`remaining ≠ granted - usage`. They diverge for two independent reasons, both by design:
* **Manual "Set Balance"** writes `balance` directly, decoupling it from `granted`. Set a balance below zero and `usage` (= `granted - balance`) inflates past `granted` with no real consumption behind it — the "spurious negative balance / huge usage" artifact.
* **The flooring** of `remaining` (above) breaks the identity whenever any entitlement is in overage.
Treat each column as the named sum it is, not as a term in an equation. Rollovers used to be a third reason — they were layered into all three columns as separate `rollover_*` terms that didn't cancel. They no longer appear here at all, which makes the columns cleaner but means you have to add them yourself.
## Rollovers live in their own table
Rollover **config** (`rollover_max`, `rollover_max_percentage`, and the two expiry fields) has always been visible, on `v2_3_plan_items`. Rollover **balances** were not in the lakehouse at all — so `balances.remaining` and `balances.usage` understated the real figures for every customer holding a rollover, silently. `v2_3_rollovers` fixes that. It is a correctness fix, not a convenience table: if you built a report on rollover-enabled features before it existed, that report was wrong and should be re-run.
One row per rollover grant. Join `internal_breakdown_id` → `v2_3_breakdowns.internal_id` to attach a rollover to the entitlement it carried over from; `internal_plan_item_id` gets you the config that produced it.
It is a separate table rather than extra columns on `v2_3_breakdowns` because rollovers are **sparse** — only about 6.8% of customer entitlements carry one — so folding them in would hang mostly-null columns off every breakdown row to serve a small minority of them. One entitlement can also hold several grants with different expiry dates, which no fixed set of columns represents.
**Rollovers expire, and the table keeps the expired ones.** `expires_at` null means *never expires*; a past `expires_at` means the grant is dead but still present. Sum `balance` without a filter and you overstate what the customer holds — always guard with `(expires_at IS NULL OR expires_at > now)`, spelled `(coalesce(expires_at, 0) = 0 OR expires_at > toUnixTimestamp(now()) * 1000)` in ClickHouse.
Aggregate rollovers in a subquery **before** joining them to breakdowns — one entitlement can hold several grants, and a direct join fans the breakdown row out so its `remaining` gets counted once per rollover. There is a ready-to-run query in [Querying → Balance including rollovers](/documentation/lakehouse/querying#balance-including-rollovers).
Rollover balance also feeds back into overage: unspent rollover is available allowance, so a customer who looks over their grant on `v2_3_breakdowns` alone may not be in overage once rollovers are counted. The leaderboard query below omits them — fold them in if your features roll over.
## Overage is derived, not stored — and there are two of them
There is **no overage column** on `v2_3_balances` or `v2_3_breakdowns`. Overage is computed at read time, and there are **two distinct figures** that are easy to conflate. They use the same per-row quantity (`usage - granted = -balance`) but floor at different points, so they give different answers.
**Billable overage** — what Autumn invoices. Per entitlement, `max(0, -balance)`, **floored per row, then summed**. Equivalently `Σ max(0, usage - included_grant - prepaid_grant)`. An undrawn grant on one entitlement never reduces the bill on another.
```text theme={null}
billable_overage = Σ max(0, usage - included_grant - prepaid_grant) -- floor each row, then sum
```
**Displayed overage** — what the balance header and dashboard show. The **feature-level net**, summed first and floored once: `max(0, Σusage - Σgranted)`. Because `balances.usage` and `balances.granted` already net per-entitlement surpluses against deficits, an undrawn grant on one entitlement **does** offset an overage on another.
```text theme={null}
displayed_overage = max(0, Σusage - Σgranted) -- sum first, then floor once
```
**These two diverge by exactly the undrawn grants** (`Σ max(0, granted - usage)`), and the difference can be large. For one real customer, billable overage was ≈ `824k` while displayed (dashboard) overage was ≈ `715k` — a ≈ `110k` gap of unused allowance and lifetime grants that offset the deficit in the net but not in the per-row floor. The absolute figures drift each cycle; the gap structure does not. The dashboard balance header shows **displayed** — decide which one you mean before you report it, and label it.
Either way, overage is only meaningful where a usage-based / overage-allowed price exists — a capped feature never goes negative.
The leaderboard query in [Querying → Current-period overage](/documentation/lakehouse/querying#current-period-overage) computes the **displayed** net (to match the dashboard) and shows the billable variant alongside.
## The active + current-cycle filter
This is the filter the API applies and the warehouse does not. Re-apply it before any balance, usage, or overage query.
1. **Active plan only.** Keep breakdown rows whose `internal_customer_product_id` matches an active subscription — it **is** `v2_3_subscriptions.internal_id`, so this is one direct equality against the customer's own subscription row, and its `status` is right there. (Don't match on `internal_product_id` instead — it identifies the shared *plan version* rather than the customer's copy of it, so you'd have to match on customer **and** plan and hope the customer had held that plan only once.) If your org enables `include_past_due`, also keep `past_due`. One-off entitlements (`reset_interval = 'one_off'`) are always live. A row whose `internal_customer_product_id` matches a `v2_3_purchases` row instead is a one-off purchase, not a subscription.
2. **Current cycle only.** An entitlement carries one row per reset cycle it has lived through. The current cycle is the one whose reset is the **earliest still in the future**: per `(internal_customer_id, internal_customer_product_id)`, `min(reset_resets_at)` where `reset_resets_at > now`. `one_off` rows have no cycle and are always kept.
3. **Scope.** Keep `coalesce(entity_id, '') = ''` for customer-scoped totals — but note this now *excludes* entity-scoped entitlements rather than deduping, because each entitlement produces exactly one row. Customers with `config.disable_pooled_balance` set track per-entity instead; for those, sum the per-entity rows. See [Querying → Pooled vs per-entity](/documentation/lakehouse/querying#pooled-vs-per-entity-rows).
4. **Not expired.** Drop rows whose `expires_at` is in the past.
5. **Add rollovers.** Sum the unexpired `v2_3_rollovers.balance` for the surviving breakdown rows — the API includes them and these tables don't.
A ready-to-run query that applies all of this and reproduces the dashboard's overage leaderboard is in [Querying → Current-period overage](/documentation/lakehouse/querying#current-period-overage).
## Deduction order (why monthly drains before lifetime)
When usage is recorded, Autumn deducts from entitlements **shortest-reset-interval-first** (a daily grant drains before a monthly, which drains before a lifetime/`one_off`), after a few higher-priority rules — entity-scoped before pooled when tracking an entity, unlimited first, prepaid before pay-per-use. This is why, when a customer has both a monthly grant and a lifetime grant for the same feature, the monthly empties first and overage lands on whichever pool is drained last. It matters for analytics because it determines **which** breakdown row shows the overage, not just the total.
## Footgun: `IS NULL` throws on these tables
In **ClickHouse**, on the Iceberg balances/breakdowns/rollovers/flags tables, `WHERE entity_id IS NULL` raises `NOT_FOUND_COLUMN_IN_BLOCK` (it reaches for an unmaterialized `entity_id.null` subcolumn). Use `coalesce(entity_id, '') = ''` instead, everywhere you'd reach for `IS NULL` — including `v2_3_rollovers.expires_at`, where null carries real meaning ("never expires") and the numeric form is `coalesce(expires_at, 0) = 0`. BigQuery is unaffected; plain `IS NULL` works there. See [Querying → Pooled vs per-entity](/documentation/lakehouse/querying#pooled-vs-per-entity-rows).
# Connecting
Source: https://docs.useautumn.com/documentation/lakehouse/connecting
Attach ClickHouse or BigQuery to your Autumn Lakehouse catalog.
**Available on request** — The Autumn Lakehouse is provisioned per customer. Contact us at [hey@useautumn.com](mailto:hey@useautumn.com) to get access.
When your Lakehouse is provisioned, Autumn privately sends you:
* Your **catalog** and **namespace** names (the namespace is where your `v2_3_*` tables live).
* A **scoped access key and secret** for the underlying object storage.
* The **region**: `us-east-2`.
Keep these credentials private. If you're connecting **BigQuery**, you get a **project** and **dataset** instead of a catalog, namespace, and storage key — Autumn owns the external connection, so there are no object-storage credentials for you to hold. Then connect your engine below.
#### Add a Data Lake Catalog
In ClickHouse Cloud, go to **Data Sources → Add → Data Lake Catalog → AWS Glue**.
#### Configure the catalog
Set the **region** to `us-east-2`, then paste the **access key** and **secret** Autumn sent you.
#### Save and browse
Save the connection. The catalog mounts as a database, and your tables appear as `` ``.`.v2_3_
#### Access the dataset
Autumn provisions your Iceberg tables as BigLake external tables in a BigQuery dataset you're granted access to. We share the **project** and **dataset** names with you during onboarding — you don't create the external connection yourself.
#### Verify access
List the dataset to confirm the tables are visible. They appear as `` `..v2_3_
## Test the connection
Run a quick count against any table to confirm everything is wired up:
```sql theme={null}
SELECT count() FROM ; -- BigQuery: COUNT(*)
```
Once that returns, head to the [Schema Reference](/documentation/lakehouse/schema) to see what's available, then [Querying](/documentation/lakehouse/querying) for examples.
If you notice the number seems lower than expected, it's because it may take a few minutes to a few hours for your data warehouse to catch up.
# Lakehouse Overview
Source: https://docs.useautumn.com/documentation/lakehouse/overview
Query your full Autumn dataset directly from your own data warehouse.
**Available on request** — The Autumn Lakehouse is provisioned per customer. Contact us at [hey@useautumn.com](mailto:hey@useautumn.com) to get access.
The Autumn Lakehouse mirrors your entire Autumn dataset — customers, plans, subscriptions, invoices, balances, events, and more — into your own data warehouse as [Apache Iceberg](https://iceberg.apache.org/) tables. You read it directly with **ClickHouse** or **BigQuery**, no API pagination required.
It's built for analytics: BI dashboards, revenue and usage reporting, cohort analysis, and joining Autumn's billing data against your own product data — all in SQL, against the full history.
Every object is delivered as a table named `v2_3_