{
"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
'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.
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.
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[]
required
Feature configurations included in this plan. Each item defines included units, pricing, and reset behavior for a feature.
Show properties
Show properties
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
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.
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.
'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[]
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
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
Reset configuration for consumable features. Omit for non-consumable features like seats.
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[]
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.
object | null
Free trial configuration for a plan.
Show properties
Show properties
number
required
Number of duration_type periods the trial lasts.
'day' | 'month' | 'year'
required
Unit of time for the trial (‘day’, ‘month’, ‘year’).
boolean
required
If true, payment method required to start trial. Customer is 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
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[]
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
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[]
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.
string
Optional user-defined label to distinguish multiple alerts on the same feature.
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.
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.
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
Unique identifier for the plan.
string
Display name of the plan.
string | null
Optional description of the plan.
string | null
Group identifier for organizing related plans. Plans in the same group are mutually exclusive.
boolean
Whether this is an add-on plan that can be attached alongside a main plan.
boolean
If true, this plan is automatically attached when a customer is created. Used for free plans.
object
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 | 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
Previous billing controls when they changed. Null when unset.
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.
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
required
The plan’s price before the change.
Show properties
Show properties
number
required
Base price amount for the plan.
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 | null
required
The plan’s price after the change.
Show properties
Show properties
number
required
Base price amount for the plan.
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
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
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[]
required
Deprecated — use plan_change.item_changes. Features that were added to or removed from this 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
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.
string[]
required
Reason tags describing why this event fired (e.g. ‘trial_ended’, ‘phase_changed’). Always present; empty when no specific reason applies.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
The webhook event type.
Allowed value:
"billing.updated"Show child attributes
Show child attributes
Example:
{
"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": []
}
Response
200
Webhook received successfully.
⌘I