Plans Updated - Autumn

{
  "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": []
  }
}

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

object

string

required

customer_id

string

required

The ID of the customer whose plans changed.

entity_id

string | null

The ID of the entity, if the changes are scoped to a specific entity.

plan_changes

object[]

required

The plans that were activated, scheduled, updated, or expired.

Show properties

action

'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).

subscription

object

The subscription as it stands after this change. Present when the plan is billed as a recurring subscription.

Show properties

plan_id

string

required

The ID of the customer plan.

status

'active' | 'scheduled' | 'expired'

required

The current status of the subscription on the customer.

past_due

boolean

required

Whether the subscription has overdue payments.

started_at

number | null

required

When the subscription started, in milliseconds since the Unix epoch.

canceled_at

number | null

required

When the subscription was canceled, in milliseconds since the Unix epoch, or null if not canceled.

expires_at

number | null

required

When the subscription ends, in milliseconds since the Unix epoch, or null if no expiry is set.

trial_ends_at

number | null

required

When the trial ends, in milliseconds since the Unix epoch. Null when not actively trialing.

current_period_start

number | null

required

Start of the current billing period, or null if not applicable.

current_period_end

number | null

required

End of the current billing period, or null if not applicable.

purchase

object

The purchase as it stands after this change. Present when the plan is a one-off purchase.

Show properties

plan_id

string

required

The ID of the customer plan.

status

'active' | 'scheduled' | 'expired'

required

The current status of the purchase on the customer.

expires_at

number | null

required

When the purchase ends, in milliseconds since the Unix epoch, or null if no expiry is set.

previous_attributes

object | null

required

Sparse map of scalar fields whose values changed, holding their previous values. Null when the plan is newly activated or scheduled.

item_changes

object[]

required

Features that were added to or removed from this plan. Only populated for updated plans.

Show properties

action

'created' | 'deleted'

required

Whether the feature was added to or removed from the plan.

feature_id

string

required

The ID of the feature that was added or removed.

item

object

required

The item snapshot that was added or removed.

Show properties

feature_id

string

required

The ID of the feature this item configures.

feature

object

The full feature object if expanded.

Show properties

string

required

The ID of the feature, used to refer to it in other API calls like /track or /check.

name

string | null

The name of the feature.

type

required

The type of the feature

display

object | null

Singular and plural display names for the feature.

Show properties

singular

string

required

The singular display name for the feature.

plural

string

required

The plural display name for the feature.

credit_schema

object[] | null

Credit cost schema for credit system features.

Show properties

metered_feature_id

string

required

The ID of the metered feature (should be a single_use feature).

credit_cost

number

required

The credit cost of the metered feature.

archived

boolean | null

Whether or not the feature is archived.

included

number

required

Number of free units included. For consumable features, balance resets to this number each interval.

unlimited

boolean

required

Whether the customer has unlimited access to this feature.

reset

object | null

required

Reset configuration for consumable features. Null for non-consumable features like seats where usage persists across billing cycles.

Show properties

interval

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.

interval_count

number

Number of intervals between resets. Defaults to 1.

price

object | null

required

Pricing configuration for usage beyond included units. Null if feature is entirely free.

Show properties

amount

number

Price per billing_units after included usage is consumed. Mutually exclusive with tiers.

tiers

object[]

Tiered pricing configuration. Each tier’s ‘to’ INCLUDES the included amount. Either ‘tiers’ or ‘amount’ is required.

Show properties

number

required

amount

number

required

flat_amount

number

tier_behavior

'graduated' | 'volume'

interval

required

Billing interval for this price. For consumable features, should match reset.interval.

interval_count

number

Number of intervals per billing cycle. Defaults to 1.

billing_units

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).

billing_method

'prepaid' | 'usage_based'

required

‘prepaid’ for features like seats where customers pay upfront, ‘usage_based’ for pay-as-you-go after included usage.

max_purchase

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.

display

object

Display text for showing this item in pricing pages.

Show properties

primary_text

string

required

Main display text (e.g. ‘$10’ or ‘100 messages’).

secondary_text

string

Secondary display text (e.g. ‘per month’ or ‘then $0.5 per 100’).

rollover

object

Rollover configuration for unused units. If set, unused included units roll over to the next period.

Show properties

max

number | null

required

Maximum rollover units. Null for unlimited rollover.

max_percentage

number | null

Maximum rollover as a percentage (0-100) of included + prepaid grant. Mutually exclusive with max.

expiry_duration_type

'month' | 'forever'

required

When rolled over units expire.

expiry_duration_length

number

Number of periods before expiry.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

type

string

required

The webhook event type.

Allowed value: "billing.updated"

data

object

required

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.

Auto Top-Up Succeeded Resource Deleted

⌘I

​Payload Fields

Authorizations

Body

Response

Payload Fields