API de pedidos2026-11Prévia

Ordens de processamento

As linhas de um pedido que embalamos em um pacote, com a caixa em que vão e a nossa verificação de cada item.

A maioria dos pedidos tem uma. Um pedido cujos itens chegam muito separados, ou que você divide, tem mais.
Um pedido da Shopify chega como a própria solicitação de processamento da Shopify. Aceitamos quando cada linha corresponde a um SKU (Variantes), e recusamos informando as linhas que não correspondem, para que a Shopify mantenha o pedido com você.
Um item reprovado na nossa verificação gera qc.issue e espera a sua decisão antes de ser enviado.

Endpoints

GET/v1/fulfillment_ordersListar ordens de processamento
GET/v1/fulfillment_orders/{id}Obter uma ordem de processamento
POST/v1/fulfillment_orders/{id}/holdReter
POST/v1/fulfillment_orders/{id}/releaseLiberar
POST/v1/fulfillment_orders/{id}/cancelCancelar

O objeto Fulfillment order

idstring: Começa com fo_.
orderstring: O pedido a que pertence.
statusstring: open (aguardando os itens), in_progress (em embalagem), on_hold, closed (enviada) ou cancelled.
requestobject|null: Para um pedido da Shopify: a ordem de processamento da Shopify e a nossa resposta, aceita, ou recusada com as variantes da loja que não estão vinculadas a um SKU.
holdobject|null: reason e note, enquanto estiver retida.
packagingstring|null: A caixa ou o envelope em que vai.
lines[].qcobject: A nossa verificação: pending, passed ou issue, com as fotos e a data.
shipmentstring|null: Definido quando sai.

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 ordens de processamento

GET/v1/fulfillment_orders

Mais recentes primeiro. Filtre por pedido ou status.

Escopoorders:read

Parâmetros de consulta

orderstring: Opcional. Um 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
}

Obter uma ordem de processamento

GET/v1/fulfillment_orders/{id}

As linhas, a nossa verificação de cada uma, a embalagem e o envio.

Escopoorders:read

Parâmetros de caminho

idstringobrigatório: O id da ordem de processamento.

Erros

Status	Tipo	Quando
404	not-found	Essa ordem de processamento não existe nesta conta.

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

Reter

POST/v1/fulfillment_orders/{id}/hold

Impede o envio até você liberar: para esperar outro pedido do mesmo cliente, ou um estoque que você está enviando. A armazenagem grátis na sua prateleira continua contando.

Escopoorders:write

Parâmetros de caminho

idstringobrigatório: O id da ordem de processamento.

Corpo

reasonstringobrigatório: combine, wait_for_stock ou other.
notestring: Opcional. Uma nota para você, salva com a retenção.

Erros

Status	Tipo	Quando
404	not-found	Essa ordem de processamento não existe nesta conta.
409	invalid-state	Está fechada ou 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

Deixa uma ordem de processamento retida seguir.

Escopoorders:write

Parâmetros de caminho

idstringobrigatório: O id da ordem de processamento.

Erros

Status	Tipo	Quando
404	not-found	Essa ordem de processamento não existe nesta conta.
409	invalid-state	Não está retida.

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 o pacote enquanto nada foi embalado nele. Os itens ficam na sua prateleira, para enviar depois ou com outro pedido. Para cancelar também a compra, cancele o pedido.

Escopoorders:write

Parâmetros de caminho

idstringobrigatório: O id da ordem de processamento.

Erros

Status	Tipo	Quando
404	not-found	Essa ordem de processamento não existe nesta conta.
409	invalid-state	Está embalada ou 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"
}