---
title: "商品のインポート"
description: "Tokenz Dashboard でファイルをアップロードすると、商品を 1 件ずつ作成する代わりに、まとめて追加または更新できます。"
source: "https://docs.tokenz.one/ja/v1/product/import"
api_version: "v1"
locale: "ja"
version_status: "legacy"
docs_stage: "prod"
---

# 商品のインポート

Tokenz Dashboard でファイルをアップロードすると、商品を 1 件ずつ作成する代わりに、まとめて追加または更新できます。

**製品**（Products）を開き、**商品をインポート** を選択します。商品はライブモードで管理されるため、先にテストモードをオフにしてください。

インポート画面とエラーメッセージは Dashboard の表示言語で表示されます。このガイドでは、日本語表示の画面の文言をそのまま記載しています。

## 事前準備

**商品をインポート** ボタンは、ご自身のロールに次の権限がすべて付与されている場合にのみ表示されます。不足している権限は管理者に追加を依頼してください。

| グループ | 権限 |
| --- | --- |
| カタログアイテム | カタログアイテムの表示、カタログアイテムの作成、カタログアイテムの編集 |
| 価格プラン | 価格プランの閲覧、価格プランの作成、価格プランの掲載 |

## 形式の選び方

| 形式 | 使う場面 |
| --- | --- |
| CSV（`.csv`） | ほとんどのカタログに適しています。商品ごとに価格 1 つ、画像 URL 1 つ。スプレッドシートから簡単に書き出せます。 |
| JSON（`products.json`） | 地域別の価格、または商品ごとに複数の画像が必要な場合。画像はすべて URL で指定します。 |
| ZIP（`products.json` と画像） | JSON と同じですが、画像ファイルをマニフェストと一緒にアップロードしたい場合。 |

どの形式も同じルールに従います。商品は `sku` で照合され、インポートは商品の追加または更新のみを行います。ファイルに含まれていない商品が削除されることはありません。

## CSV 形式

### ファイルのルール

