API de pedidos2026-11Vista previa

Órdenes de preparación

Las líneas de un pedido que empacamos en un paquete, con la caja en que van y nuestra revisión de cada artículo.

La mayoría de los pedidos tienen una. Un pedido cuyos artículos llegan muy separados, o que divides, tiene más.
Un pedido de Shopify llega como la propia solicitud de preparación de Shopify. La aceptamos cuando cada línea corresponde a un SKU (Variantes), y la rechazamos indicando las líneas que no, para que Shopify la deje contigo.
Un artículo que no pasa nuestra revisión genera qc.issue y espera tu decisión antes de enviarse.

Endpoints

GET/v1/fulfillment_ordersListar órdenes de preparación
GET/v1/fulfillment_orders/{id}Obtener una orden de preparación
POST/v1/fulfillment_orders/{id}/holdRetener
POST/v1/fulfillment_orders/{id}/releaseLiberar
POST/v1/fulfillment_orders/{id}/cancelCancelar

El objeto Fulfillment order

idstring: Empieza por fo_.
orderstring: El pedido al que pertenece.
statusstring: open (esperando sus artículos), in_progress (en empaque), on_hold, closed (enviada) o cancelled.
requestobject|null: Para un pedido de Shopify: la orden de preparación de Shopify y nuestra respuesta, aceptada o rechazada con las variantes de la tienda que no están vinculadas a un SKU.
holdobject|null: reason y note, mientras está retenida.
packagingstring|null: La caja o el sobre en que va.
lines[].qcobject: Nuestra revisión: pending, passed o issue, con las fotos y la fecha.
shipmentstring|null: Se fija cuando sale.

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

Listar órdenes de preparación

GET/v1/fulfillment_orders

Lo más reciente primero. Filtra por pedido o estado.

Alcanceorders:read

Parámetros de consulta

orderstring: Opcional. Un id de pedido.
statusstring: Opcional.
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
}

Obtener una orden de preparación

GET/v1/fulfillment_orders/{id}

Sus líneas, nuestra revisión de cada una, el empaque y el envío.

Alcanceorders:read

Parámetros de ruta

idstringobligatorio: El id de la orden de preparación.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe esa orden de preparación en esta cuenta.

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

Retener

POST/v1/fulfillment_orders/{id}/hold

Evita que se envíe hasta que la liberes: para esperar otro pedido del mismo cliente, o stock que estás enviando. El almacenamiento gratuito en tu estante sigue corriendo.

Alcanceorders:write

Parámetros de ruta

idstringobligatorio: El id de la orden de preparación.

Cuerpo

reasonstringobligatorio: combine, wait_for_stock u other.
notestring: Opcional. Una nota para ti, guardada con la retención.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe esa orden de preparación en esta cuenta.
409	invalid-state	Está cerrada o cancelada.

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

Liberar

POST/v1/fulfillment_orders/{id}/release

Deja continuar una orden de preparación retenida.

Alcanceorders:write

Parámetros de ruta

idstringobligatorio: El id de la orden de preparación.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe esa orden de preparación en esta cuenta.
409	invalid-state	No está retenida.

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

Cancelar

POST/v1/fulfillment_orders/{id}/cancel

Cancela el paquete mientras no se haya empacado nada en él. Sus artículos quedan en tu estante, para enviarlos más tarde o con otro pedido. Para cancelar también la compra, cancela el pedido.

Alcanceorders:write

Parámetros de ruta

idstringobligatorio: El id de la orden de preparación.

Errores

Estado	Tipo	Cuándo
404	not-found	No existe esa orden de preparación en esta cuenta.
409	invalid-state	Está empacada o enviada.

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