---
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/v2/subscriptions/lifecycle"
api_version: "v2"
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 on the consumer's behalf. Terminal — no further charges. |
| `expired` | Ended involuntarily because a payment could never 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 on the consumer's behalf, 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/v2/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 and 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.

## Cancellation

A subscription can be canceled by the merchant on the consumer's behalf, 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.