---
title: "Subscription webhooks"
description: "Subscriptions send webhook events for every lifecycle transition, so your backend can stay in sync without polling. This page lists the..."
source: "https://docs.tokenz.one/en/v2/subscriptions/webhooks"
api_version: "v2"
locale: "en"
version_status: "current"
docs_stage: "prod"
---

# Subscription webhooks

Subscriptions send webhook events for every lifecycle transition, so your backend can stay in sync without polling. This page lists the subscription-specific events and their payload shape.

For how to register webhook endpoints, verify signatures, and handle live/test mode, see [Webhooks](https://docs.tokenz.one/en/v2/checkout/webhooks) and [Get started with webhooks](https://docs.tokenz.one/en/v2/checkout/webhooks-get-started) — subscription events use the exact same Event envelope and delivery mechanism as order, refund, dispute, and redemption events.

**Amount format:** Monetary values in webhook payloads are expressed in the smallest minor unit of each currency. See [Supported currencies](https://docs.tokenz.one/en/v2/checkout/currency).

## Example event payload

The following example shows the event sent when a subscription successfully renews.

```json
{
  "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "object": "subscription.renewed",
  "createdAt": "2026-07-01T00:00:00Z",
  "test": false,
  "eventData": {
    "type": "subscription",
    "version": "v2",
    "data": {
      "subscription": {
        "id": "subscription_1p4LS47fB1h",
        "object": "subscription",
        "status": "active",
        "test": false,
        "items": [
          {
            "id": "item_1p4LS47fB1i",
            "detail": {
              "product": {
                "price": { "amount": 1000, "currency": "USD" },
                "quantity": 1,
                "label": "Pro Plan (Monthly)",
                "images": ["https://example.com/pro-plan.png"]
              }
            }
          }
        ],
        "interval": { "unit": "MONTH", "count": 1 },
        "currentBillingPeriodEnd": "2026-08-01T00:00:00Z",
        "createdAt": "2026-06-01T00:00:00Z",
        "updatedAt": "2026-07-01T00:00:00Z"
      }
    }
  }
}
```

The payload always contains the full, current state of the subscription at the time of the event (not a diff). Use the top-level `id` for delivery tracing and idempotency, and `eventData.data.subscription.id` to correlate the event with your own records.

## Types of events

| TYPE | DESCRIPTION |
| --- | --- |
| `subscription.trial_started` | The consumer provided a card and started the subscription's trial period. The subscription is now `trialing`. |
| `subscription.activated` | The subscription's first charge succeeded (either at checkout with no trial, or at trial end). The subscription is now `active`. |
| `subscription.renewed` | A recurring renewal charge succeeded and the subscription moved into its next billing period. |
| `subscription.unpaid` | A recurring (or initial) charge failed or requires payment. The subscription is now `unpaid` and dunning has started. |
| `subscription.payment_method_updated` | The subscription's payment method was successfully updated (consent was granted for the new card). |
| `subscription.plan_change_scheduled` | A deferred plan change was approved by the consumer and will be applied at the start of the next billing period. |
| `subscription.plan_change_canceled` | A previously scheduled deferred plan change was canceled before it was applied. |
| `subscription.plan_changed` | A plan change (immediate or deferred) was applied to the subscription. The `items` and/or `interval` in the payload reflect the new plan. |
| `subscription.canceled` | The subscription was canceled by the merchant on the consumer's behalf. No further charges will occur. |
| `subscription.expired` | The subscription ended because payment could not be collected (dunning exhausted, or the initial charge never succeeded). |

## Recommended handling

- **`subscription.activated`** and **`subscription.renewed`**: Grant or extend access to your product for the current billing period.
- **`subscription.unpaid`**: Optionally warn the consumer in your own product UI that a payment issue needs attention; Tokenz already handles retries and consumer emails automatically.
- **`subscription.payment_method_updated`**: Update your own records if you cache payment method metadata; no action needed to keep the subscription billing correctly.
- **`subscription.plan_changed`**: Update entitlements to match the new plan's item.
- **`subscription.canceled`** and **`subscription.expired`**: Revoke access at the end of the current billing period (or immediately, depending on your product's policy) and update your own subscription status to reflect the terminal state.