Skip to content

Browse docs

GuidesAPI Reference
Build with AI
Products & subscriptionsSubscriptions

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 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 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