{
"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
The ID of the customer whose plans changed.
The ID of the entity, if the changes are scoped to a specific entity.
The plans that were activated, scheduled, updated, or expired.
Show properties
Show properties
The lifecycle action applied to this plan: activated (newly active on the customer), scheduled (queued for a future start), updated (mutated in place), or expired (ended).
The subscription as it stands after this change. Present when the plan is billed as a recurring subscription.
Show properties
Show properties
The ID of the customer plan.
The current status of the subscription on the customer.
Whether the subscription has overdue payments.
When the subscription started, in milliseconds since the Unix epoch.
When the subscription was canceled, in milliseconds since the Unix epoch, or null if not canceled.
When the subscription ends, in milliseconds since the Unix epoch, or null if no expiry is set.
When the trial ends, in milliseconds since the Unix epoch. Null when not actively trialing.
Start of the current billing period, or null if not applicable.
End of the current billing period, or null if not applicable.
The purchase as it stands after this change. Present when the plan is a one-off purchase.
Sparse map of scalar fields whose values changed, holding their previous values. Null when the plan is newly activated or scheduled.
Features that were added to or removed from this plan. Only populated for updated plans.
Show properties
Show properties
Whether the feature was added to or removed from the plan.
The ID of the feature that was added or removed.
The item snapshot that was added or removed.
Show properties
Show properties
The ID of the feature this item configures.
The full feature object if expanded.
Show properties
Show properties
The ID of the feature, used to refer to it in other API calls like /track or /check.
The name of the feature.
type
'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system' | 'ai_credit_system'
required
The type of the feature
Whether or not the feature is archived.
Number of free units included. For consumable features, balance resets to this number each interval.
Whether the customer has unlimited access to this feature.
Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.
Show properties
Show properties
interval
'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 of intervals between resets. Defaults to 1.
Pricing configuration for usage beyond included units. Null if feature is entirely free.
Show properties
Show properties
Price per billing_units after included usage is consumed. Mutually exclusive with tiers.
Billing interval for this price. For consumable features, should match reset.interval.
Number of intervals per billing cycle. Defaults to 1.
Number of units per price increment. Usage is rounded UP to the nearest billing_units when billed (e.g. billing_units=100 means 101 usage rounds to 200).
‘prepaid’ for features like seats where customers pay upfront, ‘usage_based’ for pay-as-you-go after included usage.
Maximum units a customer can purchase beyond included. E.g. if included=100 and max_purchase=300, customer can use up to 400 total before usage is capped. Null for no limit.
Rollover configuration for unused units. If set, unused included units roll over to the next period.
Show properties
Show properties
Maximum rollover units. Null for unlimited rollover.
Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.
When rolled over units expire.
Number of periods before expiry.
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