Sob encomenda

Sob encomenda é a venda sem estoque disponível: o cliente paga e o pedido fica estacionado aguardando a mercadoria chegar. Quando você abastece o estoque do SKU, a plataforma detecta e retoma o pedido sozinha. Se a sua integração só conhece o fluxo padrão, esses pedidos parecem "travados depois do pago"; este guia explica essa espera e como ela se destrava. É o workflow backorder.

Quando um pedido cai aqui

Pedido sob encomenda nasce de venda B2B (pedido direto, proposta de representante) sobre produto que permite venda sem estoque, e só quando a plataforma tem o recurso habilitado. Você reconhece pelo workflow_type:

{
  "order_number": "ORD-000789",       // identificador público do pedido
  "workflow_type": "backorder",       // ← sob encomenda (label "Sob Encomenda")
  "status": "awaiting_restock",       // ← a espera: "Aguardando Reposição"
  "channel": "direct",                // canal de origem da venda
  "delivery_method": "shipping"       // a entrega segue o eixo normal depois
}

Existe um workflow espelho, pre_order (pré-venda): em vez de aguardar reposição (awaiting_restock → restocked), aguarda a primeira disponibilidade (awaiting_availability → available). A mecânica é idêntica; este guia usa o backorder como referência.

O caminho

stateDiagram-v2 direction LR [*] --> paid paid --> awaiting_restock: automático awaiting_restock --> restocked: estoque abastecido<br/>(automático) restocked --> paid: retomada<br/>(automático) state "preparing → … → delivered" as trilho paid --> trilho

Em palavras: o pagamento confirma (paid), o sistema move sozinho o pedido para awaiting_restock, e ali ele fica, fora das filas de preparação, até a mercadoria chegar. Quando você abastece o estoque do SKU (o mesmo POST /api/products/{id}/stock de sempre: veja Produtos · Estoque), a plataforma detecta a reposição, reserva a quantidade vendida para o pedido, marca o pedido como restocked e o devolve ao trilho padrão a partir de paid, dali ele segue como qualquer entrega (ou retirada, se for o caso).

A reposição reserva, não debita. O saldo recém-chegado sai do disponível e vai para sold_reserved_quantity, mas o quantity físico só cai no despacho. Quem espelha estoque num ERP tem que espelhar o available_quantity, não o quantity: veja Produtos · Estoque.

A fila é por linha, não por pedido. As linhas que esperam o mesmo SKU são atendidas da mais antiga para a mais nova, e cada uma reserva tudo ou nada: quem não couber no saldo que chegou continua esperando. O que espera todas as linhas é a promoção do pedido — a remessa é única, então o pedido só sai de awaiting_restock quando a última linha dele for atendida.

Etapa a etapa

Status	O que significa	Sua ação	Próximo
`paid` (relance)	Pagamento confirmou. Estado de passagem: um job em background move o pedido em seguida.	Nada: não tente `preparing` aqui.	`awaiting_restock` (automático)
`awaiting_restock`	A espera. Pedido aguardando a mercadoria chegar ao seu estoque.	Provisione a mercadoria e, quando ela chegar, dê entrada no estoque (`POST /api/products/{id}/stock` com `increment`).	`restocked` (automático)
`restocked`	Estoque reposto; marco registrado na timeline.	Nada: a quantidade vendida já está reservada e o pedido retoma sozinho.	`paid`, e daí `preparing → …`
`preparing` em diante	Pedido voltou ao fluxo comum.	Igual ao fluxo de entrega: fiscal, etiqueta, envio.

Existe também o destravamento manual, para quando você quer forçar a retomada sem dar entrada no estoque (ex.: a mercadoria chegou mas o ajuste de saldo vem depois). Use as duas rotas de status, como em qualquer outro fluxo:

GET/api/v1/sellers/orders/{id}/possible-statuses

POST/api/v1/sellers/orders/{id}/status

POST /api/v1/sellers/orders/ORD-000789/status
Content-Type: application/json

{ "status": "restocked" }

Mesmo no manual, a retomada completa acontece: o pedido passa por restocked, o saldo é reservado para ele e volta pra paid.

Retomada manual sem saldo não reserva nada, e o pedido anda mesmo assim. Se você forçar restocked antes de dar entrada no estoque, o pedido chega em paid normalmente, mas a linha sem saldo continua em stock_status: awaiting_restock — a resposta é 200 e nada no corpo do pedido avisa. O único sinal é is_blocking_stock: true naquela linha. Confira items[] depois de forçar a retomada, ou o furo só aparece no despacho.

Como a integração percebe a espera

Quatro sinais, do mais direto ao mais sutil:

1. O campo status é awaiting_restock. Com status_label "Aguardando Reposição". O pedido não vai aparecer nos seus filtros de fila de preparação (?status=paid,preparing), e isso é correto, não é um pedido perdido.

2. A listagem filtra por workflow. Sua fila de provisionamento é:

GET /api/v1/sellers/orders?workflow=backorder&status=awaiting_restock&sort=created_at

(Ordenado do mais antigo para o mais novo: quem espera há mais tempo provisiona primeiro.)

