Ninjabuy 로고Business
영업팀에 문의
주문 API2026-11프리뷰

주문

내 판매 건을 저희가 판매자에게서 구매하고, 창고에서 검수·촬영한 뒤 내 박스에 포장해 고객에게 배송해요.

폴링 대신 웹훅으로 주문을 추적하세요: 각 단계가 일어날 때마다 주문 이벤트가 발생해요. 택배 자체는 풀필먼트 주문이고, 그다음 배송이 돼요.

엔드포인트

Order 객체

idstring
ord_로 시작해요.
external_idstring
스토어 주문 번호. 계정 내에서 고유.
sourcestring
api, 또는 Shopify 스토어에서 보낸 주문이면 shopify.
statusstring
가장 덜 진행된 항목의 상태. 아래 상태를 참고하세요.
payment_statusstring
awaiting_payment, paid, partially_refunded 또는 refunded.
lanestring
saver 또는 fast.
lines[]array
옵션, 수량, 상품당 구매 수량, 상태, 검수 후 창고 사진, 거절된 경우 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필수
내 주문 번호. 같은 번호의 두 번째 주문은 거절돼요.
lines[]array필수
variant와 quantity, 또는 url, sku, quantity. units(선택 사항)는 묶음용으로 상품당 그만큼 구매해요.
ship_toobject필수
name, line1, line2, city, region, postal_code, country(두 글자), phone, email.
lanestring
saver 또는 fast. 생략하면 saver.
packagingstring
선택 사항. 포장 ID. 생략하면 기본 포장.
notestring
선택 사항. 저희 창고 팀용, 최대 500자.

오류

상태유형시점
400bad-body필드가 없거나 잘못되었어요. errors[]가 해당 위치를 가리켜요.
409duplicate-orderexternal_id가 이미 주문이에요. order가 해당 주문을 가리켜요.
422unprocessable항목의 옵션이 품절이거나 링크를 읽을 수 없어요.
422not-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.

오류

상태유형시점
404not-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
선택 사항. 주문에 저장돼요.

오류

상태유형시점
404not-found이 계정에 해당 주문이 없어요.
409invalid-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이 들며 잔액에서 차감돼요. 각 항목 설명: 수수료.