Import products

Add or update many products at once by uploading a file in the Tokenz Dashboard, instead of creating them one by one.

Open Products, then select Import products. Products are managed in live mode, so switch off test mode first.

Before you start

The Import products button appears only when your role has all of these permissions. Ask an admin to add any that are missing.

Choose a format

All formats use the same rules: products are matched by sku, and the import only adds or updates products. It never deletes a product that is missing from the file.

CSV format

File rules

• Encoding is UTF-8, with or without the byte order mark (BOM) that Excel adds. Japanese Excel's plain "CSV" (Shift_JIS) and Excel's "Unicode Text" (UTF-16) are also read. See Save a CSV from a spreadsheet.
• Values are separated by commas. Semicolon and tab separated files also work: the separator is detected from the header row.
• Prices use a dot for decimals, such as 7.50. A decimal comma (7,50), a currency symbol (¥480) or a thousands separator (1,000) is reported as not a number.
• Wrap a value in double quotes if it contains the file's separator (a comma, or a semicolon or tab in those files), a double quote or a line break. Write a double quote inside a value as "". For example, in a semicolon-separated file: gem-pack-500;500 Gems;"500 gems; added instantly.";480;JPY
• The first row must be a header row. Header names are case-insensitive. Empty columns and blank rows that a spreadsheet adds are ignored.
• Row numbers in messages count data rows: the first row under the header is row 1.
• A CSV or JSON file can be up to 25 MB. There is no limit on the number of rows.

Columns

Boolean columns (free, publish) accept true/false, yes/no or 1/0.

Example

Three game items priced in JPY. The second row shows quoting, and the third is a free item.

sku,name,description,price,currency,free,category,taxCategory,publish,image_url
gem-pack-500,500 Gems,"500 gems, added to your account instantly.",480,JPY,false,Gems,virtualCurrency,true,https://cdn.example.com/items/gem-pack-500.webp
starter-bundle,Starter Bundle,"1,200 gems and the ""Rookie"" badge.",1980,JPY,false,Bundles,virtualCurrency,false,https://cdn.example.com/items/starter-bundle.webp
daily-gift,Daily Free Gift,One free reward per day.,,,true,Free gifts,virtualCurrency,true,

Save a CSV from a spreadsheet

Start from the template: select Download template in the import dialog, fill it in, and save it as CSV.

Microsoft Excel

• Use File > Save As (or Save a Copy) and choose CSV UTF-8 (Comma delimited) (*.csv). This is the recommended format in every language.
• On a Japanese system, Excel's default CSV (Comma delimited) saves the file as Shift_JIS. That works too, and Japanese text imports correctly.
• In regions that use a decimal comma, such as much of Europe, Excel saves "CSV" with semicolons and writes prices like 7,50. The semicolons are detected, but a decimal comma is not read as a price. Before saving, make the decimal separator a dot (in Excel for Windows, File > Options > Advanced, clear Use system separators and set Decimal separator to .), or type the prices as text with a dot.
• Excel turns long numeric SKUs such as 123456789012 into 1.23457E+11 and drops leading zeros. Format the sku column as Text before you enter the SKUs. A SKU saved in scientific notation is refused, because its digits are already lost.

Google Sheets

Use File > Download > Comma-separated values (.csv). The file is UTF-8 and imports as it is.

Apple Numbers

Use File > Export To > CSV. Keep Text Encoding set to Unicode (UTF-8).

JSON format

A JSON import is a single manifest named products.json. Upload it on its own when every image is a URL, or inside a ZIP when it refers to image files.

Manifest

Product fields

Each product needs exactly one pricing field: price, free: true or regionPrices.

Example

{
  "version": 1,
  "defaults": {
    "currency": "JPY",
    "taxCategory": "virtualCurrency",
    "publish": false
  },
  "products": [
    {
      "sku": "starter-bundle",
      "name": "Starter Bundle",
      "description": "1,200 gems and the Rookie badge.",
      "price": 1980,
      "category": "Bundles",
      "images": ["images/starter-bundle.webp"]
    },
    {
      "sku": "daily-gift",
      "name": "Daily Free Gift",
      "description": "",
      "free": true,
      "images": ["https://cdn.example.com/items/daily-gift.webp"],
      "publish": true
    },
    {
      "sku": "gem-pack-1200",
      "name": "1,200 Gems",
      "description": "Priced for each region.",
      "regionPrices": { "JP": 980, "US": 6.99, "GB": 5.99 },
      "category": "Gems",
      "images": [
        "images/gem-pack-1200.webp",
        "https://cdn.example.com/items/gem-pack-1200-alt.webp"
      ]
    }
  ]
}

Package images in a ZIP

When any image is a relative path, such as images/starter-bundle.webp, upload a ZIP with products.json at its root. Relative paths are read from inside the ZIP.

products.zip
  products.json
  images/
    starter-bundle.webp
    gem-pack-1200.webp

Prices

Write every price in the currency's normal unit (480 for ¥480, 4.99 for $4.99), as a number greater than 0. This applies to price in CSV and JSON and to every amount in regionPrices.

• Decimals. A price can't have more decimal places than its currency uses. JPY and KRW have none, so 480.5 JPY is refused. Most currencies, such as USD and EUR, use 2. A few, such as BHD and KWD, use 3. See Supported currencies for each currency's decimals.
• Maximum. The largest price is 99,999,999.99, scaled to the currency's decimals:

The preview checks every price before anything is written, so a price that breaks these rules stops the import with a message naming the row.

Images

• Formats: WebP, PNG, JPEG or GIF.
• Each image can be up to 25 MB. Empty files are rejected.
• Image URLs must be publicly reachable. URLs that need a login, and private or local addresses such as localhost, are rejected.
• CSV takes one URL per product in image_url. Use JSON or a ZIP for several images or for image files.
• When you update a product, leaving out its images keeps the images it already has.

Re-import and updates

Products are matched by sku:

• New sku: the product is created.
• Existing sku: the product is updated with the values in the file. This is the default.
• sku not in the file: the product is left as it is. An import never deletes products.

To add new products without touching existing ones, select Create only (skip existing SKUs) before you import. Rows whose sku already exists are skipped and counted as skipped in the result.

A few things an import doesn't change on an existing product:

• Price of an existing plan. If the product already has a plan for the same billing interval (for example, its one-time price) at a different price, the row keeps the current price. The rest of the row is still updated, and the result notes "price not applied". To change the price, open the product in the Dashboard and change it there. Replacing a plan's price is a separate step that can't be undone, so an import never does it.
• Tax category. It is set when the product is created.

Import steps

1. Select Import products and upload your .csv, products.json or .zip file.
2. Review the preview. Each row shows whether it will be created, updated or skipped, and any errors.
3. Fix any errors and upload again. Nothing is written while the file has errors.
4. Select Import. Progress is shown as products are created and updated.
5. Review the result: how many products were created, updated, skipped and failed, with a reason for each failure.

Common errors

The import dialog shows each problem with the row it is on and the SKU, for example "Row 3 (SKU gem-pack-500): add a currency for the price, such as USD or JPY." In a JSON file, products are numbered by position ("Product 2 (SKU …)"). Nothing is written while any problem remains: fix the file and upload it again.

File problems

These stop the file from being read at all.

Row problems

After the import

The result lists each row that failed or was changed less than the file asked, with a note in English.

If text looks garbled after import, the file was saved in an encoding the import guessed wrong. Save it as CSV UTF-8 and import again.

Need help?

Contact Tokenz support with the file you tried to import and the error shown in the dashboard.