注文API2026-11プレビュー

注文

あなたの販売分を当社が出品者から購入し、倉庫で検品・撮影し、あなたの箱に梱包してお客様に発送します。

ポーリングではなくWebhookで注文を追跡してください：各段階が起きるたびに注文イベントが発生します。荷物自体はフルフィルメント注文、その後発送になります。

エンドポイント

POST/v1/orders注文を作成
GET/v1/orders注文一覧
GET/v1/orders/{id}注文を取得
POST/v1/orders/{id}/cancel注文をキャンセル

Orderオブジェクト

idstring: ord_ で始まります。
external_idstring: ストアの注文番号。アカウント内で一意。
sourcestring: api、またはShopifyストアから送られた注文なら shopify。
statusstring: 最も進んでいない明細のステータス。下のステータスをご覧ください。
payment_statusstring: awaiting_payment、paid、partially_refunded、refunded のいずれか。
lanestring: saver または fast。
lines[]array: バリエーション、数量、1個あたりの購入数、ステータス、検品後の倉庫写真、断った場合は reason。
ship_toobject: お客様の名前、住所、電話番号、メールアドレス。
packagingstring|null: あなたのブランド箱または封筒。null なら既定のもの。
chargesobject: 費用（CN¥）：買付（商品代、入庫料、税金）と荷物（送料、出荷作業料、税金）。荷物は当社が計量するまで、あなたの重さからの見積もりです。
amount_duemoney|null: awaiting_payment の間、残高でまだ賄う必要がある額。
fulfillment_orders[]array: 出荷される荷物。

order

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

注文を作成

POST/v1/orders

ストアの注文を当社に送ります。各明細は保存したバリエーション、またはそのまま購入する出品リンクとSKUです。注文はすぐに残高から支払われます。残高で賄えない注文もamount_due付きのawaiting_paymentとして作成され、チャージすると自動で進みます。

Shopifyストアからの注文はこの呼び出しなしで当社に届きます。WooCommerce、Wix、独自サイトなど、販売するあらゆるものに使ってください。

スコープorders:write

ボディ

external_idstring必須: あなたの注文番号。同じ番号の2つ目の注文は拒否されます。
lines[]array必須: variant と quantity、または url、sku、quantity。units（任意）はパック用に1個あたりその数を購入します。
ship_toobject必須: name、line1、line2、city、region、postal_code、country（2文字）、phone、email。
lanestring: saver または fast。省略時は saver。
packagingstring: 任意。梱包ID。省略時は既定の梱包。
notestring: 任意。当社倉庫チーム向け、最大500文字。

エラー

ステータス	タイプ	時期
400	bad-body	フィールドが欠けているか誤っています。errors[]が該当箇所を示します。
409	duplicate-order	external_id はすでに注文になっています。order がその注文を示します。
422	unprocessable	明細のバリエーションが売り切れか、リンクを読み取れません。
422	not-shippable	そのルートで ship_to.country に届く公開料金がありません。

curl -X POST "https://www.ninjabuy.com/api/v1/orders" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "1012",
    "lines": [{ "variant": "var_41hz", "quantity": 1 }],
    "ship_to": {
      "name": "Sam Rivera",
      "line1": "500 Congress Ave",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "country": "US",
      "phone": "+15125550142",
      "email": "sam@example.com"
    },
    "lane": "saver"
  }'

Response 201

HTTP/2 201 Created

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "api",
  "status": "buying",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "buying",
      "photos": [],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": [],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

注文一覧

GET/v1/orders

新しい順。

スコープorders:read

クエリパラメータ

statusstring: 任意。以下のステータスのいずれか。
sourcestring: 任意。api または shopify。
external_idstring: 任意。あなた自身の注文番号で検索。
created_sincestring: 任意。日時。
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/orders?status=checked" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "ord_3n7q",
      "external_id": "1012",
      "status": "checked",
      "payment_status": "paid"
    }
  ],
  "has_more": false,
  "cursor": null
}

注文を取得

GET/v1/orders/{id}

すべての明細のステータス、検品後の倉庫写真、費用、荷物。

スコープorders:read

パスパラメータ

idstring必須: 注文のID。

エラー

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

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

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "external_id": "1012",
  "source": "shopify",
  "status": "checked",
  "payment_status": "paid",
  "lane": "saver",
  "lines": [
    {
      "id": "lin_9a2c",
      "variant": "var_41hz",
      "sku": "5187209554",
      "title": "Heavyweight Washed Hoodie, Black / M",
      "quantity": 1,
      "units": 1,
      "status": "checked",
      "photos": [
        "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
        "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
      ],
      "reason": null
    }
  ],
  "ship_to": {
    "name": "Sam Rivera",
    "line1": "500 Congress Ave",
    "line2": null,
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "phone": "+15125550142",
    "email": "sam@example.com"
  },
  "packaging": "pkg_acme_mailer",
  "charges": {
    "procurement": {
      "goods": { "amount": "38.00", "currency": "CNY" },
      "intake_fee": { "amount": "12.00", "currency": "CNY" },
      "tax": { "amount": "7.00", "currency": "CNY" },
      "total": { "amount": "57.00", "currency": "CNY" }
    },
    "parcel": {
      "lane": "saver",
      "shipping": { "amount": "68.00", "currency": "CNY" },
      "handling_fee": { "amount": "50.00", "currency": "CNY" },
      "tax": { "amount": "16.52", "currency": "CNY" },
      "total": { "amount": "134.52", "currency": "CNY" },
      "estimate": true
    },
    "total": { "amount": "191.52", "currency": "CNY" }
  },
  "amount_due": null,
  "fulfillment_orders": ["fo_7k2m"],
  "created_at": "2026-11-01T09:14:02Z",
  "updated_at": "2026-11-02T03:20:11Z"
}

注文をキャンセル

POST/v1/orders/{id}/cancel

購入前なら注文全体が残高に返金されます。購入後は、出品者が引き取った明細が返金され、残りは倉庫在庫としてあなたの棚に残ります。発送済みの注文はキャンセルできません。

スコープorders:write

パスパラメータ

idstring必須: 注文のID。

ボディ

reasonstring: 任意。注文に保存されます。

エラー

ステータス	タイプ	時期
404	not-found	このアカウントにその注文はありません。
409	invalid-state	発送済みです。

curl -X POST "https://www.ninjabuy.com/api/v1/orders/ord_3n7q/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer changed their mind" }'

Response 200

HTTP/2 200 OK

{
  "id": "ord_3n7q",
  "status": "cancelled",
  "payment_status": "refunded",
  "refunded": { "amount": "191.52", "currency": "CNY" }
}

ステータス

明細ごとにステータスがあり、注文のステータスは最も進んでいない明細のものです。順に：

ステータス	意味
awaiting_payment	残高で賄えませんでした。チャージすれば自動で進みます。
buying	支払い済み。出品者から購入中です。
with_seller	購入済み。出品者はまだ当社倉庫に発送していません。
checked	当社倉庫で検品・撮影済み、梱包待ち。
shipped	追跡付きで輸送中。
delivered	配送業者が到着したと報告しています。
rejected	購入できませんでした（売り切れ、リンク切れ）。reason に理由が入り、返金されます。
cancelled	あなたがキャンセルしました。

お金

サンプルでは、1個の購入にCN¥57.00、発送にCN¥134.52かかり、残高から差し引かれます。各明細の内容：手数料。