--- title: "Subscription lifecycle & billing" description: "This page explains how a subscription moves through its lifecycle, how billing periods and renewals are calculated, and how failed payments are handled." source: "https://docs.tokenz.one/en/v3/subscriptions/lifecycle" api_version: "v3" locale: "en" version_status: "current" docs_stage: "prod" --- # Subscription lifecycle & billing This page explains how a subscription moves through its lifecycle, how billing periods and renewals are calculated, and how failed payments are handled. ## Statuses | Status | Meaning | | --- | --- | | `created` | The subscription was created but hasn't been authorized by the consumer yet. | | `trialing` | The consumer is in the trial period. No money has moved yet. | | `active` | The subscription bills normally. A new order is created and charged automatically at the end of every billing period. | | `unpaid` | The current billing period's order could not be paid. The subscription is in dunning and will recover to `active` or terminate as `expired`. | | `canceled` | Canceled by the merchant or by consumer. Terminal — no further charges. | | `expired` | Ended involuntarily because a payment could not be collected (either the initial charge, or dunning was exhausted). Terminal — no further charges. | `canceled` and `expired` are both terminal, but they mean different things: `canceled` is a deliberate cancellation by the merchant or consumer, while `expired` reflects payment failure. Distinguish between them in your own churn reporting. ## Billing periods Every active subscription has a `currentBillingPeriodEnd` timestamp, trialing subscriptions also have `trialEnd` timestamp. - **Interval**: An object with `unit` (`WEEK`, `MONTH`, or `YEAR`) and `count` (the number of units between renewals). Monthly and yearly periods roll forward to the same day-of-month as the subscription's billing anchor (the first successful charge), falling back to the last day of the month when the anchor day doesn't exist in the target month (e.g. anchor on the 31st rolls to the 30th or 28th/29th in shorter months). - **Renewal**: Is managed by Tokenz at the end of current billing period ```mermaid sequenceDiagram; autonumber; participant T as Tokenz; participant PSP as Card network / PSP; participant W as Merchant webhook handler; T->>T: Create renewal order for the billing period; T->>PSP: Charge saved card; alt Payment succeeds PSP-->>T: Authorized; T->>T: Advance billing period, subscription stays active; T->>W: webhook: subscription.renewed; else Payment fails PSP-->>T: Declined; T->>T: Mark subscription unpaid, start dunning; T->>W: webhook: subscription.unpaid; end ``` ## Trial periods If you set `trialPeriodDays` (1–365) when creating the subscription, no initial order is created at checkout. Instead: 1. The consumer starts the trial by providing card details. Tokenz registers payment consent in payment network. — see [Payment methods & consent](https://docs.tokenz.one/en/v3/subscriptions/payment-methods). 2. The subscription moves to `trialing`, a `subscription.trial_started` webhook is sent. 3. When trial reaches `trialEnd` an order is created and charged using stored card. On success, the subscription becomes `active` and `subscription.activated` webhook is sent. If no trial period is configured, the initial order is created and charged at checkout time, and the subscription becomes `active` immediately on successful authorization. ## Dunning (failed payment recovery) Each subscription is created with a dunning strategy that controls what happens when a scheduled charge fails: - **`RETRY`** (default): The unpaid order is retried up to `dunningMaxAttempts` times (default 3), spaced out until the order's expiry window (`dunningExpireAfterHours`, default 24 hours) elapses. The consumer also receives a recovery checkout link by email so they can update their card if needed. If a retry succeeds, the subscription returns to `active`. If every retry fails or the order expires, the subscription becomes `expired`. - **`CANCEL_IMMEDIATELY`**: The first failed charge immediately expires the subscription — there is no retry window. | Field | Description | | --- | --- | | `dunningMode` | `RETRY` or `CANCEL_IMMEDIATELY`. Defaults to `RETRY`. | | `dunningMaxAttempts` | Maximum retry attempts when `dunningMode` is `RETRY`. 1–10, default 3. | | `dunningExpireAfterHours` | Hours until the unpaid order expires when `dunningMode` is `RETRY`. 1–168, default 24. | > **Note:** Recovering from `unpaid` back to `active` does not shift the original billing period — the next renewal is still scheduled from the original anchor date, not from the recovery date. ## Consumer access How you grant the consumer what they paid for depends on the kind of subscription. **Time-based** subscriptions (for example a premium plan) carry access on the Subscription object. Read `provideAccess` and `provideAccessUntil` from [subscription webhooks](https://docs.tokenz.one/en/v3/subscriptions/webhooks) and from the [Subscription API](https://docs.tokenz.one/en/v3/subscriptions/modification#retrieve-a-subscription). `provideAccess` is whether the consumer should be granted access. `provideAccessUntil` is the timestamp at which access ends; it is absent when access is open-ended or not granted. Follow these fields. A transition to `unpaid`, or the clock passing `currentBillingPeriodEnd` while the subscription is still `active` or `trialing`, is not itself a reason to revoke access. **Item-based** subscriptions (for example a monthly currency purchase) should be fulfilled from the orders Tokenz creates for the subscription. Handle the [order webhooks](https://docs.tokenz.one/en/v3/order#order-webhooks) for those orders — the same events used for one-time purchases, such as `order.succeeded`. Each of those orders includes `subscriptionId`. ## Cancellation A subscription can be canceled by the merchant (via the Tokenz Dashboard or [directly through the API](https://docs.tokenz.one/en/v3/subscriptions/modification#cancel-a-subscription)) or by the consumer (via a [hosted confirmation](https://docs.tokenz.one/en/v3/subscriptions/modification#request-consumer-cancellation)), while it is `trialing`, `active`, or `unpaid`. Canceling: - Sets `canceledAt` and disables generation of further renewal orders - Cancels any in-flight order for the subscription (e.g. an order still awaiting payment). - Sends a `subscription.canceled` webhook. Cancellation is final — there is currently no way to resume a canceled subscription. The consumer would need to start a new subscription. ## Renewal reminders In some regions, regulations require notice before certain charges (e.g. before a trial converts, or ahead of an annual renewal); where required, Tokenz sends these automatically.