3. O possible-statuses só oferece duas saídas. Em awaiting_restock, as next_actions são mark-restocked (→ restocked) e cancel (→ cancelled). Nada de preparing: se sua integração renderiza um botão por ação, ela já mostra o fluxo certo sem código especial.

{
  "data": {
    "current_status": "awaiting_restock",
    "workflow_type": "backorder",
    "next_actions": [
      { "action": "mark-restocked", "target_status": "restocked", "label": "Reposto", "payload_schema": null },
      { "action": "cancel", "target_status": "cancelled", "label": "Cancelado", "payload_schema": { "type": "object", "required": ["reason"], "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 500 } } } }
    ]
  }
}

4. A timeline conta a história.GET /orders/{id}/events registra o paid → awaiting_restock com autoria do sistema e, na retomada, o awaiting_restock → restocked → paid, com autoria "Sistema (reposição de estoque)" quando veio do abastecimento, ou a sua quando foi forçada manualmente. Cada linha que passa a travar (ou deixa de travar) o pedido também entra na timeline, como item_stock_status_changed.

5. As linhas dizem o que falta.status é do pedido inteiro; o que falta é por linha. Cada item de items[] traz stock_status, stock_status_label e is_blocking_stock — veja Estoque por linha. Num pedido misto, é o único jeito de saber qual SKU segura a remessa:

GET /api/v1/sellers/orders?blocking_stock=1

Pontos de atenção

O pulo para awaiting_restock é assíncrono. Logo após o webhook de pagamento, o pedido pode aparecer por alguns instantes como paid, e nessa janela curta o possible-statuses ainda oferece preparing, porque o sistema não estacionou o pedido. Num pedido workflow_type=backorder, não dispare a esteira de preparação no primeiro paid. Espere o estado assentar em awaiting_restock; o produto, por definição, ainda não está no estoque.

Os dados do comprador ficam visíveis durante a espera. O pedido sob encomenda só estaciona depois do pagamento confirmado, então customer_data_released vem true e o PII do comprador (nome, endereço, documento) aparece normalmente em awaiting_restock e restocked, você pode planejar a entrega enquanto provisiona. O que continua bloqueado nesse período é a emissão fiscal (abaixo).

A reserva acontece na retomada; o débito, no despacho. A venda sob encomenda nasce sem reservar saldo, porque não havia saldo. Quando a mercadoria chega, a quantidade vendida é reservada para a linha (stock_status vira sold_reserved) e sai do disponível. O quantity físico só cai quando o pedido é despachado, e aí a linha vira committed. Por isso a entrada de estoque vem primeiro: sem ela não há o que reservar.

A reposição deve ser verdade. O cliente já pagou e vê a linha do tempo do pedido ("Reposto" é um marco visível). Forçar a retomada sem ter a mercadoria só transfere o atraso para a etapa de preparação, onde os prazos de SLA da plataforma passam a contar.

Pedido misto

Nem todo pedido que passa por aqui está inteiro sem estoque. Uma venda direta em que só uma das linhas ficou sem saldo entra no trilho de sob encomenda por causa dessa linha — as demais ficam reservadas normalmente, e a remessa espera a última.

Você reconhece pela combinação de type e workflow_type:

{
  "order_number": "ORD-000791",
  "type": "standard",              // ← continua padrão: a venda não nasceu sob encomenda
  "workflow_type": "backorder",    // ← mas anda por este trilho
  "status": "awaiting_restock",
  "items": [
    { "product_id": "01K8PROD0002TENISAZUL", "stock_status": "sold_reserved",    "is_blocking_stock": false },
    { "product_id": "01K8PROD0003CABOHDMI",  "stock_status": "awaiting_restock", "is_blocking_stock": true }
  ]
}

Duas armadilhas:

?type=backorder não acha esses pedidos. Quem mudou foi o workflow_type, não o type. Filtre por ?workflow=backorder.
O saldo das linhas atendidas já está preso. Elas contam em sold_reserved_quantity desde antes do pedido retomar, e não estão mais disponíveis pra vender. Um ERP que só olha status=awaiting_restock e conclui "nada deste pedido consome estoque" erra.

Cancelamento

Aqui o seller tem mais janela que nos outros fluxos: a espera inteira é pré-operacional, então cancelled está disponível tanto em awaiting_restock quanto em restocked, útil quando o fornecedor falha de vez. reason é obrigatório (mínimo 10 caracteres):

{
  "status": "cancelled",
  "data": { "reason": "Produto descontinuado pelo fornecedor, sem previsão de reposição." }
}

O estorno ao cliente segue o pipeline normal de cancelamento. A janela fecha no lugar de sempre: quando o pedido retoma o trilho e entra em preparing, cancelar vira assunto da operação da plataforma.

Emissão fiscal

Nada durante a espera.awaiting_restock e restocked (e o paid de passagem) estão fora da janela fiscal. A API de emissão recusa com 422. A elegibilidade abre quando o pedido retoma o trilho e chega em preparing, exatamente como no fluxo de entrega. A partir daí: emitir documento, gerar etiqueta, despachar.