Orders-API2026-11Vorschau

Fulfillment-Aufträge

Die Positionen einer Bestellung, die wir in ein Paket packen, mit dem Karton, in den sie kommen, und unserer Prüfung jedes Artikels.

Die meisten Bestellungen haben einen. Eine Bestellung, deren Artikel weit auseinander ankommen oder die du aufteilst, hat mehrere.
Eine Shopify-Bestellung kommt als Shopifys eigene Fulfillment-Anfrage an. Wir nehmen sie an, wenn jede Position einer SKU zugeordnet ist (Varianten), und lehnen sie unter Nennung der Positionen ab, bei denen das nicht so ist, damit Shopify sie bei dir lässt.
Ein Artikel, der unsere Prüfung nicht besteht, löst qc.issue aus und wartet vor dem Versand auf deine Entscheidung.

Endpunkte

GET/v1/fulfillment_ordersFulfillment-Aufträge auflisten
GET/v1/fulfillment_orders/{id}Einen Fulfillment-Auftrag abrufen
POST/v1/fulfillment_orders/{id}/holdZurückhalten
POST/v1/fulfillment_orders/{id}/releaseFreigeben
POST/v1/fulfillment_orders/{id}/cancelAbbrechen

Das Fulfillment-Order-Objekt

idstring: Beginnt mit fo_.
orderstring: Die Bestellung, zu der er gehört.
statusstring: open (wartet auf seine Artikel), in_progress (wird gepackt), on_hold, closed (versendet) oder cancelled.
requestobject|null: Für eine Shopify-Bestellung: Shopifys Fulfillment-Auftrag und unsere Antwort darauf, angenommen oder abgelehnt mit den Shop-Varianten, die keiner SKU zugeordnet sind.
holdobject|null: reason und note, solange zurückgehalten.
packagingstring|null: Der Karton oder die Versandtasche, in die es kommt.
lines[].qcobject: Unsere Prüfung: pending, passed oder issue, mit den Fotos und dem Zeitpunkt.
shipmentstring|null: Gesetzt, sobald es rausgeht.

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

Fulfillment-Aufträge auflisten

GET/v1/fulfillment_orders

Neueste zuerst. Nach Bestellung oder Status filtern.

Scopeorders:read

Query-Parameter

orderstring: Optional. Eine Bestell-ID.
statusstring: Optional.
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
}

Einen Fulfillment-Auftrag abrufen

GET/v1/fulfillment_orders/{id}

Seine Positionen, unsere Prüfung jeder davon, die Verpackung und die Sendung.

Scopeorders:read

Pfadparameter

idstringerforderlich: Die ID des Fulfillment-Auftrags.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Fulfillment-Auftrag in diesem Konto.

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

Zurückhalten

POST/v1/fulfillment_orders/{id}/hold

Hält ihn vom Versand ab, bis du ihn freigibst: um auf eine andere Bestellung an denselben Kunden zu warten oder auf Ware, die du einschickst. Die kostenlose Lagerung in deinem Regal läuft weiter.

Scopeorders:write

Pfadparameter

idstringerforderlich: Die ID des Fulfillment-Auftrags.

Body

reasonstringerforderlich: combine, wait_for_stock oder other.
notestring: Optional. Eine Notiz für dich, die mit der Zurückstellung gespeichert wird.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Fulfillment-Auftrag in diesem Konto.
409	invalid-state	Er ist geschlossen oder storniert.

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

Freigeben

POST/v1/fulfillment_orders/{id}/release

Lässt einen zurückgehaltenen Fulfillment-Auftrag weiterlaufen.

Scopeorders:write

Pfadparameter

idstringerforderlich: Die ID des Fulfillment-Auftrags.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Fulfillment-Auftrag in diesem Konto.
409	invalid-state	Er ist nicht zurückgehalten.

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

Storniert das Paket, solange noch nichts hineingepackt wurde. Seine Artikel bleiben in deinem Regal, um später oder mit einer anderen Bestellung versendet zu werden. Um auch den Kauf zu stornieren, storniere die Bestellung.

Scopeorders:write

Pfadparameter

idstringerforderlich: Die ID des Fulfillment-Auftrags.

Fehler

Status	Typ	Wann
404	not-found	Kein solcher Fulfillment-Auftrag in diesem Konto.
409	invalid-state	Er ist gepackt oder versendet.

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

Das Fulfillment-Order-Objekt

Fulfillment-Aufträge auflisten

Query-Parameter

Einen Fulfillment-Auftrag abrufen

Pfadparameter

Fehler

Zurückhalten

Pfadparameter

Body

Fehler

Freigeben

Pfadparameter

Fehler

Abbrechen

Pfadparameter

Fehler