アカウントAPI2026-11プレビュー

残高

注文の支払いに使うお金（CN¥）。ninjabuy.comでチャージし、APIは読み取るだけでカードに請求することはありません。

残高で賄えない注文は awaiting_payment として待機し、チャージ後に自動で進みます。
キャンセルした注文や購入できなかった明細の返金は残高に戻ります。手数料にすべての請求を記載しています。

エンドポイント

GET/v1/balance残高を取得
GET/v1/balance/transactions取引一覧

Balanceオブジェクト

availablemoney: 新しい注文に使える額（CN¥）。
reservedmoney: 購入中の注文と計量待ちの荷物のために確保されています。
top_up_urlstring: ninjabuy.comにログインしてチャージする場所。

balance

{
  "available": { "amount": "2140.00", "currency": "CNY" },
  "reserved": { "amount": "264.20", "currency": "CNY" },
  "top_up_url": "https://www.ninjabuy.com/me/balance/top-up",
  "updated_at": "2026-11-04T09:20:03Z"
}

残高を取得

GET/v1/balance

大量の注文を送る前に確認してください。

スコープbalance:read

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

Response 200

HTTP/2 200 OK

{
  "available": { "amount": "2140.00", "currency": "CNY" },
  "reserved": { "amount": "264.20", "currency": "CNY" },
  "top_up_url": "https://www.ninjabuy.com/me/balance/top-up",
  "updated_at": "2026-11-04T09:20:03Z"
}

取引一覧

GET/v1/balance/transactions

チャージ、注文と送料の請求、返金（新しい順）。金額は符号付きで、請求はマイナスです。

スコープbalance:read

クエリパラメータ

typestring: 任意。top_up、order、shipping、refund のいずれか。
orderstring: 任意。注文ID：その注文で動いたものすべて。
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/balance/transactions?limit=3" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "txn_k22a",
      "type": "shipping",
      "order": "ord_3n7q",
      "amount": { "amount": "-134.52", "currency": "CNY" },
      "created_at": "2026-11-03T05:58:00Z"
    },
    {
      "id": "txn_k21d",
      "type": "order",
      "order": "ord_3n7q",
      "amount": { "amount": "-57.00", "currency": "CNY" },
      "created_at": "2026-11-01T09:14:02Z"
    },
    {
      "id": "txn_k1zz",
      "type": "top_up",
      "order": null,
      "amount": { "amount": "2000.00", "currency": "CNY" },
      "created_at": "2026-10-31T16:40:12Z"
    }
  ],
  "has_more": true,
  "cursor": "c_k1zz"
}