API Commandes2026-11Aperçu

Commandes

Une de vos ventes, que nous achetons au vendeur, vérifions et photographions dans notre entrepôt, emballons dans votre boîte et expédions à votre client.

Suivez une commande avec des webhooks plutôt qu’en interrogeant l’API : les événements de commande sont déclenchés à chaque étape. Le colis lui-même est une commande d’exécution, puis un envoi.

Endpoints

POST/v1/ordersCréer une commande
GET/v1/ordersLister les commandes
GET/v1/orders/{id}Récupérer une commande
POST/v1/orders/{id}/cancelAnnuler une commande

L’objet Order

idstring: Commence par ord_.
external_idstring: Le numéro de commande de votre boutique. Unique sur votre compte.
sourcestring: api, ou shopify pour les commandes envoyées par votre boutique Shopify.
statusstring: Le statut de la ligne la moins avancée ; voir Statuts ci-dessous.
payment_statusstring: awaiting_payment, paid, partially_refunded ou refunded.
lanestring: saver ou fast.
lines[]array: Variante, quantité, unités achetées par article, statut, les photos d’entrepôt une fois vérifiée, et reason en cas de refus.
ship_toobject: Le nom, l’adresse, le téléphone et l’e-mail de votre client.
packagingstring|null: Votre boîte ou pochette à votre marque ; celle par défaut si null.
chargesobject: Ce que ça coûte, en CN¥ : l’approvisionnement (articles, frais de réception, taxe) et le colis (expédition, frais de préparation, taxe). Le colis est une estimation d’après vos poids jusqu’à ce que nous le pesions.
amount_duemoney|null: Ce que votre solde doit encore couvrir, pendant awaiting_payment.
fulfillment_orders[]array: Les colis dans lesquels il part.

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

Envoyez-nous une commande de votre boutique. Chaque ligne est une variante enregistrée, ou un lien d’annonce et un SKU que nous achetons tels quels. La commande est payée immédiatement depuis votre solde ; une commande que votre solde ne couvre pas est quand même créée, en awaiting_payment avec amount_due, et repart d’elle-même quand vous rechargez.

Les commandes de votre boutique Shopify nous parviennent sans cet appel. Utilisez-le pour WooCommerce, Wix, votre propre site, ou tout ce qui vend.

Scopeorders:write

Corps

external_idstringobligatoire: Votre numéro de commande. Une deuxième commande avec ce numéro est refusée.
lines[]arrayobligatoire: variant et quantity, ou url, sku et quantity. units (facultatif) en achète autant par article, pour les lots.
ship_toobjectobligatoire: name, line1, line2, city, region, postal_code, country (deux lettres), phone, email.
lanestring: saver ou fast. saver si omis.
packagingstring: Facultatif. Un identifiant d’emballage ; votre emballage par défaut si omis.
notestring: Facultatif. Pour l’équipe de notre entrepôt, jusqu’à 500 caractères.

Erreurs

Statut	Type	Quand
400	bad-body	Un champ manque ou est incorrect ; errors[] l’indique.
409	duplicate-order	external_id est déjà une commande ; order l’indique.
422	unprocessable	La variante d’une ligne est épuisée, ou son lien est illisible.
422	not-shippable	Aucun tarif publié n’atteint ship_to.country sur cette ligne.

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

Lister les commandes

GET/v1/orders

Les plus récents d’abord.

Scopeorders:read

Paramètres de requête

statusstring: Facultatif. L’un des statuts ci-dessous.
sourcestring: Facultatif. api ou shopify.
external_idstring: Facultatif. Retrouvez-en une par votre propre numéro de commande.
created_sincestring: Facultatif. Une date.
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
}

Récupérer une commande

GET/v1/orders/{id}

Le statut de chaque ligne, ses photos d’entrepôt une fois vérifiée, son coût et ses colis.

Scopeorders:read

Paramètres de chemin

idstringobligatoire: L’identifiant de la commande.

Erreurs

Statut	Type	Quand
404	not-found	Aucune commande de ce type sur ce compte.

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

Annuler une commande

POST/v1/orders/{id}/cancel

Avant l’achat, toute la commande est remboursée sur votre solde. Après l’achat, les lignes que le vendeur reprend sont remboursées et le reste reste sur votre étagère comme stock en entrepôt. Une commande expédiée ne peut pas être annulée.

Scopeorders:write

Paramètres de chemin

idstringobligatoire: L’identifiant de la commande.

Corps

reasonstring: Facultatif. Conservé sur la commande.

Erreurs

Statut	Type	Quand
404	not-found	Aucune commande de ce type sur ce compte.
409	invalid-state	Il a été expédié.

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

Statuts

Chaque ligne a son propre statut ; celui d’une commande est celui de sa ligne la moins avancée. Dans l’ordre :

Statut	Signification
awaiting_payment	Votre solde ne la couvrait pas. Rechargez et elle repart d’elle-même.
buying	Payé ; nous l’achetons au vendeur.
with_seller	Acheté ; le vendeur ne l’a pas encore envoyé à notre entrepôt.
checked	Dans notre entrepôt, vérifié et photographié, en attente d’emballage.
shipped	En route, avec suivi.
delivered	Le transporteur indique qu’il est arrivé.
rejected	Nous n’avons pas pu l’acheter (épuisé, lien disparu) ; reason indique pourquoi, et il est remboursé.
cancelled	Vous l’avez annulée.

Argent

Dans les exemples, acheter une unité coûte 57,00 CNY et l’expédier 134,52 CNY, prélevés sur votre solde. Ce qu’est chaque ligne : Frais.

L’objet Order

Créer une commande

Corps

Erreurs

Lister les commandes

Paramètres de requête

Récupérer une commande

Paramètres de chemin

Erreurs

Annuler une commande

Paramètres de chemin

Corps

Erreurs

Statuts

Argent