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

商品

インポートから保存した出品。あなたのタイトルと価格、販売先のストアが含まれます。

商品の送信先はShopifyです。Shopifyストアが販売しているマーケットプレイスの注文もShopify経由で当社に届きます：ストアを接続。
WooCommerceやWixのストアは自分の商品を管理し、注文を作成で注文を送ります。

エンドポイント

GET/v1/products商品一覧
GET/v1/products/{id}商品を取得
PATCH/v1/products/{id}商品を更新
POST/v1/products/{id}/pushShopifyに送信
DELETE/v1/products/{id}商品を削除

Productオブジェクト

idstring: prd_ で始まります。
titlestring: あなたのタイトル。出品者のものはインポートに残ります。
statusstring: active、または paused（あなたによる停止、またはコストが上がりすぎたり出品者が売り切れた際の同期ルールによる停止）。
sourceobject: マーケットプレイス、出品リンク、中国の出品者。
options[]array: オプション名（最大3つ）、ストアでの表示どおりに。
price_range, cost_rangeobject: バリエーションごとのあなたの価格と出品者の価格。
channels[]array: 出品先：ストア、そこでの商品ID、そこでのステータス。
syncobject: 従う同期ルールと、出品を最後に読み取った日時。
importstring: 保存元のインポート。

product

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

商品一覧

GET/v1/products

あなたの商品（新しい順）。

スコープproducts:read

クエリパラメータ

statusstring: 任意。active または paused。
channelstring: 任意。shopify（そこに出品されているもの）。
changed_sincestring: 任意。日時：それ以降にコストまたは在庫が変わった商品のみ。
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/products?status=active&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "prd_8f2k",
      "title": "Heavyweight Washed Hoodie",
      "status": "active",
      "variants_count": 6
    },
    {
      "id": "prd_1x0a",
      "title": "Canvas Tote",
      "status": "active",
      "variants_count": 3
    }
  ],
  "has_more": true,
  "cursor": "c_1x0a"
}

商品を取得

GET/v1/products/{id}

仕入れ先、チャンネル、同期状態を含む商品1つ。バリエーションは別のルートです。

スコープproducts:read

パスパラメータ

idstring必須: 商品のID。

エラー

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

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

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

商品を更新

PATCH/v1/products/{id}

タイトルや説明を変更したり、一時停止・再開します。変更するものだけを送ってください。価格はバリエーションごとです（バリエーション）。送信済みの商品は、次の送信時に変更がストアに反映されます。

スコープproducts:write

パスパラメータ

idstring必須: 商品のID。

ボディ

titlestring: 任意。
descriptionstring: 任意。ストアに表示するHTML。
statusstring: 任意。active または paused。paused にするとチャンネルの在庫が0になります。
sync_rulestring: 任意。同期ルールID。null なら既定ルール。

エラー

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

curl -X PATCH "https://www.ninjabuy.com/api/v1/products/prd_8f2k" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "paused",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Shopifyに送信

POST/v1/products/{id}/push

連携したShopifyストアに商品を出品します：Shopify商品1つ、残したSKUごとのバリエーション、写真、各バリエーションの在庫はFulfilled by NinjaBuy拠点に置かれるので、注文は当社に届きます。

初回の送信は下書きとして作成されます。タイトルと写真は中国のマーケットプレイスのものなので、購入者より先に読んでから、Shopifyで公開してください。
再送信すると同じShopify商品が更新されます：価格と在庫が再設定され、外したバリエーションは削除されます。ステータス、タイトル、説明、写真は、新しいものを送らない限りShopifyでの状態のままです。
在庫は出品者の数量で、上限は100です。当社は注文ごとに購入するので、これはShopifyが売り切れと表示するまでに受けられる注文数です。
価格はUS$なので、ストアはUS$で販売している必要があります。売り切れのバリエーションはスキップされ、skipped[] に記載されます。

スコープproducts:write

パスパラメータ

idstring必須: 商品のID。

ボディ

shopstring: 連携したストア（例：acme-goods.myshopify.com）。複数連携している場合のみ必要です。
title, descriptionstring: 任意。送った場合だけShopifyに送信されます。

エラー

ステータス	タイプ	時期
409	no-linked-store	このアカウントに連携しているShopifyストアがないか、複数あるのに`shop`が指定されていません。
409	store-not-ready	ストアのアクセスが切れたか、当社拠点がまだ設定されていません。ShopifyでNinjaBuyアプリを一度開いてください。
422	store-currency	ストアはUS$で販売していません。
422	too-many-options	出品のオプションが3つを超えています。Shopifyは3つまでです。
422	unprocessable	すべてのバリエーションが売り切れか、Shopifyがフィールドを拒否しました。detail にその内容が入ります。

curl -X POST "https://www.ninjabuy.com/api/v1/products/prd_8f2k/push" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "shop": "acme-goods.myshopify.com" }'

Response 200

HTTP/2 200 OK

{
  "channel": "shopify",
  "shop": "acme-goods.myshopify.com",
  "external_id": "gid://shopify/Product/8812042",
  "status": "draft",
  "created": true,
  "variants": 5,
  "skipped": [{ "sku": "5187209555", "reason": "sold_out" }],
  "admin_url": "https://admin.shopify.com/store/acme-goods/products/8812042"
}

商品を削除

DELETE/v1/products/{id}

同期を停止し、チャンネルの在庫を0にします。Shopifyの商品はアーカイブ用に残ります。すでに入った注文は引き続き発送されます。

スコープproducts:write

パスパラメータ

idstring必須: 商品のID。

エラー

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

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

Response 200

HTTP/2 200 OK

{ "id": "prd_8f2k", "deleted": true }