Orders-API2026-11Vorschau

Bestellungen

Ein Verkauf von dir, den wir beim Verkäufer kaufen, in unserem Lager prüfen und fotografieren, in deinen Karton packen und an deinen Kunden versenden.

Verfolge eine Bestellung mit Webhooks statt mit Polling: Bestell-Events werden bei jedem Schritt ausgelöst. Das Paket selbst ist ein Fulfillment-Auftrag, dann eine Sendung.

Endpunkte

POST/v1/ordersBestellung anlegen
GET/v1/ordersBestellungen auflisten
GET/v1/orders/{id}Eine Bestellung abrufen
POST/v1/orders/{id}/cancelEine Bestellung stornieren

Das Order-Objekt

idstring: Beginnt mit ord_.
external_idstring: Die Bestellnummer deines Shops. Eindeutig in deinem Konto.
sourcestring: api, oder shopify für Bestellungen, die uns dein Shopify-Shop geschickt hat.
statusstring: Der Status der am wenigsten weit gekommenen Position; siehe Status unten.
payment_statusstring: awaiting_payment, paid, partially_refunded oder refunded.
lanestring: saver oder fast.
lines[]array: Variante, Menge, pro Artikel gekaufte Stück, Status, die Lagerfotos nach der Prüfung und reason bei Ablehnung.
ship_toobject: Name, Adresse, Telefon und E-Mail deines Kunden.
packagingstring|null: Dein Markenkarton oder deine Versandtasche; bei null dein Standard.
chargesobject: Was es kostet, in CN¥: die Beschaffung (Ware, Annahmegebühr, Steuer) und das Paket (Versand, Bearbeitungsgebühr, Steuer). Das Paket ist eine Schätzung aus deinen Gewichten, bis wir es wiegen.
amount_duemoney|null: Was dein Guthaben noch decken muss, solange awaiting_payment.
fulfillment_orders[]array: Die Pakete, in denen sie rausgeht.

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

Schick uns eine Bestellung deines Shops. Jede Position ist eine Variante, die du gespeichert hast, oder ein Angebotslink mit SKU, den wir so kaufen. Die Bestellung wird sofort aus deinem Guthaben bezahlt; eine, die dein Guthaben nicht deckt, wird trotzdem angelegt, als awaiting_payment mit amount_due, und geht von selbst weiter, wenn du auflädst.

Bestellungen aus deinem Shopify-Shop erreichen uns ohne diesen Aufruf. Nutze ihn für WooCommerce, Wix, deine eigene Website oder alles andere, was verkauft.

Scopeorders:write

Body

external_idstringerforderlich: Deine Bestellnummer. Eine zweite Bestellung damit wird abgelehnt.
lines[]arrayerforderlich: variant und quantity oder url, sku und quantity. units (optional) kauft so viele pro Artikel, für Packs.
ship_toobjecterforderlich: name, line1, line2, city, region, postal_code, country (zwei Buchstaben), phone, email.
lanestring: saver oder fast. Ohne Angabe saver.
packagingstring: Optional. Eine Verpackungs-ID; ohne Angabe dein Standard.
notestring: Optional. Für unser Lagerteam, bis zu 500 Zeichen.

Fehler

Status	Typ	Wann
400	bad-body	Ein Feld fehlt oder ist falsch; errors[] zeigt darauf.
409	duplicate-order	external_id ist schon eine Bestellung; order nennt sie.
422	unprocessable	Die Variante einer Position ist ausverkauft, oder ihr Link lässt sich nicht lesen.
422	not-shippable	Kein veröffentlichter Tarif erreicht ship_to.country auf diesem Versandweg.

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

Bestellungen auflisten

GET/v1/orders

Neueste zuerst.

Scopeorders:read

Query-Parameter

statusstring: Optional. Einer der Status unten.
sourcestring: Optional. api oder shopify.
external_idstring: Optional. Such eine anhand deiner eigenen Bestellnummer.
created_sincestring: Optional. Ein Zeitpunkt.
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
}

Eine Bestellung abrufen

GET/v1/orders/{id}

Der Status jeder Position, ihre Lagerfotos nach der Prüfung, was sie gekostet hat und ihre Pakete.

Scopeorders:read

Pfadparameter

idstringerforderlich: Die ID der Bestellung.

Fehler

Status	Typ	Wann
404	not-found	Keine solche Bestellung in diesem Konto.

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

Eine Bestellung stornieren

POST/v1/orders/{id}/cancel

Vor dem Kauf wird die ganze Bestellung deinem Guthaben erstattet. Nach dem Kauf werden die Positionen erstattet, die der Verkäufer zurücknimmt, und der Rest bleibt als Lagerbestand in deinem Regal. Eine versendete Bestellung kann nicht storniert werden.

Scopeorders:write

Pfadparameter

idstringerforderlich: Die ID der Bestellung.

Body

reasonstring: Optional. Wird an der Bestellung gespeichert.

Fehler

Status	Typ	Wann
404	not-found	Keine solche Bestellung in diesem Konto.
409	invalid-state	Sie ist versendet.

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

Status

Jede Position hat ihren eigenen Status; der einer Bestellung ist der ihrer am wenigsten weit gekommenen Position. Der Reihe nach:

Status	Bedeutung
awaiting_payment	Dein Guthaben hat es nicht gedeckt. Lade auf, und sie geht von selbst weiter.
buying	Bezahlt; wir kaufen es beim Verkäufer.
with_seller	Gekauft; der Verkäufer hat es noch nicht an unser Lager geschickt.
checked	In unserem Lager, geprüft und fotografiert, wartet aufs Verpacken.
shipped	Unterwegs, mit Sendungsverfolgung.
delivered	Der Versanddienstleister meldet die Zustellung.
rejected	Wir konnten es nicht kaufen (ausverkauft, Link weg); reason sagt, warum, und es wird erstattet.
cancelled	Du hast sie storniert.

Geld

In den Beispielen kostet der Kauf eines Stücks 57,00 CN¥ und sein Versand 134,52 CN¥, abgezogen von deinem Guthaben. Was jede Zeile ist: Gebühren.

Das Order-Objekt

Bestellung anlegen

Body

Fehler

Bestellungen auflisten

Query-Parameter

Eine Bestellung abrufen

Pfadparameter

Fehler

Eine Bestellung stornieren

Pfadparameter

Body

Fehler

Status

Geld