Product

⚠️ Beta Testing: Our Product API is currently in beta testing. More extensive support and features are on the way. Some functionality may be limited or subject to change. We recommend testing thoroughly before production use.

Learn how to manage and access your virtual items and bundles through the Product API.

Product API is a content management system that allows merchants to manage their virtual items and create bundles. The API provides secure access to your product catalog with pagination and filtering. Each product is priced in a single currency, while checkout supports multiple payment currencies.

You can retrieve product information to display in your storefront, manage inventory, and set pricing in your preferred currency.

Amount format: All monetary values (such as price fields) are expressed in the smallest minor unit of each currency. See Supported currencies for the exact encoding per currency.

Overview

The Product system consists of two main components:

Virtual Items: Individual digital products with names, descriptions, images, and pricing
Bundles: Collections of virtual items sold together at a bundled price

Products support single-currency pricing and rich media attachments. The API includes pagination and filtering capabilities. While each product has one base currency, customers can pay in their local currency during checkout.

Product lifecycle

Product Creation: Virtual items and bundles are created and configured in the Tokenz Dashboard
API Access: Your application retrieves product data using the Product API with filtering and pagination
Display: Products are displayed in your storefront with appropriate pricing
Integration: Product data integrates with checkout sessions for purchase flows

Diagram

API call examples

List virtual items

Retrieve a paginated list of virtual items with optional filtering and sorting.

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/product/virtual-items' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

The following query parameters are supported:

Query parameters

Pagination

limit: Number of items to return (max 100, default 20)
offset: Number of items to skip for pagination

Filtering

sku: Filter by SKU (exact match)

Sorting

Virtual items and bundles support sorting by:

name_asc / name_desc: Sort by name
sku_asc / sku_desc: Sort by SKU
created_asc / created_desc: Sort by date (default: created_desc)

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/product/virtual-items?limit=10&offset=0&sku=gold-ring-350&sort=name_asc' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

Response:

json

