API Ordini2026-11Anteprima

Ordini di evasione

Le righe di un ordine che imballiamo in un pacco, con la scatola in cui vanno e il nostro controllo di ogni articolo.

La maggior parte degli ordini ne ha uno. Un ordine i cui articoli arrivano a distanza, o che dividi, ne ha di più.
Un ordine Shopify arriva come richiesta di evasione di Shopify. Lo accettiamo quando ogni riga corrisponde a uno SKU (Variants) e lo rifiutiamo indicando le righe che non corrispondono, così Shopify lo lascia a te.
Un articolo che non supera il nostro controllo genera qc.issue e aspetta la tua scelta prima della spedizione.

Endpoint

GET/v1/fulfillment_ordersElenca gli ordini di evasione
GET/v1/fulfillment_orders/{id}Recupera un ordine di evasione
POST/v1/fulfillment_orders/{id}/holdMetti in attesa
POST/v1/fulfillment_orders/{id}/releaseRilascia
POST/v1/fulfillment_orders/{id}/cancelAnnulla

L’oggetto Fulfillment order

idstring: Inizia con fo_.
orderstring: L’ordine a cui appartiene.
statusstring: open (in attesa dei suoi articoli), in_progress (in imballaggio), on_hold, closed (spedito) o cancelled.
requestobject|null: Per un ordine Shopify: l’ordine di evasione di Shopify e la nostra risposta, accettato o rifiutato con le varianti del negozio non associate a uno SKU.
holdobject|null: reason e note, mentre è in attesa.
packagingstring|null: La scatola o la busta in cui va.
lines[].qcobject: Il nostro controllo: pending, passed o issue, con le foto e la data.
shipmentstring|null: Impostato quando parte.

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

Elenca gli ordini di evasione

GET/v1/fulfillment_orders

Dal più recente. Filtra per ordine o stato.

Scopeorders:read

Parametri di query

orderstring: Facoltativo. Un ID ordine.
statusstring: Facoltativo.
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
}

Recupera un ordine di evasione

GET/v1/fulfillment_orders/{id}

Le sue righe, il nostro controllo di ciascuna, l’imballaggio e la spedizione.

Scopeorders:read

Parametri di percorso

idstringobbligatorio: L’ID dell’ordine di evasione.

Errori

Stato	Tipo	Quando
404	not-found	Nessun ordine di evasione simile su questo account.

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

Metti in attesa

POST/v1/fulfillment_orders/{id}/hold

Lo trattiene finché non lo sblocchi: per aspettare un altro ordine dello stesso cliente, o stock che stai inviando. Lo stoccaggio gratuito sul tuo scaffale continua a scorrere.

Scopeorders:write

Parametri di percorso

idstringobbligatorio: L’ID dell’ordine di evasione.

Corpo

reasonstringobbligatorio: combine, wait_for_stock o other.
notestring: Facoltativa. Una nota per te, salvata con la sospensione.

Errori

Stato	Tipo	Quando
404	not-found	Nessun ordine di evasione simile su questo account.
409	invalid-state	È chiuso o annullato.

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

Rilascia

POST/v1/fulfillment_orders/{id}/release

Lascia procedere un ordine di evasione in attesa.

Scopeorders:write

Parametri di percorso

idstringobbligatorio: L’ID dell’ordine di evasione.

Errori

Stato	Tipo	Quando
404	not-found	Nessun ordine di evasione simile su questo account.
409	invalid-state	Non è in attesa.

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

Annulla

POST/v1/fulfillment_orders/{id}/cancel

Annulla il pacco finché non vi è stato imballato nulla. I suoi articoli restano sul tuo scaffale, da spedire più tardi o con un altro ordine. Per annullare anche l’acquisto, annulla l’ordine.

Scopeorders:write

Parametri di percorso

idstringobbligatorio: L’ID dell’ordine di evasione.

Errori

Stato	Tipo	Quando
404	not-found	Nessun ordine di evasione simile su questo account.
409	invalid-state	È imballato o spedito.

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