---
title: "Integrate subscriptions"
description: "This guide walks through creating a subscription, activating it, and letting renewals run automatically — for both the no-trial and trial-period flows."
source: "https://docs.tokenz.one/en/v2/subscriptions/get-started"
api_version: "v2"
locale: "en"
version_status: "current"
docs_stage: "prod"
---

# Integrate subscriptions

This guide walks through creating a subscription, activating it, and letting renewals run automatically — for both the no-trial and trial-period flows.

## Prerequisites

You'll need your API secret key from the Tokenz Dashboard. See [Checkout](https://docs.tokenz.one/en/v2/checkout) if you haven't integrated one-time payments yet — subscriptions are built on the same Checkout Session flow.

## 1. Create a subscription checkout session

Create a Checkout Session with a `subscription` block specifying details of the recurring contract. Only a single, non-discounted item is allowed on a subscription checkout.

```bash
curl --request POST \
  --url https://api.tokenz.one/v2/checkoutsession \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "itemDetails": [{
      "product": {
        "price": { "amount": 1000, "currency": "USD" },
        "quantity": 1,
        "label": "Pro Plan (Monthly)",
        "images": ["https://example.com/pro-plan.png"],
        "taxCategory": "SAAS"
      }
    }],
    "subscription": {
      "interval": { "unit": "MONTH", "count": 1 },
      "trialPeriodDays": 7,
      "dunningMode": "RETRY"
    },
    "successUrl": "https://example.com/success",
    "pendingUrl": "https://example.com/pending",
    "cancelUrl": "https://example.com/cancel",
    "customerInfo": {
      "emailAddress": "consumer@example.com"
    }
  }'
```

### Subscription parameters

- `interval` (required): The billing interval, an object with `unit` (`WEEK`, `MONTH`, or `YEAR`) and `count` (integer ≥ 1, the number of units between renewals). For example, `{ "unit": "MONTH", "count": 1 }` renews monthly.
- `trialPeriodDays` (optional, 1–365): Number of days before the first charge. Omit for no trial.
- `dunningMode` (optional): `RETRY` (default) or `CANCEL_IMMEDIATELY`. See [Lifecycle & billing](https://docs.tokenz.one/en/v2/subscriptions/lifecycle#dunning-(failed-payment-recovery)).
- `dunningMaxAttempts` (optional, default 3), `dunningExpireAfterHours` (optional, default 24): Only used when `dunningMode` is `RETRY`.

### Response

```json
{
  "id": "checkoutsession_1p4LPTRKB5Z",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/1p4LPTRKB5Z",
  "test": false,
  "subscription": {
    "id": "subscription_1p4LS47fB1h",
    "object": "subscription",
    "status": "created",
    "test": false,
    "items": [
      {
        "id": "item_1p4LS47fB1i",
        "detail": {
          "product": {
            "price": { "amount": 1000, "currency": "USD" },
            "quantity": 1,
            "label": "Pro Plan (Monthly)",
            "images": ["https://example.com/pro-plan.png"]
          }
        }
      }
    ],
    "interval": { "unit": "MONTH", "count": 1 },
    "createdAt": "2026-07-01T00:00:00Z",
    "updatedAt": "2026-07-01T00:00:00Z"
  }
}
```

> **Note:** When `trialPeriodDays` is omitted, the response also includes an `order` object for the initial charge.

## 2. Redirect the consumer to complete setup

Redirect the consumer to the returned `url`. From there, the Tokenz-hosted checkout page takes care of the rest of the consumer-facing flow:

- Resolving the consumer's region, currency, and applicable tax
- Collecting the card and completing any 3D Secure challenge required by the issuer
- Capturing the recurring-charge consent needed for future renewals (see [Payment methods & consent](https://docs.tokenz.one/en/v2/subscriptions/payment-methods))
- **No trial period**: charging the first order immediately, activating the subscription
- **Trial period configured**: starting the trial without charging anything yet

Once the consumer completes this step, Tokenz redirects them back to your `successUrl`, `pendingUrl`, or `cancelUrl` depending on the outcome — the same redirect contract as a one-time Checkout Session.

## 3. Renewals and activation happen automatically

You don't need to call anything further:

- If there was no trial, the subscription is `active` as soon as the initial charge succeeds.
- If a trial was configured, Tokenz automatically creates and charges the first order when the trial ends, activating the subscription on success.
- From then on, Tokenz automatically creates and charges a new order at the end of every billing period, for as long as the subscription stays `active`.

Listen for webhooks to keep your own records in sync — `subscription.trial_started`, `subscription.activated`, and `subscription.renewed` on success, or `subscription.unpaid` if a charge fails. See [Webhooks](https://docs.tokenz.one/en/v2/subscriptions/webhooks).

```mermaid
sequenceDiagram;
autonumber;
participant C as Consumer;
participant M as Merchant Server;
participant T as Tokenz API;
participant TC as Tokenz-hosted Checkout;
participant W as Merchant Webhook Handler;
M->>T: POST /v2/checkoutsession (with subscription block);
T-->>M: checkoutSession + subscription (created);
M-->>TC: Redirect consumer to checkout session url;
TC->>TC: Collect card, resolve region/tax, capture consent;
alt No trial period
TC->>TC: Charge initial order, subscription becomes active;
else Trial period configured
TC->>TC: Subscription becomes trialing (no charge yet);
Note over T: At trialEnd, Tokenz creates and charges the first order automatically;
T->>T: Subscription becomes active;
end
TC-->>C: Redirect back to successUrl / pendingUrl / cancelUrl;
T->>W: webhook: subscription.trial_started / subscription.activated;
loop Every billing period;
T->>T: Create renewal order, charge saved card automatically;
T->>W: webhook: subscription.renewed (or subscription.unpaid on failure);
end
```

## Viewing subscriptions

Use the Tokenz Dashboard to view and manage subscriptions across your account. For your own systems, rely on the webhook events above to keep an up-to-date view of each subscription's status without polling.

## Testing

- Use test API keys (prefixed `test_`) to create test subscriptions; test entity IDs carry a `_t` suffix (e.g. `subscription_1p4LS47fB1h_t`).
- Test mode lets you simulate authorization outcomes (approved, declined) on the hosted checkout page, so you can exercise both the happy path and dunning/recovery without a real card network.
- The Tokenz Dashboard also lets you trigger a renewal charge on demand for a test subscription, instead of waiting for the regular billing schedule.