Alterar o status
Move o pedido de um status para outro (pago, enviado, entregue, cancelado...), consulta os destinos permitidos e força uma mudança fora do fluxo.
O status diz em que etapa o pedido está. Mudá-lo é a operação mais importante do ciclo de vida: ela baixa ou devolve estoque, dispara e-mails ao cliente, estorna o pagamento em um cancelamento, atualiza os relatórios e grava uma linha no histórico. Esta página reúne as quatro rotas que mexem no status.
A lista de status existentes, com a letra e o significado de cada um, está na home da seção e em Status de pedido. Cada loja tem o seu cadastro de status: antes de integrar, leia o da loja com GET /api/v1/admin/order-statuses.
/api/v1/admin/orders/{id}/statusAdminAltera o status de um pedido
Exige o privilégio manage_orders. O corpo aceita o código do status (shipped) ou a letra do cadastro da loja (S).
Regras da plataforma:
- Entre os status padrão da plataforma, só valem as transições da tabela abaixo. Pular etapas (pendente direto para enviado) ou sair de um estado final (reembolsado) é recusado com 400
invalid_transition. - Pedido já enviado, entregue ou concluído não volta para pendente, processando, em espera ou pago.
- Status personalizados da loja (criados em Status de pedido) e transições entre eles não têm restrição, além de o destino existir no cadastro.
- Ao mover um pedido pago para cancelado ou reembolsado, a plataforma tenta estornar no gateway antes de concluir. Se o estorno falhar, o status não muda.
- Cancelado, reembolsado e falho devolvem o estoque. Sair desses status para um status ativo baixa o estoque de novo.
- Ao enviar e entregar,
shipped_atedelivered_atsão preenchidos. - Se o pedido é sub-pedido, o status do pedido pai é recalculado (veja Sub-pedidos).
Path parameters
iduuidobrigatórioCorpo da requisição
statusstringobrigatórioprocessing, shipped, cancelled...) ou letra (P, S, I...).notesstringpublic_notestringexpected_updated_atstringupdated_at que você leu. Se outro usuário alterou o pedido depois disso, a resposta é 409 stale_order_update e nada é gravado./api/v1/admin/orders/{id}/allowed-transitionsAdminStatus para os quais este pedido pode ir
Devolve os status para os quais o pedido pode ir agora, segundo as regras acima. Use antes de montar um botão ou um menu de "mudar status", em vez de reescrever a tabela no seu código. Exige view_orders ou manage_orders.
Quando a loja usa o fluxo de status personalizado (recurso opcional), a resposta vem da matriz configurada para o administrador e traz também flow_active: true e a lista targets com nomes e cores.
Path parameters
iduuidobrigatório/api/v1/admin/orders/{id}/force-statusAdminForça uma mudança de status fora do fluxo da loja
Muda o status ignorando a matriz de transições configurada pela loja, com um motivo obrigatório que fica no histórico e no log de atividades. As regras da plataforma (estorno, estoque, estados finais) continuam valendo. Só existe quando a loja ativou o recurso de fluxo de status, e exige os privilégios manage_orders e force_order_transition. Sem o recurso, responde 403 module_disabled.
Path parameters
iduuidobrigatórioCorpo da requisição
statusstringobrigatórioreasonstringobrigatórioreason_required./api/v1/admin/orders/{id}/sync-statusAdminRecalcula o status de um pedido pai a partir dos subpedidos
Recalcula o status de um pedido pai a partir dos seus sub-pedidos e devolve o pedido. Normalmente isso já acontece sozinho a cada mudança de um sub-pedido; use a rota para corrigir um pedido pai que ficou fora de sincronia. Exige manage_orders.
Path parameters
iduuidobrigatórioTransições permitidas (status padrão da plataforma)
| De | Para |
|---|---|
pending (O) | processing, on_hold, paid, cancelled, failed |
processing (P) | pending, on_hold, paid, shipped, cancelled, refunded, chargeback |
on_hold (H) | pending, processing, cancelled |
failed (F) | pending, processing, cancelled |
paid (A) | shipped, cancelled, refunded, chargeback |
shipped (S) | delivered, on_hold, chargeback |
delivered (C) | completed, refunded, chargeback |
completed (K) | chargeback |
cancelled (I) | pending, processing, on_hold (reabrir um pedido cancelado) |
refunded (R) | nenhuma (estado final) |
chargeback (Z) | refunded, cancelled |
Essa tabela vale para quem usa o alfabeto padrão. Em uma loja que renomeou ou reatribuiu letras, um status que deixa de ser reconhecido como o da plataforma passa a ser tratado como personalizado, sem restrição. Por isso, confie em allowed-transitions e não em uma cópia local.
Exemplo de requisição
# Marcar como enviado
curl -X PUT "$BASE_URL/api/v1/admin/orders/$ORDER_ID/status" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"status":"shipped","notes":"Despachado pela transportadora"}'Resposta
{
"id": "2b4bd680-b717-4295-a2be-8b5c6771a4d0",
"order_number": "PEDIDO-20261011-0001-V1",
"parent_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
"subtotal": 167895,
"shipping_total": 1759,
"total": 169654,
"payment_status": "pending",
"status": "S",
"status_text": "shipped",
"shipped_at": "2026-10-11T20:16:39.661262Z",
"updated_at": "2026-10-11T20:19:31.828444Z"
}{
"transitions": [
{ "code": "P", "label_key": "processing" },
{ "code": "H", "label_key": "on_hold" },
{ "code": "A", "label_key": "paid" },
{ "code": "I", "label_key": "cancelled" },
{ "code": "F", "label_key": "failed" }
]
}{
"message": "parent order status synced from sub-orders",
"order": { "order": { "id": "e148b6aa-d495-4b89-92ab-f38b5979a43f", "status": "P", "status_text": "processing" }, "items": [], "addresses": [], "status_history": [] }
}Campos da resposta
statusstringstatus_textstringtransitionsarraycode é a letra para enviar de volta; label_key é o código do status.flow_activebooleantrue quando a loja usa o fluxo de status personalizado.targetsarraycode, letter_code, name, name_pt, color e requires_reason (se a mudança exige justificativa).messagestringEfeitos da mudança de status
| Ao entrar em... | O que acontece |
|---|---|
cancelled, refunded, failed | O estoque dos itens é devolvido. Pedido pago tem o estorno solicitado ao gateway antes. |
shipped | shipped_at é preenchido; o cliente pode receber o e-mail de envio. |
delivered | delivered_at é preenchido. |
chargeback | Emite o evento de contestação de pagamento (chargeback) para as integrações. |
| qualquer status | Uma linha entra no histórico (old_status, new_status, notes, quem alterou) e o evento de mudança de status é emitido, para e-mails, comissões e integrações. |
Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | Falta status | {"error":"status is required"} |
| 400 | Transição inválida, ou status que não existe no cadastro da loja | {"error":"invalid_transition","detail":"invalid_transition: from delivered to P (post-shipment orders cannot revert to a pre-shipment status via drag; use a return/refund flow)"} |
| 400 | Fluxo de status da loja não permite a transição | {"error":"transition_not_in_flow","detail":"..."} |
| 401 | Sem credenciais ou token expirado | {"error":"invalid or expired token"} |
| 403 | Sem manage_orders (e force_order_transition no force-status); transição proibida para o seu papel; recurso de fluxo desligado | {"error":"insufficient privileges","required":"manage_orders"}, {"error":"transition_not_allowed_for_actor"} ou {"error":"module_disabled","module":"order-status-flow"} |
| 404 | O pedido não existe | {"error":"order not found"} |
| 409 | Outro usuário alterou o pedido (expected_updated_at); ou estorno em andamento | {"error":"stale_order_update"} ou {"error":"refund_in_progress","detail":"Estorno em andamento: este pedido não pode mudar de status até o estorno terminar."} |
| 422 | Fluxo da loja exige justificativa; status aposentado | {"error":"reason_required"} ou {"error":"status_retired"} |
| 423 | Cancelar/reembolsar pedido de um mês contábil já fechado | {"error":"period_closed","competence":"2026-07"} |