주문 API2026-11프리뷰

배송 내역

고객에게 가는 중인 택배. 송장 정보는 주문이 들어온 스토어로 돌아가므로 고객은 저희가 아닌 내게서 소식을 받아요.

order.shipped는 배송이 생성될 때 송장 정보와 함께 발생해요.

엔드포인트

GET/v1/shipments배송 목록
GET/v1/shipments/{id}배송 조회
GET/v1/shipments/{id}/tracking배송 추적 이벤트 조회

Shipment 객체

idstring: shp_로 시작해요.
order, fulfillment_orderstring: 담고 있는 것.
lanestring: saver 또는 fast.
carrier, tracking_number, tracking_urlstring: 고객에게 보낼 송장 정보 준비 완료.
weight_ginteger: 포장할 때 택배의 무게.
shipping_chargedmoney: 계량한 택배의 배송비, 취급 수수료, 세금(CN¥): 잔액에서 결제한 금액.
pushed_to_channelboolean: 주문이 들어온 스토어에 송장 정보가 있는지. 그다음 Shopify가 고객에게 이메일로 보내요.
statusstring: in_transit, out_for_delivery, delivered 또는 exception(보류, 반송, 분실).
shipped_at, delivered_atstring|null: 저희를 떠난 시각과 택배사가 도착했다고 알린 시각.

shipment

{
  "id": "shp_5r8w",
  "order": "ord_3n7q",
  "fulfillment_order": "fo_7k2m",
  "lane": "saver",
  "carrier": "YunExpress",
  "tracking_number": "YT2630812345678",
  "tracking_url": "https://t.17track.net/en#nums=YT2630812345678",
  "weight_g": 176,
  "shipping_charged": { "amount": "134.52", "currency": "CNY" },
  "pushed_to_channel": true,
  "status": "in_transit",
  "shipped_at": "2026-11-03T06:00:00Z",
  "delivered_at": null
}

배송 목록

GET/v1/shipments

최신순. 상태로 필터링해 내 확인이 필요한 것을 찾으세요.

범위orders:read

쿼리 매개변수

statusstring: 선택 사항.
orderstring: 선택 사항. 주문 ID.
shipped_sincestring: 선택 사항. 시각.
limit, cursor: Pagination

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

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "shp_5q1d",
      "order": "ord_3m2b",
      "tracking_number": "YT2630811190042",
      "status": "exception"
    }
  ],
  "has_more": false,
  "cursor": null
}

배송 조회

GET/v1/shipments/{id}

택배 1개와 송장 정보.

범위orders:read

경로 매개변수

idstring필수: 배송 ID.

오류

상태	유형	시점
404	not-found	이 계정에 해당 배송이 없어요.

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

Response 200

HTTP/2 200 OK

{
  "id": "shp_5r8w",
  "order": "ord_3n7q",
  "fulfillment_order": "fo_7k2m",
  "lane": "saver",
  "carrier": "YunExpress",
  "tracking_number": "YT2630812345678",
  "tracking_url": "https://t.17track.net/en#nums=YT2630812345678",
  "weight_g": 176,
  "shipping_charged": { "amount": "134.52", "currency": "CNY" },
  "pushed_to_channel": true,
  "status": "in_transit",
  "shipped_at": "2026-11-03T06:00:00Z",
  "delivered_at": null
}

배송 추적 이벤트 조회

GET/v1/shipments/{id}/tracking

택배사 스캔 기록, 오래된 순, 영어.

범위orders:read

경로 매개변수

idstring필수: 배송 ID.

오류

상태	유형	시점
404	not-found	이 계정에 해당 배송이 없어요.

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

Response 200

HTTP/2 200 OK

{
  "shipment": "shp_5r8w",
  "status": "in_transit",
  "events": [
    {
      "at": "2026-11-03T06:00:00Z",
      "where": "Shenzhen, CN",
      "status": "in_transit",
      "description": "Left the NinjaBuy warehouse"
    },
    {
      "at": "2026-11-05T22:10:00Z",
      "where": "Shenzhen, CN",
      "status": "in_transit",
      "description": "Departed the origin country"
    },
    {
      "at": "2026-11-09T19:40:00Z",
      "where": "Los Angeles, US",
      "status": "in_transit",
      "description": "Arrived in the destination country"
    }
  ]
}