API Commandes2026-11Aperçu

Commandes d’exécution

Les lignes d’une commande que nous emballons dans un colis, avec la boîte utilisée et notre contrôle de chaque article.

La plupart des commandes en ont un. Une commande dont les articles arrivent à des moments éloignés, ou que vous divisez, en a plusieurs.
Une commande Shopify arrive comme une demande d’exécution Shopify. Nous l’acceptons quand chaque ligne correspond à un SKU (Variants), et la refusons en nommant les lignes qui ne correspondent pas, pour que Shopify vous la laisse.
Un article qui échoue à notre contrôle déclenche qc.issue et attend votre choix avant l’expédition.

Endpoints

GET/v1/fulfillment_ordersLister les commandes d’exécution
GET/v1/fulfillment_orders/{id}Récupérer une commande d’exécution
POST/v1/fulfillment_orders/{id}/holdMettre en attente
POST/v1/fulfillment_orders/{id}/releaseLibérer
POST/v1/fulfillment_orders/{id}/cancelAnnuler

L’objet Fulfillment order

idstring: Commence par fo_.
orderstring: La commande à laquelle il appartient.
statusstring: open (en attente de ses articles), in_progress (en cours d’emballage), on_hold, closed (expédiée) ou cancelled.
requestobject|null: Pour une commande Shopify : la commande d’exécution de Shopify et notre réponse, acceptée, ou refusée avec les variantes de la boutique qui ne sont associées à aucun SKU.
holdobject|null: reason et note, pendant la mise en attente.
packagingstring|null: La boîte ou la pochette d’envoi dans laquelle il part.
lines[].qcobject: Notre contrôle : pending, passed ou issue, avec les photos et la date.
shipmentstring|null: Renseigné à son départ.

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

Lister les commandes d’exécution

GET/v1/fulfillment_orders

Les plus récents d’abord. Filtrez par commande ou par statut.

Scopeorders:read

Paramètres de requête

orderstring: Facultatif. Un identifiant de commande.
statusstring: Facultatif.
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
}

Récupérer une commande d’exécution

GET/v1/fulfillment_orders/{id}

Ses lignes, notre contrôle de chacune, l’emballage et l’envoi.

Scopeorders:read

Paramètres de chemin

idstringobligatoire: L’identifiant de la commande d’exécution.

Erreurs

Statut	Type	Quand
404	not-found	Aucune commande d’exécution de ce type sur ce compte.

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

Mettre en attente

POST/v1/fulfillment_orders/{id}/hold

L’empêche de partir jusqu’à ce que vous le débloquiez : pour attendre une autre commande du même client, ou du stock que vous envoyez. Le stockage gratuit sur votre étagère continue de courir.

Scopeorders:write

Paramètres de chemin

idstringobligatoire: L’identifiant de la commande d’exécution.

Corps

reasonstringobligatoire: combine, wait_for_stock ou other.
notestring: Facultatif. Une note pour vous, enregistrée avec la mise en attente.

Erreurs

Statut	Type	Quand
404	not-found	Aucune commande d’exécution de ce type sur ce compte.
409	invalid-state	Elle est clôturée ou annulée.

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

Libérer

POST/v1/fulfillment_orders/{id}/release

Laisse repartir une commande d’exécution en attente.

Scopeorders:write

Paramètres de chemin

idstringobligatoire: L’identifiant de la commande d’exécution.

Erreurs

Statut	Type	Quand
404	not-found	Aucune commande d’exécution de ce type sur ce compte.
409	invalid-state	Elle n’est pas en attente.

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

Annuler

POST/v1/fulfillment_orders/{id}/cancel

Annule le colis tant que rien n’y a été emballé. Ses articles restent sur votre étagère, à expédier plus tard ou avec une autre commande. Pour annuler aussi l’achat, annulez la commande.

Scopeorders:write

Paramètres de chemin

idstringobligatoire: L’identifiant de la commande d’exécution.

Erreurs

Statut	Type	Quand
404	not-found	Aucune commande d’exécution de ce type sur ce compte.
409	invalid-state	Il est emballé ou expédié.

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