--- title: "Product" description: "Learn how to manage and access your virtual items and bundles through the Product API." source: "https://docs.tokenz.one/en/v2/product" api_version: "v2" locale: "en" version_status: "current" docs_stage: "prod" --- # Product > **Early access**: The Product API is available in early access. Additional features and broader support are in development. Some functionality is limited or may change. Test your integration thoroughly before using it in production. 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](https://docs.tokenz.one/en/v2/checkout/currency) 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 1. **Product Creation**: Virtual items and bundles are created and configured in the Tokenz Dashboard 2. **API Access**: Your application retrieves product data using the Product API with filtering and pagination 3. **Display**: Products are displayed in your storefront with appropriate pricing 4. **Integration**: Product data integrates with checkout sessions for purchase flows ```mermaid sequenceDiagram; autonumber; participant M as Merchant App; participant T as Product API; participant DB as Product Database; %% 1 ── Request product catalog; M->>T: GET /v2/product/virtual-items; T->>DB: Query virtual items; DB-->>T: Return product data; T-->>M: Paginated product list; %% 2 ── Request specific product details; M->>T: GET /v2/product/virtual-items/{id}; T->>DB: Query specific item; DB-->>T: Return detailed product; T-->>M: Complete product details; %% 3 ── Integration with checkout; M->>M: Customer selects products; M->>T: Create Checkout Session with products; T-->>M: Checkout Session created; ``` ## 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/v2/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) - `category`: Filter by category #### 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/v2/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/v2/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/v2/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/v2/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/v2/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. ## Early access status The Product API is in early access. Its current capabilities and limitations are listed below: **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 early access.