Orders-API2026-11Preview

Bestellingen

Een verkoop van jou die we bij de verkoper kopen, in ons magazijn controleren en fotograferen, in jouw doos verpakken en naar je klant verzenden.

Volg een bestelling met webhooks in plaats van polling: bestelevents worden verstuurd bij elke stap. Het pakket zelf is een fulfillmentorder, daarna een zending.

Endpoints

POST/v1/ordersEen bestelling aanmaken
GET/v1/ordersBestellingen opvragen
GET/v1/orders/{id}Een bestelling ophalen
POST/v1/orders/{id}/cancelEen bestelling annuleren

Het Order-object

idstring: Begint met ord_.
external_idstring: Het bestelnummer van je winkel. Uniek binnen je account.
sourcestring: api, of shopify voor bestellingen die je Shopify-winkel ons stuurde.
statusstring: De status van de regel die het minst ver is; zie Statussen hieronder.
payment_statusstring: awaiting_payment, paid, partially_refunded of refunded.
lanestring: saver of fast.
lines[]array: Variant, aantal, gekochte stuks per artikel, status, de magazijnfoto's na controle, en reason bij weigering.
ship_toobject: Naam, adres, telefoon en e-mail van je klant.
packagingstring|null: Je doos of verzendzak met jouw merk; je standaard bij null.
chargesobject: Wat het kost, in CN¥: de inkoop (goederen, ontvangstkosten, belasting) en het pakket (verzending, verwerkingskosten, belasting). Het pakket is een schatting op basis van jouw gewichten tot we het wegen.
amount_duemoney|null: Wat je saldo nog moet dekken, zolang awaiting_payment.
fulfillment_orders[]array: De pakketten waarin hij vertrekt.

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

Stuur ons een bestelling uit je winkel. Elke regel is een variant die je hebt opgeslagen, of een listinglink en SKU die we zo kopen. De bestelling wordt meteen uit je saldo betaald; een bestelling die je saldo niet dekt, wordt toch aangemaakt, als awaiting_payment met amount_due, en gaat vanzelf verder als je opwaardeert.

Bestellingen uit je Shopify-winkel bereiken ons zonder deze aanroep. Gebruik hem voor WooCommerce, Wix, je eigen site, of alles wat verder verkoopt.

Scopeorders:write

Body

external_idstringverplicht: Je bestelnummer. Een tweede bestelling ermee wordt geweigerd.
lines[]arrayverplicht: variant en quantity, of url, sku en quantity. units (optioneel) koopt er zoveel per artikel, voor packs.
ship_toobjectverplicht: name, line1, line2, city, region, postal_code, country (twee letters), phone, email.
lanestring: saver of fast. saver als je het weglaat.
packagingstring: Optioneel. Een verpakkings-id; je standaard als je het weglaat.
notestring: Optioneel. Voor ons magazijnteam, tot 500 tekens.

Fouten

Status	Type	Wanneer
400	bad-body	Een veld ontbreekt of klopt niet; errors[] wijst het aan.
409	duplicate-order	external_id is al een bestelling; order noemt hem.
422	unprocessable	De variant van een regel is uitverkocht, of de link is niet te lezen.
422	not-shippable	Geen gepubliceerd tarief bereikt ship_to.country op die lijn.

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

Bestellingen opvragen

GET/v1/orders

Nieuwste eerst.

Scopeorders:read

Queryparameters

statusstring: Optioneel. Een van de statussen hieronder.
sourcestring: Optioneel. api of shopify.
external_idstring: Optioneel. Zoek er een op je eigen bestelnummer.
created_sincestring: Optioneel. Een tijdstip.
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
}

Een bestelling ophalen

GET/v1/orders/{id}

De status van elke regel, de magazijnfoto's na controle, wat het kostte en de pakketten.

Scopeorders:read

Padparameters

idstringverplicht: De id van de bestelling.

Fouten

Status	Type	Wanneer
404	not-found	Deze bestelling bestaat niet op dit account.

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

Een bestelling annuleren

POST/v1/orders/{id}/cancel

Voordat we kopen, wordt de hele bestelling teruggestort op je saldo. Na het kopen worden de regels die de verkoper terugneemt terugbetaald, en de rest blijft op je schap als magazijnvoorraad. Een verzonden bestelling kan niet worden geannuleerd.

Scopeorders:write

Padparameters

idstringverplicht: De id van de bestelling.

Body

reasonstring: Optioneel. Bewaard bij de bestelling.

Fouten

Status	Type	Wanneer
404	not-found	Deze bestelling bestaat niet op dit account.
409	invalid-state	Hij is verzonden.

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

Statussen

Elke regel heeft een eigen status; die van een bestelling is die van de regel die het minst ver is. Op volgorde:

Status	Betekenis
awaiting_payment	Je saldo dekte het niet. Waardeer op en hij gaat vanzelf verder.
buying	Betaald; we kopen het bij de verkoper.
with_seller	Gekocht; de verkoper heeft het nog niet naar ons magazijn gestuurd.
checked	In ons magazijn, gecontroleerd en gefotografeerd, wacht om ingepakt te worden.
shipped	Onderweg, met tracking.
delivered	De vervoerder meldt dat het is bezorgd.
rejected	We konden het niet kopen (uitverkocht, link weg); reason zegt waarom, en het wordt terugbetaald.
cancelled	Jij hebt hem geannuleerd.

Geld

In de voorbeelden kost het kopen van één stuk CN¥ 57,00 en het verzenden CN¥ 134,52, afgeschreven van je saldo. Wat elke regel is: Kosten.

Het Order-object

Een bestelling aanmaken

Body

Fouten

Bestellingen opvragen

Queryparameters

Een bestelling ophalen

Padparameters

Fouten

Een bestelling annuleren

Padparameters

Body

Fouten

Statussen

Geld