{
"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 scalar fields whose values changed, holding their previous values. Null when the plan is newly activated or scheduled.
object[]
required
Features that were added to or removed from this plan. Only populated for updated plans.
Show properties
Show properties
'created' | 'deleted'
required
Whether the feature was added to or removed from the plan.
string
required
The ID of the feature that was added or removed.
object
required
The 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.
Was this page helpful?
⌘I