Skip to content

Browse docs

GuidesAPI Reference
Build with AI
Products & subscriptionsCreate a checkout session

Creating checkout sessions with product items

Learn how to create checkout sessions using virtual items and bundles from your Tokenz Product catalog.

Overview

The Product system allows you to manage your virtual items and bundles through the Tokenz Dashboard. These product items can be directly referenced when creating checkout sessions, enabling a fully programmatic flow from product management to checkout completion.

Prerequisites

Before creating checkout sessions with product items, ensure you have:

  1. API Credentials: Obtain your secret key from the Tokenz Dashboard
  2. Product Setup: Create virtual items and/or bundles in the Tokenz Dashboard
  3. Product IDs: Note the IDs of the items you want to use (format: virtualitem_xxx or bundle_xxx) - these can be obtained from the products API, allowing for fully programmatic checkout flow creation

Creating a Checkout Session with product items

Using virtual items

When creating a Checkout Session, you can reference virtual items directly by their product IDs. The pricing and product information will be automatically pulled from your product configuration.

bash
curl --request POST \
  --url https://api.tokenz.one/v1/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemDetails": [
      {
        "virtualItem":{
          "id": "virtualitem_5xA9BnKfvH7",
          "quantity": 2
        }
      },
      {
        "virtualItem":{
          "id": "virtualitem_3yB8CmLgwI8",
          "quantity": 1
        }
      }
    ],
    "customerInfo": {},
    "successUrl": "https://yourdomain.com/success",
    "pendingUrl": "https://yourdomain.com/pending",
    "cancelUrl": "https://yourdomain.com/cancel",
    "locale": "en_US"
  }'

Using bundles

bash
curl --request POST \
  --url https://api.tokenz.one/v1/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemDetails": [
      {
        "bundle": {
          "id": "bundle_8mR5TnKfvH7",
          "quantity": 1
        }
      }
    ],
    "customerInfo": {},
    "successUrl": "https://yourdomain.com/success",
    "pendingUrl": "https://yourdomain.com/pending",
    "cancelUrl": "https://yourdomain.com/cancel",
    "locale": "en_US"
  }'

Mixing items and bundles

You can combine both virtual items and bundles in a single Checkout Session:

bash
curl --request POST \
  --url https://api.tokenz.one/v1/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemDetails": [
      {
        "bundle": {
          "id": "bundle_8mR5TnKfvH7",
          "quantity": 1
        }
      },
      {
        "virtualItem": {
          "id": "virtualitem_5xA9BnKfvH7",
          "quantity": 3
        }
      }
    ],
    "customerInfo": {},
    "successUrl": "https://yourdomain.com/success",
    "pendingUrl": "https://yourdomain.com/pending",
    "cancelUrl": "https://yourdomain.com/cancel"
  }'

Implementation examples

javascript
import fetch from 'node-fetch';

async function createCheckoutSession() {
  const response = await fetch('https://api.tokenz.one/v1/checkoutsession', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.TOKENZ_SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      itemDetails: [
        {
          virtualItem: {
            id: "virtualitem_5xA9BnKfvH7",
            quantity: 2
          }
        }
      ],
      successUrl: "https://yourdomain.com/success",
      pendingUrl: "https://yourdomain.com/pending",
      cancelUrl: "https://yourdomain.com/cancel",
      locale: "en_US"
    })
  });

  const session = await response.json();

  // Redirect user to checkout
  return session.url;
}

Response

The API returns a Checkout Session object:

json
{
  "id": "checkoutsession_12345678QsZ",
  "object": "checkoutsession",
  "url": "https://checkout.tokenz.one/12345678QsZ",
  "cancelUrl": "https://yourdomain.com/cancel",
  "pendingUrl": "https://yourdomain.com/pending",
  "successUrl": "https://yourdomain.com/success",
  "order": {
    "id": "order_1xdzo1aZRGB",
    "object": "order",
    "status": "requiresPayment",
    "amount": {
      "amount": 900,
      "currency": "JPY"
    },
    "items": [
      {
        "id": "item_1xdzo1ZpRcT",
        "detail": {
          "product": {
            "price": {
              "amount": 450,
              "currency": "JPY"
            },
            "quantity": 2,
            "label": "Mana Potion",
            "description": "",
            "images": [
              "https://images.ctfassets.net/z82qbo7cv7ia/2JyshO1smpYQwi0my9Rtif/f7df805472f4a1a0bf4e295afe9378a7/mana-potion.png"
            ],
            "sku": "mana-potion-450",
            "taxCategory": "DIGITAL_GOODS_AND_SERVICES"
          }
        }
      }
    ],
    "test": true,
    "createdAt": "2025-09-22T04:32:04.696Z",
    "updatedAt": "2025-09-22T04:32:04.696Z"
  },
  "createdAt": "2025-09-22T04:32:04.374Z",
  "updatedAt": "2025-09-22T04:32:04.374Z",
  "test": true,
  "customerInfo": {},
  "locale": "en_US",
  "preferApplePay": false,
  "preferGooglePay": false
}

Best practices

  1. Validate Item IDs: Always verify that the product item IDs exist before creating sessions
  2. Handle Errors: Implement proper error handling for invalid or discontinued items
  3. Use Webhooks: Set up webhooks to receive real-time updates on payment status
  4. Test Thoroughly: Use test mode to verify your integration before going live

Next steps