API zamówień2026-11Podgląd

Zlecenia realizacji

Pozycje zamówienia, które pakujemy do jednej paczki, z pudełkiem, do którego trafiają, i naszą kontrolą każdego produktu.

Większość zamówień ma jedno. Zamówienie, którego produkty docierają w dużych odstępach albo które rozdzielisz, ma ich więcej.
Zamówienie Shopify przychodzi jako własne żądanie realizacji Shopify. Przyjmujemy je, gdy każda pozycja jest zmapowana na SKU (Warianty), a odrzucamy, wskazując niezmapowane pozycje, więc Shopify zostawia je u ciebie.
Produkt, który nie przejdzie naszej kontroli, wywołuje qc.issue i czeka na twoją decyzję przed wysyłką.

Endpointy

GET/v1/fulfillment_ordersLista zleceń realizacji
GET/v1/fulfillment_orders/{id}Pobranie zlecenia realizacji
POST/v1/fulfillment_orders/{id}/holdWstrzymanie
POST/v1/fulfillment_orders/{id}/releaseZwolnij
POST/v1/fulfillment_orders/{id}/cancelAnuluj

Obiekt Fulfillment order

idstring: Zaczyna się od fo_.
orderstring: Zamówienie, do którego należy.
statusstring: open (czeka na produkty), in_progress (w pakowaniu), on_hold, closed (wysłane) lub cancelled.
requestobject|null: Dla zamówienia Shopify: zlecenie realizacji Shopify i nasza odpowiedź na nie — przyjęte albo odrzucone z wariantami sklepu niezmapowanymi na SKU.
holdobject|null: reason i note, gdy wstrzymane.
packagingstring|null: Pudełko lub koperta, do której trafia.
lines[].qcobject: Nasza kontrola: pending, passed lub issue, ze zdjęciami i czasem.
shipmentstring|null: Ustawiane, gdy wyjdzie.

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"
}

Lista zleceń realizacji

GET/v1/fulfillment_orders

Od najnowszych. Filtruj według zamówienia lub statusu.

Zakresorders:read

Parametry zapytania

orderstring: Opcjonalne. ID zamówienia.
statusstring: Opcjonalne.
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
}

Pobranie zlecenia realizacji

GET/v1/fulfillment_orders/{id}

Jego pozycje, nasza kontrola każdej, opakowanie i przesyłka.

Zakresorders:read

Parametry ścieżki

idstringwymagane: ID zlecenia realizacji.

Błędy

Status	Typ	Kiedy
404	not-found	Na tym koncie nie ma takiego zlecenia realizacji.

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"
}

Wstrzymanie

POST/v1/fulfillment_orders/{id}/hold

Wstrzymuje wysyłkę, dopóki jej nie zwolnisz: by poczekać na inne zamówienie do tego samego klienta albo na zapas, który dosyłasz. Darmowe przechowywanie na półce nadal biegnie.

Zakresorders:write

Parametry ścieżki

idstringwymagane: ID zlecenia realizacji.

Body

reasonstringwymagane: combine, wait_for_stock lub other.
notestring: Opcjonalnie. Notatka dla ciebie, zapisana razem ze wstrzymaniem.

Błędy

Status	Typ	Kiedy
404	not-found	Na tym koncie nie ma takiego zlecenia realizacji.
409	invalid-state	Jest zamknięte lub anulowane.

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"
}

Zwolnij

POST/v1/fulfillment_orders/{id}/release

Pozwala wstrzymanemu zleceniu realizacji ruszyć dalej.

Zakresorders:write

Parametry ścieżki

idstringwymagane: ID zlecenia realizacji.

Błędy

Status	Typ	Kiedy
404	not-found	Na tym koncie nie ma takiego zlecenia realizacji.
409	invalid-state	Nie jest wstrzymane.

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"
}

Anuluj

POST/v1/fulfillment_orders/{id}/cancel

Anuluje paczkę, dopóki nic do niej nie zapakowano. Jej produkty zostają na twojej półce, do wysłania później lub z innym zamówieniem. Aby anulować też zakup, anuluj zamówienie.

Zakresorders:write

Parametry ścieżki

idstringwymagane: ID zlecenia realizacji.

Błędy

Status	Typ	Kiedy
404	not-found	Na tym koncie nie ma takiego zlecenia realizacji.
409	invalid-state	Jest zapakowane lub wysłane.

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"
}