{
"type": "billing.updated",
"data": {
"object": "billing.updated",
"customer_id": "cus_123",
"plan_changes": [
{
"action": "activated",
"subscription": {
"plan_id": "pro",
"status": "active",
"past_due": false,
"started_at": 1779000000000,
"canceled_at": null,
"expires_at": null,
"trial_ends_at": null,
"current_period_start": 1779000000000,
"current_period_end": 1781592000000
},
"previous_attributes": null,
"item_changes": []
},
{
"action": "expired",
"subscription": {
"plan_id": "free",
"status": "expired",
"past_due": false,
"started_at": 1776000000000,
"canceled_at": 1779000000000,
"expires_at": 1779000000000,
"trial_ends_at": null,
"current_period_start": null,
"current_period_end": null
},
"previous_attributes": {
"status": "active"
},
"item_changes": []
}
],
"tags": []
}
}Billing
Plans 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.
WEBHOOK
billing.updated
{
"type": "billing.updated",
"data": {
"object": "billing.updated",
"customer_id": "cus_123",
"plan_changes": [
{
"action": "activated",
"subscription": {
"plan_id": "pro",
"status": "active",
"past_due": false,
"started_at": 1779000000000,
"canceled_at": null,
"expires_at": null,
"trial_ends_at": null,
"current_period_start": 1779000000000,
"current_period_end": 1781592000000
},
"previous_attributes": null,
"item_changes": []
},
{
"action": "expired",
"subscription": {
"plan_id": "free",
"status": "expired",
"past_due": false,
"started_at": 1776000000000,
"canceled_at": 1779000000000,
"expires_at": 1779000000000,
"trial_ends_at": null,
"current_period_start": null,
"current_period_end": null
},
"previous_attributes": {
"status": "active"
},
"item_changes": []
}
],
"tags": []
}
}Payload Fields
string
required
string
required
The ID of the customer whose plans changed.
string | null
The ID of the entity, if the changes are scoped to a specific entity.
object[]
required
The plans that were activated, scheduled, updated, or expired.
Show properties
Show properties
string | null
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.
'activated' | 'scheduled' | 'updated' | 'expired'
required
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).
object
The subscription as it stands after this change. Present when the plan is billed as a recurring subscription.
Show properties
Show properties
string
required
The ID of the customer plan.
'active' | 'scheduled' | 'expired'
required
The current status of the subscription on the customer.
boolean
required
Whether the subscription has overdue payments.
number | null
required
When the subscription started, in milliseconds since the Unix epoch.
number | null
required
When the subscription was canceled, in milliseconds since the Unix epoch, or null if not canceled.
number | null
required
When the subscription ends, in milliseconds since the Unix epoch, or null if no expiry is set.
number | null
required
When the trial ends, in milliseconds since the Unix epoch. Null when not actively trialing.
number | null
required
Start of the current billing period, or null if not applicable.
number | null
required
End of the current billing period, or null if not applicable.
object
The purchase as it stands after this change. Present when the plan is a one-off purchase.
object | null
required
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.
Show properties
Show properties
'active' | 'scheduled' | 'expired'
The current status of the subscription on the customer.
boolean
Whether the subscription has overdue payments.
number | null
When the subscription was canceled, in milliseconds since the Unix epoch, or null if not canceled.
number | null
When the subscription ends, in milliseconds since the Unix epoch, or null if no expiry is set.
number | null
When the trial ends, in milliseconds since the Unix epoch. Null when not actively trialing.
object
Content-level change to the plan definition for this customer plan (items, base price, free trial).
Show properties
Show properties
object
The plan after the change. Omitted unless the caller expands it.
Show properties
Show properties
string
required
Unique identifier for the plan.
string
required
Display name of the plan.
string | null
required
Optional description of the plan.
string | null
required
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
number
required
Version number of the plan. Incremented when plan configuration changes.
string | null
User-facing version identity. Defaults to v{n} when the version is minted.
boolean
Whether this is the active version of the plan. At most one version is active.
boolean
required
Whether this is an add-on plan that can be attached alongside a main plan.
boolean
required
If true, this plan is automatically attached when a customer is created. Used for free plans.
object | null
required
Base recurring price for the plan. Null for free plans or usage-only plans.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
Number of intervals per billing cycle. Defaults to 1.
object
object[]
required
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature this item configures.
object
The full feature object if expanded.
Show properties
Show properties
string
required
The ID of the feature, used to refer to it in other API calls like /track or /check.
string | null
The name of the feature.
'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'
required
The type of the feature
object | null
object[] | null
boolean | null
Whether or not the feature is archived.
number
required
Number of free units included. For consumable features, balance resets to this number each interval.
boolean
required
Whether the customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object | null
required
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
Show properties
Show properties
'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
The interval at which the feature balance resets (e.g. ‘month’, ‘year’). For consumable features, usage resets to 0 and included units are restored.
number
Number of intervals between resets. Defaults to 1.
object | null
required
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Show properties
Show properties
number
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’ (tiered prices carry per-currency amounts on each tier).
object[]
Tiered pricing configuration. Each tier’s ‘to’ INCLUDES the included amount. Either ‘tiers’ or ‘amount’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval for this price. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
required
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for features like seats where customers pay upfront, ‘usage_based’ for pay-as-you-go after included usage.
number | null
required
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
object
object
Rollover configuration for unused units. If set, unused included units roll over to the next period.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object
Payment processors this plan is connected to. Omitted when unset.
Show properties
Show properties
object | null
object | null
Show properties
Show properties
object[]
required
Every RevenueCat product that maps to this plan. Replaces the current set.
object
Free trial configuration. If set, new customers can try this plan before being charged.
Show properties
Show properties
number
required
Number of duration_type periods the trial lasts.
'day' | 'month' | 'year'
required
Unit of time for the trial duration (‘day’, ‘month’, ‘year’).
boolean
required
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
'bill' | 'revert'
Behavior when the trial ends. ‘bill’ charges the customer (default). ‘revert’ expires the trial and restores the customer’s previous plan.
number
required
Unix timestamp (ms) when the plan was created.
'sandbox' | 'live'
required
Environment this plan belongs to (‘sandbox’ or ‘live’).
boolean
required
Whether the plan is archived. Archived plans cannot be attached to new customers.
object
required
Miscellaneous plan-level configuration flags.
Show properties
Show properties
boolean
required
If true, entitlements attached to this plan will still reset on schedule even when the customer’s product is in a past_due state.
object
Plan-level billing controls used as customer defaults.
Show properties
Show properties
object[]
List of auto top-up configurations per feature.
Show properties
Show properties
string
required
The ID of the feature (credit balance) to auto top-up.
boolean
required
Whether auto top-up is enabled.
number
required
When the balance drops below this threshold, an auto top-up will be purchased.
number
required
Amount of credits to add per auto top-up.
object
boolean
When true, auto top-up creates a send_invoice invoice instead of auto-charging.
object[]
List of overage spend limits per feature (caps overage spend).
Show properties
Show properties
string
Optional feature ID this spend limit applies to.
boolean
required
Whether the overage spend limit is enabled.
'absolute' | 'usage_percentage'
How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
number
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
boolean
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
object[]
List of hard usage caps per feature (max units per interval).
Show properties
Show properties
string
required
The feature this usage limit applies to.
boolean
required
Whether this usage limit is enabled.
number
required
Maximum units allowed per interval.
'day' | 'week' | 'month' | 'year'
required
Interval for the cap, aligned to the customer’s billing cycle.
'billing_cycle' | 'utc'
Window alignment. ‘billing_cycle’ phases the interval to the customer’s renewal time; ‘utc’ aligns to the UTC calendar.
object[]
List of usage alert configurations per feature.
Show properties
Show properties
string
The feature ID this alert applies to.
boolean
required
Whether this usage alert is enabled.
number
required
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'
required
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
'balance' | 'included' | 'recurring' | 'usage_limit'
required
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.
object
Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter.
Show properties
Show properties
string
required
string
Optional user-defined label to distinguish multiple alerts on the same feature.
object
required
Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
object
Show properties
Show properties
boolean
Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
'active' | 'scheduled'
The customer’s current status with this plan. ‘active’ if attached, ‘scheduled’ if pending activation.
boolean
Whether the customer’s active instance of this plan is set to cancel.
boolean
Whether the customer is currently on a free trial of this plan.
'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase'
required
The action that would occur if this plan were attached to the customer.
string | null
required
Deprecated. Use variant_details.base_plan_id instead. If this is a variant, the ID of the base plan it was created from.
object
Details about how this variant relates to its latest base plan.
Show properties
Show properties
string
required
The ID of the base plan this variant was derived from.
object
The customization that transforms the base plan into this variant.
Show properties
Show properties
object | null
Base price configuration for a plan.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
object[]
Items to add to the plan.
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature to configure.
number
Number of free units included. Balance resets to this each interval for consumable features.
boolean
If true, customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object
object
Pricing for usage beyond included units. Omit for free features.
Show properties
Show properties
number
Price per billing_units after included usage. Either ‘amount’ or ‘tiers’ is required.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’.
object[]
Tiered pricing. Either ‘amount’ or ‘tiers’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for upfront payment (seats), ‘usage_based’ for pay-as-you-go.
number | null
Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
object
Proration settings for prepaid features. Controls mid-cycle quantity change billing.
Show properties
Show properties
object
Rollover config for unused units. If set, unused included units carry over.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object[]
Filters selecting items to remove from the plan.
Show properties
Show properties
string
Match items linked to this feature.
'prepaid' | 'usage_based'
Match items with this billing method (prepaid or usage_based).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
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.
integer
Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
number
Match items whose grant equals this included usage. Omitted is a wildcard.
object | null
Free trial configuration for a plan.
Show properties
Show properties
object
Override the plan’s billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
Show properties
Show properties
object[]
Show properties
Show properties
string
required
The ID of the feature (credit balance) to auto top-up.
boolean
required
Whether auto top-up is enabled.
number
required
When the balance drops below this threshold, an auto top-up will be purchased.
number
required
Amount of credits to add per auto top-up.
object
Optional rate limit to cap how often auto top-ups occur. Pass count to set the current window’s consumed top-ups.
Show properties
Show properties
'hour' | 'day' | 'week' | 'month'
required
The time interval for the purchase limit window.
number
required
Number of intervals in the purchase limit window.
number
required
Maximum number of auto top-ups allowed within the interval.
number
Set the current window’s consumed auto top-up count. Omit to leave runtime state unchanged.
boolean
When true, auto top-up creates a send_invoice invoice instead of auto-charging.
object[]
Show properties
Show properties
string
Optional feature ID this spend limit applies to.
boolean
required
Whether the overage spend limit is enabled.
'absolute' | 'usage_percentage'
How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
number
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
boolean
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
object[]
Show properties
Show properties
string
required
The feature this usage limit applies to.
boolean
required
Whether this usage limit is enabled.
number
required
Maximum units allowed per interval.
'day' | 'week' | 'month' | 'year'
required
Interval for the cap, aligned to the customer’s billing cycle.
'billing_cycle' | 'utc'
Window alignment. ‘billing_cycle’ phases the interval to the customer’s renewal time; ‘utc’ aligns to the UTC calendar.
object[]
Show properties
Show properties
string
The feature ID this alert applies to.
boolean
required
Whether this usage alert is enabled.
number
required
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'
required
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
'balance' | 'included' | 'recurring' | 'usage_limit'
required
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.
object
Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter.
Show properties
Show properties
string
required
string
Optional user-defined label to distinguish multiple alerts on the same feature.
object[]
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.
Show properties
Show properties
string
required
string
integer
boolean
object | null
Show properties
Show properties
object | null
Base price configuration for a plan.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
object[]
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature to configure.
number
Number of free units included. Balance resets to this each interval for consumable features.
boolean
If true, customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object
object
Pricing for usage beyond included units. Omit for free features.
Show properties
Show properties
number
Price per billing_units after included usage. Either ‘amount’ or ‘tiers’ is required.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’.
object[]
Tiered pricing. Either ‘amount’ or ‘tiers’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for upfront payment (seats), ‘usage_based’ for pay-as-you-go.
number | null
Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
object
Proration settings for prepaid features. Controls mid-cycle quantity change billing.
Show properties
Show properties
object
Rollover config for unused units. If set, unused included units carry over.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object[]
Show properties
Show properties
string
Match items linked to this feature.
'prepaid' | 'usage_based'
Match items with this billing method (prepaid or usage_based).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
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.
integer
Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
number
Match items whose grant equals this included usage. Omitted is a wildcard.
object
object | null
required
Sparse map of scalar plan fields that changed, holding their previous values. Null when the plan is new.
Show properties
Show properties
string | null
Unique identifier for the plan.
string | null
Display name of the plan.
string | null | null
Optional description of the plan.
string | null | null
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
boolean | null
Whether this is an add-on plan that can be attached alongside a main plan.
boolean | null
If true, this plan is automatically attached when a customer is created. Used for free plans.
object | null
Miscellaneous plan-level configuration flags.
Show properties
Show properties
boolean
required
If true, entitlements attached to this plan will still reset on schedule even when the customer’s product is in a past_due state.
boolean | null
Whether this is the active version of the plan. At most one version is active.
boolean | null
Whether the plan is archived. Archived plans cannot be attached to new customers.
object | null
Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
object | null
Previous payment processors when they changed. Null when the plan had none.
Show properties
Show properties
object | null
object | null
Show properties
Show properties
object[]
required
Every RevenueCat product that maps to this plan. Replaces the current set.
object | null
Previous free trial when it changed. Null when the plan had none.
Show properties
Show properties
number
required
Number of duration_type periods the trial lasts.
'day' | 'month' | 'year'
required
Unit of time for the trial duration (‘day’, ‘month’, ‘year’).
boolean
required
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
'bill' | 'revert'
Behavior when the trial ends. ‘bill’ charges the customer (default). ‘revert’ expires the trial and restores the customer’s previous plan.
object | null
Sparse previous billing_controls — only keys that changed. Null when unset; a null lane was unset before.
Show properties
Show properties
object[] | null
List of auto top-up configurations per feature.
Show properties
Show properties
string
required
The ID of the feature (credit balance) to auto top-up.
boolean
required
Whether auto top-up is enabled.
number
required
When the balance drops below this threshold, an auto top-up will be purchased.
number
required
Amount of credits to add per auto top-up.
object
boolean
When true, auto top-up creates a send_invoice invoice instead of auto-charging.
object[] | null
List of overage spend limits per feature (caps overage spend).
Show properties
Show properties
string
Optional feature ID this spend limit applies to.
boolean
required
Whether the overage spend limit is enabled.
'absolute' | 'usage_percentage'
How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
number
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
boolean
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
object[] | null
List of hard usage caps per feature (max units per interval).
Show properties
Show properties
string
required
The feature this usage limit applies to.
boolean
required
Whether this usage limit is enabled.
number
required
Maximum units allowed per interval.
'day' | 'week' | 'month' | 'year'
required
Interval for the cap, aligned to the customer’s billing cycle.
'billing_cycle' | 'utc'
Window alignment. ‘billing_cycle’ phases the interval to the customer’s renewal time; ‘utc’ aligns to the UTC calendar.
object[] | null
List of usage alert configurations per feature.
Show properties
Show properties
string
The feature ID this alert applies to.
boolean
required
Whether this usage alert is enabled.
number
required
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'
required
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
'balance' | 'included' | 'recurring' | 'usage_limit'
required
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.
object
Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter.
Show properties
Show properties
string
required
string
Optional user-defined label to distinguish multiple alerts on the same feature.
object
Present when the plan’s price changed.
Show properties
Show properties
object | null | null
required
Base recurring price for the plan. Null for free plans or usage-only plans.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
Number of intervals per billing cycle. Defaults to 1.
object
object | null
required
The plan’s price after the change.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
Number of intervals per billing cycle. Defaults to 1.
object
object
Present when the plan’s free trial changed.
Show properties
Show properties
object | null
required
The plan’s free trial before the change. Null when none.
Show properties
Show properties
number
required
Number of duration_type periods the trial lasts.
'day' | 'month' | 'year'
required
Unit of time for the trial duration (‘day’, ‘month’, ‘year’).
boolean
required
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
'bill' | 'revert'
Behavior when the trial ends. ‘bill’ charges the customer (default). ‘revert’ expires the trial and restores the customer’s previous plan.
object | null
required
The plan’s free trial after the change. Null when none.
Show properties
Show properties
number
required
Number of duration_type periods the trial lasts.
'day' | 'month' | 'year'
required
Unit of time for the trial duration (‘day’, ‘month’, ‘year’).
boolean
required
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
'bill' | 'revert'
Behavior when the trial ends. ‘bill’ charges the customer (default). ‘revert’ expires the trial and restores the customer’s previous plan.
object[]
required
Feature items added to or removed from the plan.
Show properties
Show properties
'created' | 'deleted'
required
Whether the item was added to or removed from the plan.
string
required
The ID of the feature that was added or removed.
object
required
The plan item snapshot that was added or removed.
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature this item configures.
object
The full feature object if expanded.
Show properties
Show properties
string
required
The ID of the feature, used to refer to it in other API calls like /track or /check.
string | null
The name of the feature.
'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'
required
The type of the feature
object | null
object[] | null
boolean | null
Whether or not the feature is archived.
number
required
Number of free units included. For consumable features, balance resets to this number each interval.
boolean
required
Whether the customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object | null
required
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
Show properties
Show properties
'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
The interval at which the feature balance resets (e.g. ‘month’, ‘year’). For consumable features, usage resets to 0 and included units are restored.
number
Number of intervals between resets. Defaults to 1.
object | null
required
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Show properties
Show properties
number
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’ (tiered prices carry per-currency amounts on each tier).
object[]
Tiered pricing configuration. Each tier’s ‘to’ INCLUDES the included amount. Either ‘tiers’ or ‘amount’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval for this price. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
required
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for features like seats where customers pay upfront, ‘usage_based’ for pay-as-you-go after included usage.
number | null
required
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
object
object
Rollover configuration for unused units. If set, unused included units roll over to the next period.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object
Params that would transform the previous plan into the current one, including license upserts/removes.
Show properties
Show properties
object | null
Base price configuration for a plan.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
object[]
Items to add to the plan.
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature to configure.
number
Number of free units included. Balance resets to this each interval for consumable features.
boolean
If true, customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object
object
Pricing for usage beyond included units. Omit for free features.
Show properties
Show properties
number
Price per billing_units after included usage. Either ‘amount’ or ‘tiers’ is required.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’.
object[]
Tiered pricing. Either ‘amount’ or ‘tiers’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for upfront payment (seats), ‘usage_based’ for pay-as-you-go.
number | null
Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
object
Proration settings for prepaid features. Controls mid-cycle quantity change billing.
Show properties
Show properties
object
Rollover config for unused units. If set, unused included units carry over.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object[]
Filters selecting items to remove from the plan.
Show properties
Show properties
string
Match items linked to this feature.
'prepaid' | 'usage_based'
Match items with this billing method (prepaid or usage_based).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
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.
integer
Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
number
Match items whose grant equals this included usage. Omitted is a wildcard.
object | null
Free trial configuration for a plan.
Show properties
Show properties
object
Override the plan’s billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
Show properties
Show properties
object[]
Show properties
Show properties
string
required
The ID of the feature (credit balance) to auto top-up.
boolean
required
Whether auto top-up is enabled.
number
required
When the balance drops below this threshold, an auto top-up will be purchased.
number
required
Amount of credits to add per auto top-up.
object
Optional rate limit to cap how often auto top-ups occur. Pass count to set the current window’s consumed top-ups.
Show properties
Show properties
'hour' | 'day' | 'week' | 'month'
required
The time interval for the purchase limit window.
number
required
Number of intervals in the purchase limit window.
number
required
Maximum number of auto top-ups allowed within the interval.
number
Set the current window’s consumed auto top-up count. Omit to leave runtime state unchanged.
boolean
When true, auto top-up creates a send_invoice invoice instead of auto-charging.
object[]
Show properties
Show properties
string
Optional feature ID this spend limit applies to.
boolean
required
Whether the overage spend limit is enabled.
'absolute' | 'usage_percentage'
How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
number
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
boolean
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
object[]
Show properties
Show properties
string
required
The feature this usage limit applies to.
boolean
required
Whether this usage limit is enabled.
number
required
Maximum units allowed per interval.
'day' | 'week' | 'month' | 'year'
required
Interval for the cap, aligned to the customer’s billing cycle.
'billing_cycle' | 'utc'
Window alignment. ‘billing_cycle’ phases the interval to the customer’s renewal time; ‘utc’ aligns to the UTC calendar.
object[]
Show properties
Show properties
string
The feature ID this alert applies to.
boolean
required
Whether this usage alert is enabled.
number
required
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'
required
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
'balance' | 'included' | 'recurring' | 'usage_limit'
required
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.
object
Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter.
Show properties
Show properties
string
required
string
Optional user-defined label to distinguish multiple alerts on the same feature.
object[]
planLicenses created or overridden. Same shape as customize.upsert_licenses / licenses[] entries.
Show properties
Show properties
string
required
string
integer
boolean
object | null
Show properties
Show properties
object | null
Base price configuration for a plan.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
object[]
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature to configure.
number
Number of free units included. Balance resets to this each interval for consumable features.
boolean
If true, customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object
object
Pricing for usage beyond included units. Omit for free features.
Show properties
Show properties
number
Price per billing_units after included usage. Either ‘amount’ or ‘tiers’ is required.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’.
object[]
Tiered pricing. Either ‘amount’ or ‘tiers’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for upfront payment (seats), ‘usage_based’ for pay-as-you-go.
number | null
Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
object
Proration settings for prepaid features. Controls mid-cycle quantity change billing.
Show properties
Show properties
object
Rollover config for unused units. If set, unused included units carry over.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object[]
Show properties
Show properties
string
Match items linked to this feature.
'prepaid' | 'usage_based'
Match items with this billing method (prepaid or usage_based).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
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.
integer
Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
number
Match items whose grant equals this included usage. Omitted is a wildcard.
object
object[]
planLicenses created, updated, or removed on this plan. Omitted when none. Nested plan_change is core-only.
Show properties
Show properties
string
required
The plan offered as a license under this plan.
integer
required
The exact license-plan version pinned by this link.
string
Version slug of the license-plan row this link points at.
number
required
Number of license assignments included with this plan for free.
object
Arbitrary key-value metadata defined by you on this link.
object
The effective plan for this license link — the pinned version, with the link’s customize applied. Present when license plans are expanded.
Show properties
Show properties
string
required
Unique identifier for the plan.
string
required
Display name of the plan.
string | null
required
Optional description of the plan.
string | null
required
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
number
required
Version number of the plan. Incremented when plan configuration changes.
string | null
User-facing version identity. Defaults to v{n} when the version is minted.
boolean
Whether this is the active version of the plan. At most one version is active.
boolean
required
Whether this is an add-on plan that can be attached alongside a main plan.
boolean
required
If true, this plan is automatically attached when a customer is created. Used for free plans.
object | null
required
Base recurring price for the plan. Null for free plans or usage-only plans.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
Number of intervals per billing cycle. Defaults to 1.
object
object[]
required
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature this item configures.
object
The full feature object if expanded.
Show properties
Show properties
string
required
The ID of the feature, used to refer to it in other API calls like /track or /check.
string | null
The name of the feature.
'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'
required
The type of the feature
object | null
object[] | null
boolean | null
Whether or not the feature is archived.
number
required
Number of free units included. For consumable features, balance resets to this number each interval.
boolean
required
Whether the customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object | null
required
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
Show properties
Show properties
'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
The interval at which the feature balance resets (e.g. ‘month’, ‘year’). For consumable features, usage resets to 0 and included units are restored.
number
Number of intervals between resets. Defaults to 1.
object | null
required
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Show properties
Show properties
number
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’ (tiered prices carry per-currency amounts on each tier).
object[]
Tiered pricing configuration. Each tier’s ‘to’ INCLUDES the included amount. Either ‘tiers’ or ‘amount’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval for this price. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
required
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for features like seats where customers pay upfront, ‘usage_based’ for pay-as-you-go after included usage.
number | null
required
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
object
object
Rollover configuration for unused units. If set, unused included units roll over to the next period.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object
Payment processors this plan is connected to. Omitted when unset.
Show properties
Show properties
object | null
object | null
Show properties
Show properties
object[]
required
Every RevenueCat product that maps to this plan. Replaces the current set.
object
Free trial configuration. If set, new customers can try this plan before being charged.
Show properties
Show properties
number
required
Number of duration_type periods the trial lasts.
'day' | 'month' | 'year'
required
Unit of time for the trial duration (‘day’, ‘month’, ‘year’).
boolean
required
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
'bill' | 'revert'
Behavior when the trial ends. ‘bill’ charges the customer (default). ‘revert’ expires the trial and restores the customer’s previous plan.
number
required
Unix timestamp (ms) when the plan was created.
'sandbox' | 'live'
required
Environment this plan belongs to (‘sandbox’ or ‘live’).
boolean
required
Whether the plan is archived. Archived plans cannot be attached to new customers.
object
required
Miscellaneous plan-level configuration flags.
Show properties
Show properties
boolean
required
If true, entitlements attached to this plan will still reset on schedule even when the customer’s product is in a past_due state.
object
Plan-level billing controls used as customer defaults.
Show properties
Show properties
object[]
List of auto top-up configurations per feature.
Show properties
Show properties
string
required
The ID of the feature (credit balance) to auto top-up.
boolean
required
Whether auto top-up is enabled.
number
required
When the balance drops below this threshold, an auto top-up will be purchased.
number
required
Amount of credits to add per auto top-up.
object
boolean
When true, auto top-up creates a send_invoice invoice instead of auto-charging.
object[]
List of overage spend limits per feature (caps overage spend).
Show properties
Show properties
string
Optional feature ID this spend limit applies to.
boolean
required
Whether the overage spend limit is enabled.
'absolute' | 'usage_percentage'
How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
number
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
boolean
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
object[]
List of hard usage caps per feature (max units per interval).
Show properties
Show properties
string
required
The feature this usage limit applies to.
boolean
required
Whether this usage limit is enabled.
number
required
Maximum units allowed per interval.
'day' | 'week' | 'month' | 'year'
required
Interval for the cap, aligned to the customer’s billing cycle.
'billing_cycle' | 'utc'
Window alignment. ‘billing_cycle’ phases the interval to the customer’s renewal time; ‘utc’ aligns to the UTC calendar.
object[]
List of usage alert configurations per feature.
Show properties
Show properties
string
The feature ID this alert applies to.
boolean
required
Whether this usage alert is enabled.
number
required
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'
required
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
'balance' | 'included' | 'recurring' | 'usage_limit'
required
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.
object
Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter.
Show properties
Show properties
string
required
string
Optional user-defined label to distinguish multiple alerts on the same feature.
object
required
Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
object
Show properties
Show properties
boolean
Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
'active' | 'scheduled'
The customer’s current status with this plan. ‘active’ if attached, ‘scheduled’ if pending activation.
boolean
Whether the customer’s active instance of this plan is set to cancel.
boolean
Whether the customer is currently on a free trial of this plan.
'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase'
required
The action that would occur if this plan were attached to the customer.
string | null
required
Deprecated. Use variant_details.base_plan_id instead. If this is a variant, the ID of the base plan it was created from.
object
Details about how this variant relates to its latest base plan.
Show properties
Show properties
string
required
The ID of the base plan this variant was derived from.
object
The customization that transforms the base plan into this variant.
Show properties
Show properties
object | null
Base price configuration for a plan.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
object[]
Items to add to the plan.
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature to configure.
number
Number of free units included. Balance resets to this each interval for consumable features.
boolean
If true, customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object
object
Pricing for usage beyond included units. Omit for free features.
Show properties
Show properties
number
Price per billing_units after included usage. Either ‘amount’ or ‘tiers’ is required.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’.
object[]
Tiered pricing. Either ‘amount’ or ‘tiers’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for upfront payment (seats), ‘usage_based’ for pay-as-you-go.
number | null
Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
object
Proration settings for prepaid features. Controls mid-cycle quantity change billing.
Show properties
Show properties
object
Rollover config for unused units. If set, unused included units carry over.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object[]
Filters selecting items to remove from the plan.
Show properties
Show properties
string
Match items linked to this feature.
'prepaid' | 'usage_based'
Match items with this billing method (prepaid or usage_based).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
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.
integer
Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
number
Match items whose grant equals this included usage. Omitted is a wildcard.
object | null
Free trial configuration for a plan.
Show properties
Show properties
object
Override the plan’s billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
Show properties
Show properties
object[]
Show properties
Show properties
string
required
The ID of the feature (credit balance) to auto top-up.
boolean
required
Whether auto top-up is enabled.
number
required
When the balance drops below this threshold, an auto top-up will be purchased.
number
required
Amount of credits to add per auto top-up.
object
Optional rate limit to cap how often auto top-ups occur. Pass count to set the current window’s consumed top-ups.
Show properties
Show properties
'hour' | 'day' | 'week' | 'month'
required
The time interval for the purchase limit window.
number
required
Number of intervals in the purchase limit window.
number
required
Maximum number of auto top-ups allowed within the interval.
number
Set the current window’s consumed auto top-up count. Omit to leave runtime state unchanged.
boolean
When true, auto top-up creates a send_invoice invoice instead of auto-charging.
object[]
Show properties
Show properties
string
Optional feature ID this spend limit applies to.
boolean
required
Whether the overage spend limit is enabled.
'absolute' | 'usage_percentage'
How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
number
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
boolean
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
object[]
Show properties
Show properties
string
required
The feature this usage limit applies to.
boolean
required
Whether this usage limit is enabled.
number
required
Maximum units allowed per interval.
'day' | 'week' | 'month' | 'year'
required
Interval for the cap, aligned to the customer’s billing cycle.
'billing_cycle' | 'utc'
Window alignment. ‘billing_cycle’ phases the interval to the customer’s renewal time; ‘utc’ aligns to the UTC calendar.
object[]
Show properties
Show properties
string
The feature ID this alert applies to.
boolean
required
Whether this usage alert is enabled.
number
required
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'
required
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
'balance' | 'included' | 'recurring' | 'usage_limit'
required
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.
object
Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter.
Show properties
Show properties
string
required
string
Optional user-defined label to distinguish multiple alerts on the same feature.
object[]
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.
Show properties
Show properties
string
required
string
integer
boolean
object | null
Show properties
Show properties
object | null
Base price configuration for a plan.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
object[]
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature to configure.
number
Number of free units included. Balance resets to this each interval for consumable features.
boolean
If true, customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object
object
Pricing for usage beyond included units. Omit for free features.
Show properties
Show properties
number
Price per billing_units after included usage. Either ‘amount’ or ‘tiers’ is required.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’.
object[]
Tiered pricing. Either ‘amount’ or ‘tiers’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for upfront payment (seats), ‘usage_based’ for pay-as-you-go.
number | null
Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
object
Proration settings for prepaid features. Controls mid-cycle quantity change billing.
Show properties
Show properties
object
Rollover config for unused units. If set, unused included units carry over.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object[]
Show properties
Show properties
string
Match items linked to this feature.
'prepaid' | 'usage_based'
Match items with this billing method (prepaid or usage_based).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
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.
integer
Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
number
Match items whose grant equals this included usage. Omitted is a wildcard.
object
'created' | 'updated' | 'removed'
required
created = new planLicense; updated = row or effective content changed; removed = dropped.
object | null
required
Previous included / prepaid_only / version. Null when created or removed, or when no row scalar changed.
object | null
Diff of the license’s effective plan. Null when created, removed, or the effective content is unchanged.
Show properties
Show properties
object
The plan after the change. Omitted unless the caller expands it.
Show properties
Show properties
string
required
Unique identifier for the plan.
string
required
Display name of the plan.
string | null
required
Optional description of the plan.
string | null
required
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
number
required
Version number of the plan. Incremented when plan configuration changes.
string | null
User-facing version identity. Defaults to v{n} when the version is minted.
boolean
Whether this is the active version of the plan. At most one version is active.
boolean
required
Whether this is an add-on plan that can be attached alongside a main plan.
boolean
required
If true, this plan is automatically attached when a customer is created. Used for free plans.
object | null
required
Base recurring price for the plan. Null for free plans or usage-only plans.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
Number of intervals per billing cycle. Defaults to 1.
object
object[]
required
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature this item configures.
object
The full feature object if expanded.
Show properties
Show properties
string
required
The ID of the feature, used to refer to it in other API calls like /track or /check.
string | null
The name of the feature.
'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'
required
The type of the feature
object | null
object[] | null
boolean | null
Whether or not the feature is archived.
number
required
Number of free units included. For consumable features, balance resets to this number each interval.
boolean
required
Whether the customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object | null
required
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
Show properties
Show properties
'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
The interval at which the feature balance resets (e.g. ‘month’, ‘year’). For consumable features, usage resets to 0 and included units are restored.
number
Number of intervals between resets. Defaults to 1.
object | null
required
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Show properties
Show properties
number
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’ (tiered prices carry per-currency amounts on each tier).
object[]
Tiered pricing configuration. Each tier’s ‘to’ INCLUDES the included amount. Either ‘tiers’ or ‘amount’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval for this price. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
required
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for features like seats where customers pay upfront, ‘usage_based’ for pay-as-you-go after included usage.
number | null
required
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
object
object
Rollover configuration for unused units. If set, unused included units roll over to the next period.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object
Payment processors this plan is connected to. Omitted when unset.
Show properties
Show properties
object | null
object | null
Show properties
Show properties
object[]
required
Every RevenueCat product that maps to this plan. Replaces the current set.
object
Free trial configuration. If set, new customers can try this plan before being charged.
Show properties
Show properties
number
required
Number of duration_type periods the trial lasts.
'day' | 'month' | 'year'
required
Unit of time for the trial duration (‘day’, ‘month’, ‘year’).
boolean
required
Whether a payment method is required to start the trial. If true, customer will be charged after trial ends.
'bill' | 'revert'
Behavior when the trial ends. ‘bill’ charges the customer (default). ‘revert’ expires the trial and restores the customer’s previous plan.
number
required
Unix timestamp (ms) when the plan was created.
'sandbox' | 'live'
required
Environment this plan belongs to (‘sandbox’ or ‘live’).
boolean
required
Whether the plan is archived. Archived plans cannot be attached to new customers.
object
required
Miscellaneous plan-level configuration flags.
Show properties
Show properties
boolean
required
If true, entitlements attached to this plan will still reset on schedule even when the customer’s product is in a past_due state.
object
Plan-level billing controls used as customer defaults.
Show properties
Show properties
object[]
List of auto top-up configurations per feature.
Show properties
Show properties
string
required
The ID of the feature (credit balance) to auto top-up.
boolean
required
Whether auto top-up is enabled.
number
required
When the balance drops below this threshold, an auto top-up will be purchased.
number
required
Amount of credits to add per auto top-up.
object
boolean
When true, auto top-up creates a send_invoice invoice instead of auto-charging.
object[]
List of overage spend limits per feature (caps overage spend).
Show properties
Show properties
string
Optional feature ID this spend limit applies to.
boolean
required
Whether the overage spend limit is enabled.
'absolute' | 'usage_percentage'
How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
number
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
boolean
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
object[]
List of hard usage caps per feature (max units per interval).
Show properties
Show properties
string
required
The feature this usage limit applies to.
boolean
required
Whether this usage limit is enabled.
number
required
Maximum units allowed per interval.
'day' | 'week' | 'month' | 'year'
required
Interval for the cap, aligned to the customer’s billing cycle.
'billing_cycle' | 'utc'
Window alignment. ‘billing_cycle’ phases the interval to the customer’s renewal time; ‘utc’ aligns to the UTC calendar.
object[]
List of usage alert configurations per feature.
Show properties
Show properties
string
The feature ID this alert applies to.
boolean
required
Whether this usage alert is enabled.
number
required
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'
required
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
'balance' | 'included' | 'recurring' | 'usage_limit'
required
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.
object
Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter.
Show properties
Show properties
string
required
string
Optional user-defined label to distinguish multiple alerts on the same feature.
object
required
Arbitrary key-value metadata defined by you for your own use. Shared across all versions of the plan.
object
Show properties
Show properties
boolean
Whether the trial on this plan is available to this customer. For example, if the customer used the trial in the past, this will be false.
'active' | 'scheduled'
The customer’s current status with this plan. ‘active’ if attached, ‘scheduled’ if pending activation.
boolean
Whether the customer’s active instance of this plan is set to cancel.
boolean
Whether the customer is currently on a free trial of this plan.
'activate' | 'upgrade' | 'downgrade' | 'none' | 'purchase'
required
The action that would occur if this plan were attached to the customer.
string | null
required
Deprecated. Use variant_details.base_plan_id instead. If this is a variant, the ID of the base plan it was created from.
object
Details about how this variant relates to its latest base plan.
Show properties
Show properties
string
required
The ID of the base plan this variant was derived from.
object
The customization that transforms the base plan into this variant.
Show properties
Show properties
object | null
Base price configuration for a plan.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
object[]
Items to add to the plan.
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature to configure.
number
Number of free units included. Balance resets to this each interval for consumable features.
boolean
If true, customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object
object
Pricing for usage beyond included units. Omit for free features.
Show properties
Show properties
number
Price per billing_units after included usage. Either ‘amount’ or ‘tiers’ is required.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’.
object[]
Tiered pricing. Either ‘amount’ or ‘tiers’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for upfront payment (seats), ‘usage_based’ for pay-as-you-go.
number | null
Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
object
Proration settings for prepaid features. Controls mid-cycle quantity change billing.
Show properties
Show properties
object
Rollover config for unused units. If set, unused included units carry over.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.
object
Named rates chosen by event properties. The most specific match sets the rate; with no match the item’s own rate applies.
Show properties
Show properties
string
required
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
integer
Breaks ties between dimensions that match the same number of keys. Higher wins.
string
required
object
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
string
object[]
number
Credits consumed per billing-unit group.
object
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.
Show properties
Show properties
object[]
Filters selecting items to remove from the plan.
Show properties
Show properties
string
Match items linked to this feature.
'prepaid' | 'usage_based'
Match items with this billing method (prepaid or usage_based).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
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.
integer
Match items with this interval_count. Disambiguates between items that share an interval but differ in count.
number
Match items whose grant equals this included usage. Omitted is a wildcard.
object | null
Free trial configuration for a plan.
Show properties
Show properties
object
Override the plan’s billing controls (auto top-ups, spend limits, usage limits, usage alerts, overage allowed) for this customer.
Show properties
Show properties
object[]
Show properties
Show properties
string
required
The ID of the feature (credit balance) to auto top-up.
boolean
required
Whether auto top-up is enabled.
number
required
When the balance drops below this threshold, an auto top-up will be purchased.
number
required
Amount of credits to add per auto top-up.
object
Optional rate limit to cap how often auto top-ups occur. Pass count to set the current window’s consumed top-ups.
Show properties
Show properties
'hour' | 'day' | 'week' | 'month'
required
The time interval for the purchase limit window.
number
required
Number of intervals in the purchase limit window.
number
required
Maximum number of auto top-ups allowed within the interval.
number
Set the current window’s consumed auto top-up count. Omit to leave runtime state unchanged.
boolean
When true, auto top-up creates a send_invoice invoice instead of auto-charging.
object[]
Show properties
Show properties
string
Optional feature ID this spend limit applies to.
boolean
required
Whether the overage spend limit is enabled.
'absolute' | 'usage_percentage'
How overage_limit is interpreted: an absolute overage cap (default) or a percentage of the main-plan allowance.
number
Overage cap for the feature: absolute units, or a percent (e.g. 120) when limit_type is usage_percentage.
boolean
When true, overage for this feature is not posted to Stripe. Usage tracking and balance resets still behave normally.
object[]
Show properties
Show properties
string
required
The feature this usage limit applies to.
boolean
required
Whether this usage limit is enabled.
number
required
Maximum units allowed per interval.
'day' | 'week' | 'month' | 'year'
required
Interval for the cap, aligned to the customer’s billing cycle.
'billing_cycle' | 'utc'
Window alignment. ‘billing_cycle’ phases the interval to the customer’s renewal time; ‘utc’ aligns to the UTC calendar.
object[]
Show properties
Show properties
string
The feature ID this alert applies to.
boolean
required
Whether this usage alert is enabled.
number
required
The threshold value that triggers the alert. For usage or remaining, this is an absolute count. For usage_percentage or remaining_percentage, this is a percentage (0-100).
'usage' | 'usage_percentage' | 'remaining' | 'remaining_percentage'
required
Whether the threshold is an absolute count or a percentage of the usage allowance or remaining balance.
'balance' | 'included' | 'recurring' | 'usage_limit'
required
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.
object
Only valid with basis usage_limit. Points the alert at the usage limit carrying the same filter.
Show properties
Show properties
string
required
string
Optional user-defined label to distinguish multiple alerts on the same feature.
object[]
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.
Show properties
Show properties
string
required
string
integer
boolean
object | null
Show properties
Show properties
object | null
Base price configuration for a plan.
Show properties
Show properties
number
required
Base price amount for the plan, in major currency units (e.g. dollars).
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval (e.g. ‘month’, ‘year’).
number
object[]
Base price amounts in additional currencies. The base ‘amount’ is in the org’s default currency.
object[]
Show properties
Show properties
object | null
Bills this many feature units when outstanding overage reaches it.
Show properties
Show properties
number
required
string
required
The ID of the feature to configure.
number
Number of free units included. Balance resets to this each interval for consumable features.
boolean
If true, customer has unlimited access to this feature.
boolean
Whether entity-level grants contribute to a shared customer balance.
object
object
Pricing for usage beyond included units. Omit for free features.
Show properties
Show properties
number
Price per billing_units after included usage. Either ‘amount’ or ‘tiers’ is required.
object[]
Amounts in additional currencies for this flat price. The base ‘amount’ is in the org’s default currency. Only valid with ‘amount’, not ‘tiers’.
object[]
Tiered pricing. Either ‘amount’ or ‘tiers’ is required.
'graduated' | 'volume'
'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
required
Billing interval. For consumable features, should match reset.interval.
number
Number of intervals per billing cycle. Defaults to 1.
number
Units per price increment. Usage is rounded UP when billed (e.g. billing_units=100 means 101 rounds to 200).
'prepaid' | 'usage_based'
required
‘prepaid’ for upfront payment (seats), ‘usage_based’ for pay-as-you-go.
number | null
Max units purchasable beyond included. E.g. included=100, max_purchase=300 allows 400 total. Null for no limit.
object
Proration settings for prepaid features. Controls mid-cycle quantity change billing.
Show properties
Show properties
object
Rollover config for unused units. If set, unused included units carry over.
object
Overrides fields of this item’s feature for customers on this plan (e.g. a credit system’s credit_schema).
Show properties
Show properties
object | object[]
For credit system features: replaces the feature’s credit_schema entirely for customers on this plan.
Show properties
Show properties
string
ID of the metered feature that draws from this credit system.
number
Number of metered-feature units priced together. Defaults to one when omitted.