API Ordini2026-11Anteprima

Ordini

Una tua vendita che acquistiamo dal venditore, controlliamo e fotografiamo nel nostro magazzino, imballiamo nella tua scatola e spediamo al tuo cliente.

Segui un ordine con i webhook invece di interrogare l’API: gli eventi dell’ordine scattano a ogni fase. Il pacco stesso è un ordine di evasione, poi una spedizione.

Endpoint

POST/v1/ordersCrea un ordine
GET/v1/ordersElenca gli ordini
GET/v1/orders/{id}Recupera un ordine
POST/v1/orders/{id}/cancelAnnulla un ordine

L’oggetto Order

idstring: Inizia con ord_.
external_idstring: Il numero d’ordine del tuo negozio. Unico sul tuo account.
sourcestring: api, o shopify per gli ordini inviati dal tuo negozio Shopify.
statusstring: Lo stato della riga meno avanzata; vedi Stati qui sotto.
payment_statusstring: awaiting_payment, paid, partially_refunded o refunded.
lanestring: saver o fast.
lines[]array: Variante, quantità, unità acquistate per articolo, stato, le foto del magazzino una volta controllata, e reason quando viene rifiutata.
ship_toobject: Nome, indirizzo, telefono ed email del tuo cliente.
packagingstring|null: La tua scatola o busta col marchio; la predefinita se null.
chargesobject: Quanto costa, in CN¥: l’approvvigionamento (merce, commissione di ricezione, tassa) e il pacco (spedizione, commissione di gestione, tassa). Il pacco è una stima dai tuoi pesi finché non lo pesiamo.
amount_duemoney|null: Quanto deve ancora coprire il saldo, durante awaiting_payment.
fulfillment_orders[]array: I pacchi in cui parte.

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

Inviaci uno degli ordini del tuo negozio. Ogni riga è una variante che hai salvato, o un link di inserzione e uno SKU che acquistiamo così come sono. L’ordine viene pagato subito dal saldo; uno che il saldo non copre viene comunque creato, come awaiting_payment con amount_due, e procede da solo quando ricarichi.

Gli ordini dal tuo negozio Shopify ci arrivano senza questa chiamata. Usala per WooCommerce, Wix, il tuo sito o qualsiasi altra cosa che vende.

Scopeorders:write

Corpo

external_idstringobbligatorio: Il tuo numero d’ordine. Un secondo ordine con lo stesso viene rifiutato.
lines[]arrayobbligatorio: variant e quantity, o url, sku e quantity. units (facoltativo) ne acquista altrettante per articolo, per le confezioni.
ship_toobjectobbligatorio: name, line1, line2, city, region, postal_code, country (due lettere), phone, email.
lanestring: saver o fast. saver se omesso.
packagingstring: Facoltativo. Un ID di imballaggio; il tuo predefinito se omesso.
notestring: Facoltativo. Per il team del nostro magazzino, fino a 500 caratteri.

Errori

Stato	Tipo	Quando
400	bad-body	Un campo manca o è errato; errors[] lo indica.
409	duplicate-order	external_id è già un ordine; order lo indica.
422	unprocessable	La variante di una riga è esaurita, o il suo link non è leggibile.
422	not-shippable	Nessuna tariffa pubblicata raggiunge ship_to.country su quella linea.

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

Elenca gli ordini

GET/v1/orders

Dal più recente.

Scopeorders:read

Parametri di query

statusstring: Facoltativo. Uno degli stati qui sotto.
sourcestring: Facoltativo. api o shopify.
external_idstring: Facoltativo. Trovane uno con il tuo numero d’ordine.
created_sincestring: Facoltativo. Una data.
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
}

Recupera un ordine

GET/v1/orders/{id}

Lo stato di ogni riga, le foto del magazzino una volta controllata, quanto è costata e i suoi pacchi.

Scopeorders:read

Parametri di percorso

idstringobbligatorio: L’ID dell’ordine.

Errori

Stato	Tipo	Quando
404	not-found	Nessun ordine simile su questo 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"
}

Annulla un ordine

POST/v1/orders/{id}/cancel

Prima dell’acquisto, l’intero ordine viene rimborsato sul saldo. Dopo l’acquisto, le righe che il venditore riprende vengono rimborsate e le altre restano sul tuo scaffale come stock in magazzino. Un ordine spedito non può essere annullato.

Scopeorders:write

Parametri di percorso

idstringobbligatorio: L’ID dell’ordine.

Corpo

reasonstring: Facoltativo. Conservato sull’ordine.

Errori

Stato	Tipo	Quando
404	not-found	Nessun ordine simile su questo account.
409	invalid-state	È stato spedito.

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

Stati

Ogni riga ha il suo stato; quello di un ordine è lo stato della riga meno avanzata. In ordine:

Stato	Significato
awaiting_payment	Il saldo non bastava. Ricarica e procede da solo.
buying	Pagato; lo stiamo acquistando dal venditore.
with_seller	Acquistato; il venditore non l’ha ancora inviato al nostro magazzino.
checked	Nel nostro magazzino, controllato e fotografato, in attesa di imballaggio.
shipped	In viaggio, con tracciamento.
delivered	Il corriere dice che è arrivato.
rejected	Non abbiamo potuto acquistarlo (esaurito, link sparito); reason dice perché, ed è rimborsato.
cancelled	L’hai annullato tu.

Denaro

Negli esempi, acquistare un’unità costa 57,00 CN¥ e spedirla 134,52 CN¥, presi dal saldo. Cos’è ogni riga: Commissioni.

L’oggetto Order

Crea un ordine

Corpo

Errori

Elenca gli ordini

Parametri di query

Recupera un ordine

Parametri di percorso

Errori

Annulla un ordine

Parametri di percorso

Corpo

Errori

Stati

Denaro