---
title: "Subscriptions"
description: "Learn how to sell recurring products with the Tokenz Subscriptions API — from creating a subscription at checkout through billing, dunning, plan changes,..."
source: "https://docs.tokenz.one/en/v2/subscriptions"
api_version: "v2"
locale: "en"
version_status: "current"
docs_stage: "prod"
---

# Subscriptions

Learn how to sell recurring products with the Tokenz Subscriptions API — from creating a subscription at checkout through billing, dunning, plan changes, and cancellation.

A Subscription automatically creates a new order and charges the consumer's saved payment method on a fixed interval (weekly, monthly, or yearly), for as long as the subscription stays active. Tokenz manages the full billing lifecycle for you: scheduling renewal charges, retrying failed payments, sending renewal reminders, and notifying your backend through webhooks at every step.

**Amount format:** Monetary values (such as `amount` fields) are expressed in the smallest minor unit of each currency. See [Supported currencies](https://docs.tokenz.one/en/v2/checkout/currency) for the exact encoding per currency.

> **Note:** Subscriptions are currently available for merchants using the Merchant of Record (MOR) model only.

## Overview

The Subscriptions API is built on top of the same [Checkout Session](https://docs.tokenz.one/en/v2/checkout) primitive used for one-time orders:

- **Create**: Start a subscription by creating a Checkout Session with a `subscription` block. Exactly one non-discounted item is allowed per subscription.
- **Authorize**: The consumer completes a card payment (with or without a trial period). This also captures a merchant-initiated transaction (MIT) consent so future renewals can be charged without further consumer interaction.
- **Bill automatically**: Tokenz creates a new order and charges the saved card at the end of every billing period, for as long as the subscription is `active`.
- **Manage**: Consumers can update their payment method through the Tokenz-hosted flow, and merchants can change plans or cancel a subscription for a consumer.
- **React**: Your backend receives webhooks for every lifecycle transition (trial started, activated, renewed, unpaid, payment method updated, plan changed, canceled, expired).

## Core concepts

- **Subscription**: The recurring billing record. Holds the price, billing interval, trial configuration, dunning strategy, current billing period, and the consumer's payment method.
- **Billing interval**: How often the subscription renews, expressed as a `unit` (`WEEK`, `MONTH`, or `YEAR`) and a `count` (the number of units between renewals). Monthly and yearly renewals happen on the same day-of-month as the first charge (falling back to the last day of the month if the month is shorter).
- **Trial period**: An optional number of days (1–365) before the first charge. If configured, the subscription is created without an initial order, and the first order is created automatically when the trial ends.
- **Payment method consent**: Subscriptions only support card payment methods. The consumer's initial authorization (or a dedicated consent flow) grants Tokenz permission to charge the card again for renewals without a 3D Secure challenge each time.
- **Dunning**: The retry strategy used when a renewal charge fails, before the subscription is expired.
- **Plan change**: A request to swap the subscription's item and/or billing interval, applied either immediately (with proration) or deferred to the next billing period.

## What's in this guide

- [Lifecycle & billing](https://docs.tokenz.one/en/v2/subscriptions/lifecycle) — statuses, billing periods, trials, dunning, cancellation, and renewal reminders in depth
- [Integrate subscriptions](https://docs.tokenz.one/en/v2/subscriptions/get-started) — create a subscription checkout, activate it, and trigger renewals
- [Payment methods & consent](https://docs.tokenz.one/en/v2/subscriptions/payment-methods) — how MIT consent works and how consumers update their card
- [Webhooks](https://docs.tokenz.one/en/v2/subscriptions/webhooks) — the full event catalog with sample payloads