カタログAPI2026-11プレビュー

バリエーション

商品の1つのオプション（サイズ、色、スマホの機種など）。当社が購入する出品者のSKUと、ストアが販売するバリエーションに紐付きます。

バリエーションは注文明細が指定するものです。その在庫数が販売可能数を示します。

エンドポイント

GET/v1/products/{id}/variants商品のバリエーション一覧
GET/v1/variants/{id}バリエーションを取得
PATCH/v1/variants/{id}バリエーションを更新

Variantオブジェクト

idstring: var_ で始まります。
skustring: 当社が読み取った出品者のSKU。当社が購入するもの。
label, options: オプションの値（1つのラベルとして、またオプション名ごとに）。
costmoney: 出品者の1個あたりの価格（CN¥、最後に読み取った時点）。
pricemoney: あなたの販売価格。
in_stockboolean: 出品者が販売できるかどうか（最後に読み取った時点）。
unitsinteger: 1個売れるごとに購入する数：ストアの3個パックなら3個購入します。
weight_ginteger: 送料の見積もりに使う、あなたが入力した1個の梱包後の重さ。
external_variant_idstring|null: ストアのバリエーション。その注文でこのSKUを購入します。紐付けのないバリエーションの注文は断られます。

variant

{
  "id": "var_41hz",
  "product": "prd_8f2k",
  "sku": "5187209554",
  "label": "Black / M",
  "options": { "Color": "Black", "Size": "M" },
  "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
  "cost": { "amount": "38.00", "currency": "CNY" },
  "price": { "amount": "49.99", "currency": "USD" },
  "in_stock": true,
  "units": 1,
  "weight_g": 180,
  "external_variant_id": "gid://shopify/ProductVariant/44100231",
  "updated_at": "2026-11-04T09:20:03Z"
}

商品のバリエーション一覧

GET/v1/products/{id}/variants

すべてのバリエーションのコスト、あなたの価格、在庫、紐付け。

スコープproducts:read

パスパラメータ

idstring必須: 商品のID。

クエリパラメータ

limit, cursor: Pagination

エラー

ステータス	タイプ	時期
404	not-found	このアカウントにその商品はありません。

curl "https://www.ninjabuy.com/api/v1/products/prd_8f2k/variants" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "var_41hz",
      "product": "prd_8f2k",
      "sku": "5187209554",
      "label": "Black / M",
      "options": { "Color": "Black", "Size": "M" },
      "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
      "cost": { "amount": "38.00", "currency": "CNY" },
      "price": { "amount": "49.99", "currency": "USD" },
      "in_stock": true,
      "units": 1,
      "weight_g": 180,
      "external_variant_id": "gid://shopify/ProductVariant/44100231",
      "updated_at": "2026-11-04T09:20:03Z"
    },
    {
      "id": "var_41j0",
      "product": "prd_8f2k",
      "sku": "5187209555",
      "label": "Black / L",
      "options": { "Color": "Black", "Size": "M" },
      "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
      "cost": { "amount": "38.00", "currency": "CNY" },
      "price": { "amount": "49.99", "currency": "USD" },
      "in_stock": false,
      "units": 1,
      "weight_g": 180,
      "external_variant_id": null,
      "updated_at": "2026-11-04T09:20:03Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

バリエーションを取得

GET/v1/variants/{id}

バリエーション1つ。

スコープproducts:read

パスパラメータ

idstring必須: バリエーションのID。

エラー

ステータス	タイプ	時期
404	not-found	このアカウントにそのバリエーションはありません。

curl "https://www.ninjabuy.com/api/v1/variants/var_41hz" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "var_41hz",
  "product": "prd_8f2k",
  "sku": "5187209554",
  "label": "Black / M",
  "options": { "Color": "Black", "Size": "M" },
  "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
  "cost": { "amount": "38.00", "currency": "CNY" },
  "price": { "amount": "49.99", "currency": "USD" },
  "in_stock": true,
  "units": 1,
  "weight_g": 180,
  "external_variant_id": "gid://shopify/ProductVariant/44100231",
  "updated_at": "2026-11-04T09:20:03Z"
}

バリエーションを更新

PATCH/v1/variants/{id}

価格、1販売あたりの購入数、重さ、対応するストアのバリエーションを設定します。変更するものだけを送ってください。

スコープproducts:write

パスパラメータ

idstring必須: バリエーションのID。

ボディ

pricemoney: 任意。あなたの販売価格。
unitsinteger: 任意。1〜50。
weight_ginteger: 任意。1個の梱包後の重さ（グラム）。
external_variant_idstring|null: 任意。ストアのバリエーションに紐付けるか、null で紐付けを解除。

エラー

ステータス	タイプ	時期
404	not-found	このアカウントにそのバリエーションはありません。
409	invalid-state	そのストアのバリエーションはすでに別のSKUに対応しています。

curl -X PATCH "https://www.ninjabuy.com/api/v1/variants/var_41hz" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{
    "units": 2,
    "price": { "amount": "89.99", "currency": "USD" }
  }'

Response 200

HTTP/2 200 OK

{
  "id": "var_41hz",
  "product": "prd_8f2k",
  "sku": "5187209554",
  "label": "Black / M",
  "options": { "Color": "Black", "Size": "M" },
  "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
  "cost": { "amount": "38.00", "currency": "CNY" },
  "price": { "amount": "89.99", "currency": "USD" },
  "in_stock": true,
  "units": 2,
  "weight_g": 180,
  "external_variant_id": "gid://shopify/ProductVariant/44100231",
  "updated_at": "2026-11-04T09:20:03Z"
}