- 文字コードは UTF-8 です。Excel が付加する先頭の BOM（バイトオーダーマーク）の有無は問いません。日本語版 Excel の標準の「CSV」（Shift_JIS）と、Excel の「Unicode テキスト」（UTF-16）も読み込めます。[スプレッドシートから CSV を保存する](https://docs.tokenz.one/ja/v1/product/import#%E3%82%B9%E3%83%97%E3%83%AC%E3%83%83%E3%83%89%E3%82%B7%E3%83%BC%E3%83%88%E3%81%8B%E3%82%89-csv-%E3%82%92%E4%BF%9D%E5%AD%98%E3%81%99%E3%82%8B)を参照してください。
- 値はカンマで区切ります。セミコロン区切りやタブ区切りのファイルも使えます。区切り文字はヘッダー行から自動で判定されます。
- 価格の小数点にはドットを使います（例: `7.50`）。小数点のカンマ（`7,50`）、通貨記号（`¥480`）、桁区切り（`1,000`）を含む値は数値ではないと判定されます。
- ファイルの区切り文字（カンマ。セミコロン区切りやタブ区切りのファイルではセミコロンやタブ）、ダブルクォート、改行を含む値はダブルクォートで囲みます。値の中のダブルクォートは `""` と書きます。例（セミコロン区切りのファイル）: `gem-pack-500;500 Gems;"500 gems; added instantly.";480;JPY`
- 1 行目はヘッダー行である必要があります。ヘッダー名の大文字と小文字は区別されません。スプレッドシートが追加する空の列や空行は無視されます。
- メッセージの行番号はデータ行を数えたものです。ヘッダーのすぐ下の行が 1 行目です。
- CSV と JSON のファイルは最大 25 MB です。行数の上限はありません。

### 列

| 列 | 必須 | 説明 |
| --- | --- | --- |
| `sku` | はい | 商品を一意に識別する ID。同じ `sku` を再度インポートすると、その商品が更新されます。 |
| `name` | はい | 商品名。 |
| `description` | はい | 商品の説明。列は必須ですが、値は空でも構いません。 |
| `price` | `free` が true でない場合 | 通貨の通常の単位で表した数値の価格。例: 480 円なら `480`、4.99 ドルなら `4.99`。 |
| `currency` | `price` を指定する場合 | ISO 4217 の通貨コード。例: `JPY`、`USD`。[対応通貨](https://docs.tokenz.one/ja/v1/checkout/currency)を参照してください。 |
| `free` | いいえ | 無料の商品なら `true`。`price` と `currency` は空にします。 |
| `category` | いいえ | カテゴリ名。存在しないカテゴリは作成されます。 |
| `taxCategory` | いいえ | `virtualCurrency`、`digitalGoodsAndServices`、`eBook`、`saas` のいずれか。既定値: `digitalGoodsAndServices`。ゲーム内通貨には `virtualCurrency` を指定してください。 |
| `publish` | いいえ | `true` で商品を公開します。既定値は `false` で、下書きとして保存されます。 |
| `image_url` | いいえ | 公開されている `https` の画像 URL を 1 つ。 |

真偽値の列（`free`、`publish`）には `true`/`false`、`yes`/`no`、`1`/`0` を使用できます。

### 例

JPY で価格を設定したゲームアイテム 3 件です。2 行目は引用符の使い方を、3 行目は無料アイテムを示しています。

```csv
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,
```

## スプレッドシートから CSV を保存する

インポート画面の **テンプレートをダウンロード** から取得したテンプレートに入力し、CSV として保存するのが確実です。

### Microsoft Excel

- **ファイル** > **名前を付けて保存**（または **コピーを保存**）で **CSV UTF-8 (コンマ区切り) (*.csv)** を選びます。どの言語の環境でも、この形式をおすすめします。
- 日本語版 Excel の標準の **CSV (コンマ区切り)** は Shift_JIS で保存されます。この形式でもインポートでき、日本語も正しく読み込まれます。
- ヨーロッパの多くの地域など、小数点にカンマを使う地域の Excel は、「CSV」をセミコロン区切りで保存し、価格を `7,50` のように書き出します。セミコロンは自動で判定されますが、小数点のカンマは価格として読み込めません。保存する前に小数点をドットにしてください（Windows 版 Excel では **ファイル** > **オプション** > **詳細設定** で **システムの区切り文字を使用する** をオフにし、**小数点の記号** を `.` にします）。または、価格をドット付きの文字列として入力してください。
- Excel は `123456789012` のような桁数の多い数値の SKU を `1.23457E+11` に変え、先頭のゼロも削除します。SKU を入力する前に `sku` 列の書式を **文字列** にしてください。指数表記で保存された SKU は、すでに桁が失われているためインポートできません。

### Google スプレッドシート

**ファイル** > **ダウンロード** > **カンマ区切り形式（.csv）** を選びます。UTF-8 で保存されるので、そのままインポートできます。

### Apple Numbers

**ファイル** > **書き出す** > **CSV** を選びます。**テキストエンコーディング** は **Unicode (UTF-8)** のままにしてください。

## JSON 形式

JSON でのインポートには、`products.json` という名前のマニフェストを 1 つ使用します。画像がすべて URL の場合はそのままアップロードし、画像ファイルを参照する場合は ZIP に含めてアップロードします。

### マニフェスト

| フィールド | 必須 | 説明 |
| --- | --- | --- |
| `version` | はい | 常に `1`。 |
| `defaults` | いいえ | 個別に指定していない商品に適用される値。`currency`、`taxCategory`、`category`、`publish` を指定できます。 |
| `products` | はい | 商品のリスト。 |

### 商品のフィールド

| フィールド | 必須 | 説明 |
| --- | --- | --- |
| `sku` | はい | 商品を一意に識別する ID。前後に空白を含めないでください。 |
| `name` | はい | 商品名。 |
| `description` | はい | 商品の説明。説明がない場合は `""` を指定します。 |
| `price` | 価格フィールドのいずれか 1 つ | 通貨の通常の単位で表した数値の価格。 |
| `free` | 価格フィールドのいずれか 1 つ | 無料の商品なら `true`。 |
| `regionPrices` | 価格フィールドのいずれか 1 つ | 2 文字の国コードをキーにした地域別の価格。例: `{ "JP": 980, "US": 6.99 }`。各地域はその地域の通貨を使用します。最初の項目は、記載していないすべての地域に適用される価格です。 |
| `currency` | いいえ | `price` の通貨。既定値は `defaults.currency`、それもなければ `JPY`。`regionPrices` とは併用できません。 |
| `category` | いいえ | カテゴリ名。存在しない場合は作成されます。 |
| `taxCategory` | いいえ | `virtualCurrency`、`digitalGoodsAndServices`、`eBook`、`saas` のいずれか。 |
| `images` | いいえ | 画像のパスまたは URL。最初の画像がメイン画像になります。 |
| `publish` | いいえ | `true` で公開、`false` で下書きとして保存。文字列ではなく真偽値で指定してください。 |

各商品には、価格フィールド（`price`、`free: true`、`regionPrices`）のいずれか 1 つだけを指定します。

### 例

```json
{
  "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"
      ]
    }
  ]
}
```

### ZIP に画像をまとめる

`images/starter-bundle.webp` のように相対パスで指定した画像がある場合は、ルートに `products.json` を置いた ZIP をアップロードします。相対パスは ZIP の中から読み込まれます。

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

## 価格

価格はすべて、通貨の通常の単位で 0 より大きい数値として指定します（480 円なら `480`、4.99 ドルなら `4.99`）。CSV と JSON の `price`、および `regionPrices` のすべての金額に適用されます。

- **小数点以下の桁数。** 通貨が使う桁数より多い小数は指定できません。JPY と KRW には小数がないため、`480.5` JPY はエラーになります。USD や EUR など多くの通貨は 2 桁、BHD や KWD など一部の通貨は 3 桁です。通貨ごとの桁数は[対応通貨](https://docs.tokenz.one/ja/v1/checkout/currency)を参照してください。
- **上限。** 価格の上限は 99,999,999.99 で、通貨の小数点以下の桁数に合わせて変わります。

| 小数点以下の桁数 | 通貨の例 | 上限 |
| --- | --- | --- |
| 0 | JPY、KRW | 99,999,999 |
| 2 | USD、EUR | 99,999,999.99 |
| 3 | BHD、KWD | 99,999,999.999 |

プレビューでは何かを書き込む前にすべての価格を確認するため、これらのルールに合わない価格があると、その行を示すメッセージが表示され、インポートは行われません。

## 画像

- 形式: WebP、PNG、JPEG、GIF。
- 1 枚あたり最大 25 MB です。空のファイルは受け付けられません。
- 画像 URL は一般に公開されている必要があります。ログインが必要な URL や、`localhost` などのプライベートまたはローカルのアドレスは受け付けられません。
- CSV では `image_url` に商品ごとに 1 つの URL を指定します。複数の画像や画像ファイルを使う場合は JSON または ZIP を使用してください。
- 商品を更新する際に画像を指定しなかった場合、既存の画像はそのまま残ります。

## 再インポートと更新

商品は `sku` で照合されます。

- **新しい `sku`**: 商品が作成されます。
- **既存の `sku`**: ファイルの値で商品が更新されます。これが既定の動作です。
- **ファイルにない `sku`**: 商品はそのまま残ります。インポートで商品が削除されることはありません。

既存の商品を変更せずに新しい商品だけを追加するには、インポート前に **新規作成のみ（既存のSKUはスキップ）** を選択します。`sku` がすでに存在する行はスキップされ、結果にスキップとして数えられます。

既存の商品について、インポートでは次の項目は変更されません。

- **既存プランの価格。** 同じ請求間隔のプラン（1 回払いの価格など）がすでに異なる価格で存在する場合、その行は現在の価格のままとなります。行のほかの値は更新され、結果に「price not applied」と表示されます。価格を変更するには、Dashboard で商品を開いてそこで変更してください。プランの価格の置き換えは元に戻せない別の操作のため、インポートでは行いません。
- **税区分。** 商品の作成時に設定されます。

## インポートの手順

1. **商品をインポート** を選択し、`.csv`、`products.json`、`.zip` のいずれかのファイルをアップロードします。
2. プレビューを確認します。各行に、作成、更新、スキップのどれになるかと、エラーの有無が表示されます。
3. エラーがあれば修正して、再度アップロードします。ファイルにエラーがある間は何も書き込まれません。
4. **インポート** を選択します。商品の作成と更新の進行状況が表示されます。
5. 結果を確認します。作成、更新、スキップ、失敗の件数と、失敗した各行の理由が表示されます。

## よくあるエラー

インポート画面では、問題ごとに行番号と SKU が表示されます。例: 「3行目（SKU gem-pack-500）: 価格の currency を入力してください（例: USD、JPY）。」JSON ファイルでは、商品は順番で示されます（「2番目の商品（SKU …）」）。問題が残っている間は何も書き込まれません。ファイルを修正して再度アップロードしてください。

### ファイルの問題

ファイル全体が読み込めない問題です。

| メッセージ | 対処方法 |
| --- | --- |
| ヘッダー行に次の列を追加してください: sku, description | 不足している必須の列を追加してください。`sku`、`name`、`description` は常に必須で、`description` は値が空でも列が必要です。迷ったらテンプレートから始めてください。 |
| 不明な列: …。名前を変えるか削除してください。 | [列](https://docs.tokenz.one/ja/v1/product/import#%E5%88%97)にある名前に変えるか、その列を削除してください。 |
| … はCSVからはインポートできません。 | `regionPrices` などの列には JSON が必要です。[形式の選び方](https://docs.tokenz.one/ja/v1/product/import#%E5%BD%A2%E5%BC%8F%E3%81%AE%E9%81%B8%E3%81%B3%E6%96%B9)を参照してください。 |
| 次の列が重複しています: … | 同じ名前の列は 1 つだけにしてください。 |
| 7列目には列名がありませんが、2行目に値があります。 | 列にデータが残ったままヘッダーのセルが削除されています。ヘッダーを入力し直すか、その列ごと削除してください。 |
| 4行目: 引用符で囲んだ値が閉じられていません。 | `"` で始まる値が `"` で終わっていないため、それ以降が 1 つの値として読まれています。閉じる引用符を追加するか、余分な引用符を削除してください。 |
| 4行目: 閉じ引用符の後に文字があります。 | 値全体を引用符で囲み、値の中の引用符は `""` と書いてください。 |
| 5行目の値の数が、ヘッダーの10列より多くなっています。 | 区切り文字（カンマ、またはセミコロンやタブ）を含む値が引用符で囲まれていないため、以降の値の列がずれています。その値をダブルクォートで囲んでください。 |
| このCSVの文字コードを読み取れません。 | Excel から **CSV UTF-8** で保存し直すか、Google スプレッドシートや Numbers から再度ダウンロードしてください。 |
| このファイルにはヘッダー行だけで商品がありません。 | ヘッダーの下に 1 行 1 商品で追加してください。 |
| このファイルは25MBを超えています。 | カタログを複数のファイルに分けて、順番にインポートしてください。 |
| ZIP に products.json がありません。 | `products.json` をフォルダの中ではなく、ZIP の最上位に置いてください。 |

### 行の問題

| メッセージ | 対処方法 |
| --- | --- |
| price の「7,50」は数値ではありません。 | 小数点にはドットを使い（`7.50`）、通貨記号や桁区切りは付けないでください。Excel が小数点をカンマで書き出す場合は [Microsoft Excel](https://docs.tokenz.one/ja/v1/product/import#microsoft-excel) を参照してください。 |
| JPY の小数点以下は0桁までのため、480.5 は請求できません。価格を丸めてください。 | 通貨が使う桁数に丸めてください。JPY と KRW には小数がありません。[価格](https://docs.tokenz.one/ja/v1/product/import#%E4%BE%A1%E6%A0%BC)を参照してください。 |
| price の 150000000 は上限の 99,999,999 JPY を超えています。 | 通貨ごとの[上限](https://docs.tokenz.one/ja/v1/product/import#%E4%BE%A1%E6%A0%BC)以内の価格にしてください。 |
| 価格の currency を入力してください（例: USD、JPY）。 | CSV では、`price` のある行すべてに `currency` が必要です。 |
| 通貨 … には対応していません。 | [対応通貨](https://docs.tokenz.one/ja/v1/checkout/currency)のコードを使用してください。 |
| SKU … は別の行でも使われています。 | 1 つのファイル内で同じ `sku` は 1 回しか使えません。重複した行の SKU を変えるか、行を削除してください。 |
| SKU 1.23457E+11 は Excel が指数表記に変えた数値のようで、桁が失われています。 | `sku` 列の書式を「文字列」にして SKU を入力し直し、保存してください。 |
| SKUを入力してください。／SKUの前後の空白を削除してください。 | すべての行に、前後に空白のない `sku` を指定してください。 |
| name を入力してください。／description を追加してください。 | `name` を入力してください。`description` は空でも含めてください。 |
| price と currency を入力するか、free を true にしてください。 | 価格と通貨を指定するか、無料に設定してください。 |
| price か free = true のどちらか一方にしてください。 | 無料の商品では `price` と `currency` を空にしてください。 |
| price は0より大きくしてください。 | 正の価格を指定するか、空にして `free` を `true` にしてください。 |
| taxCategory の「…」は無効です。 | `virtualCurrency`、`digitalGoodsAndServices`、`eBook`、`saas` のいずれかを指定してください。 |
| publish が「…」になっています。true か false にしてください。 | CSV では `true`/`false`、`yes`/`no`、`1`/`0` を使えます。JSON では `true` または `false` を引用符なしで記述してください。 |
| image_url の「…」は完全な https URL ではありません。 | `https://` で始まる完全なリンクを指定してください。 |
| 商品が ZIP に含まれていない画像を使っています。 | 同じパスでファイルを ZIP に追加するか、パスを修正してください。パスの大文字と小文字は区別されます。 |
| 商品が、空または25MBを超える画像を使っています。 | より小さい画像に差し替えてください。 |
| version を 1 にしてください。 | `products.json` に `"version": 1` を指定してください。 |

### インポート後

インポート結果には、失敗した行や、ファイルの内容どおりに変更されなかった行が英語の補足付きで表示されます。

| 補足 | 意味 |
| --- | --- |
| price not applied: this interval already has a plan… | 商品は現在の価格のままです。変更方法は[再インポートと更新](https://docs.tokenz.one/ja/v1/product/import#%E5%86%8D%E3%82%A4%E3%83%B3%E3%83%9D%E3%83%BC%E3%83%88%E3%81%A8%E6%9B%B4%E6%96%B0)を参照してください。 |
| sku already exists | **新規作成のみ** を選んだため、既存の商品はスキップされました。 |
| sku belongs to another product | その SKU は、インポートで更新できない別の商品で使われています。別の SKU を使ってください。 |

インポート後に文字化けしている場合は、ファイルの文字コードが正しく判定されていません。**CSV UTF-8** で保存し直して、再度インポートしてください。

## お問い合わせ

インポートしようとしたファイルと、Dashboard に表示されたエラーを添えて Tokenz サポートにお問い合わせください。