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

Scroll horizontally if needed

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

Diagram

Trial periods

If you set trialPeriodDays (1–365) when creating the subscription, no initial order is created at checkout. Instead:

The consumer starts the trial by providing card details. Tokenz registers payment consent in payment network. — see Payment methods & consent.
The subscription moves to trialing, a subscription.trial_started webhook is sent.
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.

Scroll horizontally if needed

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.