주문 API2026-11프리뷰

풀필먼트 주문

택배 하나에 포장하는 주문 항목, 넣을 박스, 각 상품의 검수.

대부분의 주문은 하나예요. 상품 도착 시기가 크게 다르거나 내가 나눈 주문은 여러 개예요.
Shopify 주문은 Shopify 자체의 풀필먼트 요청으로 도착해요. 모든 항목이 SKU에 연결되어 있으면 수락하고(옵션), 그렇지 않으면 해당 항목을 알려 주며 거절하므로 주문은 내게 남아요.
검수를 통과하지 못한 상품은 qc.issue를 발생시키고 배송 전에 내 선택을 기다려요.

엔드포인트

GET/v1/fulfillment_orders풀필먼트 주문 목록
GET/v1/fulfillment_orders/{id}풀필먼트 주문 조회
POST/v1/fulfillment_orders/{id}/hold보류
POST/v1/fulfillment_orders/{id}/release보류 해제
POST/v1/fulfillment_orders/{id}/cancel취소

Fulfillment order 객체

idstring: fo_로 시작해요.
orderstring: 속한 주문.
statusstring: open(상품 대기), in_progress(포장 중), on_hold, closed(배송됨) 또는 cancelled.
requestobject|null: Shopify 주문의 경우: Shopify의 풀필먼트 주문과 저희 응답. 수락, 또는 SKU에 연결되지 않은 스토어 옵션을 알려 주며 거절.
holdobject|null: 보류 중일 때 reason과 note.
packagingstring|null: 넣을 박스 또는 봉투.
lines[].qcobject: 저희 검수: pending, passed 또는 issue, 사진과 시각 포함.
shipmentstring|null: 출고 시 설정.

fulfillment_order

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

풀필먼트 주문 목록

GET/v1/fulfillment_orders

최신순. 주문이나 상태로 필터링.

범위orders:read

쿼리 매개변수

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

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

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "fo_7k1x",
      "order": "ord_3n6z",
      "status": "on_hold",
      "hold": { "reason": "combine" }
    }
  ],
  "has_more": false,
  "cursor": null
}

풀필먼트 주문 조회

GET/v1/fulfillment_orders/{id}

항목, 각 항목의 검수, 포장, 배송.

범위orders:read

경로 매개변수

idstring필수: 풀필먼트 주문 ID.

오류

상태	유형	시점
404	not-found	이 계정에 해당 풀필먼트 주문이 없어요.

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

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

보류

POST/v1/fulfillment_orders/{id}/hold

해제할 때까지 배송을 멈춰요. 같은 고객의 다른 주문이나 보내고 있는 재고를 기다릴 때 쓰세요. 선반의 무료 보관 기간은 계속 흘러가요.

범위orders:write

경로 매개변수

idstring필수: 풀필먼트 주문 ID.

본문

reasonstring필수: combine, wait_for_stock 또는 other.
notestring: 선택 사항. 보류와 함께 저장되는 나만의 메모입니다.

오류

상태	유형	시점
404	not-found	이 계정에 해당 풀필먼트 주문이 없어요.
409	invalid-state	종료되었거나 취소되었어요.

curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/hold" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "combine" }'

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "on_hold",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": {
    "reason": "combine",
    "note": null,
    "since": "2026-11-02T04:00:00Z"
  },
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

보류 해제

POST/v1/fulfillment_orders/{id}/release

보류된 풀필먼트 주문을 진행시켜요.

범위orders:write

경로 매개변수

idstring필수: 풀필먼트 주문 ID.

오류

상태	유형	시점
404	not-found	이 계정에 해당 풀필먼트 주문이 없어요.
409	invalid-state	보류 상태가 아니에요.

curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/release" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "in_progress",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}

취소

POST/v1/fulfillment_orders/{id}/cancel

아직 아무것도 포장되지 않은 택배를 취소해요. 상품은 내 선반에 남아 나중에 또는 다른 주문과 함께 배송할 수 있어요. 구매까지 취소하려면 주문을 취소하세요.

범위orders:write

경로 매개변수

idstring필수: 풀필먼트 주문 ID.

오류

상태	유형	시점
404	not-found	이 계정에 해당 풀필먼트 주문이 없어요.
409	invalid-state	포장되었거나 배송되었어요.

curl -X POST "https://www.ninjabuy.com/api/v1/fulfillment_orders/fo_7k2m/cancel" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

HTTP/2 200 OK

{
  "id": "fo_7k2m",
  "order": "ord_3n7q",
  "status": "cancelled",
  "request": {
    "channel": "shopify",
    "external_id": "gid://shopify/FulfillmentOrder/6650012",
    "status": "accepted",
    "unmapped": []
  },
  "hold": null,
  "packaging": "pkg_acme_mailer",
  "lines": [
    {
      "line": "lin_9a2c",
      "sku": "5187209554",
      "quantity": 1,
      "qc": {
        "status": "passed",
        "photos": [
          "https://media.ninjabuy.com/qc/ord_3n7q/1.webp",
          "https://media.ninjabuy.com/qc/ord_3n7q/2.webp"
        ],
        "checked_at": "2026-11-02T03:20:11Z"
      }
    }
  ],
  "shipment": null,
  "created_at": "2026-11-01T09:14:03Z"
}