{
  "data": [
    {
      "id": "virtualitem_YJoSoHrd9R1",
      "sku": "gold-ring-350",
      "label": {
        "en_US": "Gold Ring"
      },
      "description": {
        "en_US": ""
      },
      "images": [
        {
          "id": "3ZUJBfy7M99jRh0YglPUQv",
          "fileName": "gold-ring.png",
          "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png",
          "width": 240,
          "height": 240
        }
      ],
      "defaultFiatCurrency": "JPY",
      "unitPrices": [
        {
          "amount": 350,
          "currency": "JPY"
        }
      ],
      "taxCategory": "DIGITAL_GOODS_AND_SERVICES",
      "createdAt": "2025-07-28T04:28:21.112Z",
      "updatedAt": "2025-07-28T04:28:21.112Z",
      "publishedAt": "2025-07-28T04:28:21.112Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "hasNext": false,
    "hasPrevious": false
  }
}

Get virtual item by ID

Retrieve detailed information about a specific virtual item with its ID.

bash

curl --request GET \
  --url https://api.tokenz.one/v1/product/virtual-items/{VirtualItemID} \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

Response:

json

{
  "data": {
    "id": "virtualitem_YJoSoHrd9R1",
    "sku": "gold-ring-350",
    "label": {
      "en_US": "Gold Ring"
    },
    "description": {
      "en_US": ""
    },
    "images": [
      {
        "id": "3ZUJBfy7M99jRh0YglPUQv",
        "fileName": "gold-ring.png",
        "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png",
        "width": 240,
        "height": 240
      }
    ],
    "defaultFiatCurrency": "JPY",
    "unitPrices": [
      {
        "amount": 350,
        "currency": "JPY"
      }
    ],
    "taxCategory": "DIGITAL_GOODS_AND_SERVICES",
    "createdAt": "2025-07-28T04:28:21.112Z",
    "updatedAt": "2025-07-28T04:28:21.112Z",
    "publishedAt": "2025-07-28T04:28:21.112Z"
  }
}

List bundles

Retrieve bundles with optional inclusion of bundle items.

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/product/bundles' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

The following query parameters are supported:

Pagination

limit: Number of items to return (max 100, default 20)
offset: Number of items to skip for pagination

Include items

include_items: Include bundle items in response (default: false)

Filtering

sku: Filter by SKU (exact match)

Sorting

Bundles support sorting by:

name_asc / name_desc: Sort by name
sku_asc / sku_desc: Sort by SKU
created_asc / created_desc: Sort by date (default: created_desc)

bash

curl --request GET \
  --url 'https://api.tokenz.one/v1/product/bundles?include_items=true&limit=10&offset=0&sku=treasure-box&sort=name_asc' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

Response:

json

{
  "data": [
    {
      "id": "bundle_GavBmyQmH43",
      "sku": "treasure-box",
      "label": {
        "en_US": "Treasure Box"
      },
      "description": {
        "en_US": ""
      },
      "images": [
        {
          "id": "3CeCTmaDg0SbVBh1oegKam",
          "fileName": "treasure-box-1.png",
          "url": "https://images.ctfassets.net/z82qbo7cv7ia/3CeCTmaDg0SbVBh1oegKam/9c9cfe621960b96971d1a88089514e2f/treasure-box-1.png",
          "width": 360,
          "height": 360
        }
      ],
      "defaultFiatCurrency": "JPY",
      "unitPrices": [
        {
          "amount": 1500,
          "currency": "JPY"
        }
      ],
      "bundleItems": [],
      "createdAt": "2025-07-28T12:43:28.991Z",
      "updatedAt": "2025-09-12T07:25:13.994Z",
      "publishedAt": "2025-09-12T07:25:13.994Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "hasNext": false,
    "hasPrevious": false
  }
}

Get bundle by ID

Retrieve detailed information about a specific bundle with its ID.

bash

curl --request GET \
  --url https://api.tokenz.one/v1/product/bundles/{BundleID} \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

Response:

json

{
  "data": {
    "id": "bundle_GavBmyQmH43",
    "sku": "treasure-box",
    "label": {
      "en_US": "Treasure Box"
    },
    "description": {
      "en_US": ""
    },
    "images": [
      {
        "id": "3CeCTmaDg0SbVBh1oegKam",
        "fileName": "treasure-box-1.png",
        "url": "https://images.ctfassets.net/z82qbo7cv7ia/3CeCTmaDg0SbVBh1oegKam/9c9cfe621960b96971d1a88089514e2f/treasure-box-1.png",
        "width": 360,
        "height": 360
      }
    ],
    "defaultFiatCurrency": "JPY",
    "unitPrices": [
      {
        "amount": 1500,
        "currency": "JPY"
      }
    ],
    "bundleItems": [
      {
        "quantity": 5,
        "item": {
          "id": "virtualitem_YJoSoHrd9R1",
          "sku": "gold-ring-350",
          "label": {
            "en_US": "Gold Ring"
          },
          "description": {
            "en_US": ""
          },
          "images": [
            {
              "id": "3ZUJBfy7M99jRh0YglPUQv",
              "fileName": "gold-ring.png",
              "url": "https://images.ctfassets.net/z82qbo7cv7ia/3ZUJBfy7M99jRh0YglPUQv/a7d42e8c35d2af8ec7efee4e2a1f79b7/gold-ring.png",
              "width": 240,
              "height": 240
            }
          ],
          "defaultFiatCurrency": "JPY",
          "unitPrices": [
            {
              "amount": 350,
              "currency": "JPY"
            }
          ],
          "taxCategory": "DIGITAL_GOODS_AND_SERVICES",
          "createdAt": "2025-07-28T04:28:21.112Z",
          "updatedAt": "2025-07-28T04:28:21.112Z",
          "publishedAt": "2025-07-28T04:28:21.112Z"
        }
      },
      {
        "quantity": 10,
        "item": {
          "id": "virtualitem_83f3aWcvJ4w",
          "sku": "diamond-currency",
          "label": {
            "en_US": "Diamond"
          },
          "description": {
            "en_US": ""
          },
          "images": [
            {
              "id": "3jOZHd2Ht3uOL1bBxLGmeM",
              "fileName": "pngtree-blue-diamond-for-game-png-image_2914528.jpg",
              "url": "https://images.ctfassets.net/z82qbo7cv7ia/3jOZHd2Ht3uOL1bBxLGmeM/397c603cb7b968bfa9ebba2fcd21216e/pngtree-blue-diamond-for-game-png-image_2914528.jpg",
              "width": 360,
              "height": 360
            }
          ],
          "defaultFiatCurrency": "JPY",
          "unitPrices": [
            {
              "amount": 100,
              "currency": "JPY"
            }
          ],
          "taxCategory": "VIRTUAL_CURRENCY",
          "createdAt": "2025-09-12T02:35:53.272Z",
          "updatedAt": "2025-09-12T02:35:53.272Z",
          "publishedAt": "2025-09-12T02:35:53.272Z"
        }
      }
    ],
    "createdAt": "2025-07-28T12:43:28.991Z",
    "updatedAt": "2025-09-12T07:25:13.994Z",
    "publishedAt": "2025-09-12T07:25:13.994Z"
  }
}

Bundle management

Bundles allow you to group multiple virtual items together at a discounted price. When retrieving bundles:

Use include_items=true to get detailed information about bundled items
Bundle pricing is independent of individual item pricing
Each bundle item includes quantity information

Error handling

The API returns standard HTTP status codes and detailed error messages:

401 Unauthorized: Invalid or missing API key
404 Not Found: Product or bundle not found
429 Too Many Requests: Rate limit exceeded
500 Server Error: Internal server error

All error responses include a structured error object with code and message for programmatic handling.

Beta status

The Product API is currently in beta testing with the following status:

Currently available:

Virtual items and bundles management
Single-currency pricing per product
Basic pagination and filtering
Rich media attachments
Checkout integration

Coming soon:

Multi-language localization support
Enhanced filtering and search capabilities
Advanced inventory management features
Extended API endpoints

Known limitations:

Localization is not yet supported for product names and descriptions
Some advanced filtering options may be limited

We're actively developing these features and welcome your feedback during the beta period.