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

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.
• dunningMaxAttempts (optional, default 3), dunningExpireAfterHours (optional, default 24): Only used when dunningMode is RETRY.

Response

{
  "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)
• 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.

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.