VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Pedidos

Status de pedido

Lista, consulta, cria, altera e remove os status que um pedido pode ter, com a letra, a cor e o comportamento de cada um.

Cada loja tem o seu cadastro de status de pedido. Ele define quais status existem, como se chamam, qual letra de um caractere cada um grava no pedido e o que acontece ao entrar nele (avisar o cliente, mexer no estoque). A plataforma já traz um conjunto padrão; a loja pode renomear, esconder, reordenar e acrescentar os dela (por exemplo "Aguardando retirada" ou "Nota fiscal emitida").

Por isso, nunca copie a lista de status para o seu código. Leia o cadastro da loja (GET /order-statuses) e use o code e a letter_code que ele devolve.

Os status padrão

codeLetraSignificado
pendingOPedido recebido, aguardando pagamento ou confirmação.
processingPEm preparação. É para onde a maioria dos gateways leva um pedido cujo pagamento foi aprovado.
paidAPagamento confirmado (status opcional; muitos fluxos passam direto de pending para processing).
on_holdHEm espera.
failedFPagamento recusado ou falho. O estoque é devolvido.
shippedSEnviado.
deliveredCEntregue.
completedKConcluído (pós-entrega, prazo de arrependimento encerrado).
cancelledICancelado. O estoque é devolvido. Pode ser reaberto.
refundedRReembolsado. Estado final.
chargebackZContestação de pagamento (estorno por disputa).

As letras e os nomes acima são os da instalação padrão. Uma loja pode reatribuir letras (por exemplo, usar E para "Em espera" em vez de H), e por isso a letra não é a inicial do nome: C é entregue, não cancelado; cancelado é I.

GET/api/v1/admin/order-statusesAdmin

Lista os status de pedido

Lista todos os status da loja, em ordem de position. Exige um destes privilégios: manage_order_statuses, manage_shipping, view_shipping, manage_orders ou view_orders (a lista é lida por telas de pedido e de envio). A mesma lista, sem autenticação, está em GET /api/v1/order-statuses, usada pela vitrine para mostrar o status ao cliente.

GET/api/v1/admin/order-statuses/{code}Admin

Consulta um status de pedido

Um status pelo code. Exige manage_order_statuses.

Path parameters

codestringobrigatório
Código do status (shipped, Paid, docs_teste...). Diferencia maiúsculas de minúsculas, como cadastrado.
POST/api/v1/admin/order-statusesAdmin

Cria um status de pedido

Cria um status. A plataforma escolhe sozinha a próxima letra livre de A a Z (exceto as reservadas N e T), a menos que você mande uma. Também cria o modelo de e-mail do status para o cliente. Exige manage_order_statuses.

Corpo da requisição

codestringobrigatório
Identificador do status: letras, números, _ e -, sem espaços, até 32 caracteres. Não pode ser alterado depois.
namestringobrigatório
Nome em inglês, até 255 caracteres.
name_ptstring
Nome em português, até 255 caracteres.
letter_codestring
Letra de armazenamento, A a Z. Omita para a plataforma escolher. Uma letra já usada por outro status é recusada.
colorstring
Cor do crachá e da coluna do kanban, em hexadecimal (#3b82f6).
positioninteger
Ordem na lista e no kanban.
typestring
Categoria livre, usada para agrupar (initial, processing, shipped, complete, final, cancelled, refunded, general).
notify_customerbooleanpadrão: false
Enviar e-mail ao cliente quando um pedido entra neste status.
notify_vendorbooleanpadrão: false
Avisar o seller.
notify_adminbooleanpadrão: false
Avisar a equipe da loja.
show_in_kanbanbooleanpadrão: true
Mostrar como coluna no quadro de pedidos do painel.
is_activebooleanpadrão: true
Status ativo. Um status desativado deixa de ser aceito como destino (recurso de fluxo de status).
visible_to_customerbooleanpadrão: true
O cliente enxerga este status.
visible_to_vendorbooleanpadrão: true
O seller enxerga este status.
flow_stagestring
maintechnicalexception
Etapa do fluxo (recurso de fluxo de status): main aparece no passo a passo do cliente.
paramsobject
Comportamento do status, como mapa de texto: inventory (D baixa o estoque ao entrar, I devolve), appearance_type (I gera fatura, C nota de crédito), remove_cc_info (Y apaga dados de cartão), repay (Y permite ao cliente pagar de novo), calculate_for_payouts (Y conta para o repasse ao seller). Valor vazio remove o parâmetro.
descriptionsobject
Nome, descrição e assunto do e-mail por idioma, indexados pelo código do idioma da loja (pt-BR). Cada valor tem name, description e email_subject.
PUT/api/v1/admin/order-statuses/{code}Admin

Atualiza um status de pedido

Altera só os campos enviados. O code não muda: enviar um code diferente do da URL causa 400 code_immutable. Para trocar o nome, mude name/name_pt. Exige manage_order_statuses. Aceita name, name_pt, color, position, type, notify_customer, notify_vendor, notify_admin, show_in_kanban, is_active, visible_to_customer, visible_to_vendor, flow_stage e params (os mesmos significados de cima; em params, um valor vazio remove o parâmetro e os não citados ficam como estão).

Path parameters

codestringobrigatório
Código do status.
DELETE/api/v1/admin/order-statuses/{code}Admin

Exclui um status de pedido

Remove um status. Se algum pedido ainda está nele, a remoção é recusada (409). Para mover os pedidos e remover de uma vez, informe reassign_to (na query ou no corpo {"reassign_to":"processing"}): todos os pedidos do status vão para o destino em uma transação e o status é removido. O histórico antigo não é reescrito. Exige manage_order_statuses.

Path parameters

codestringobrigatório
Código do status.

Query parameters

reassign_tostring
Código do status que receberá os pedidos. Precisa existir e ser diferente do que está sendo removido.

Exemplo de requisição

bash
# Ler o cadastro da loja
curl "$BASE_URL/api/v1/admin/order-statuses" -H "Authorization: Bearer $TOKEN"

# Criar um status
curl -X POST "$BASE_URL/api/v1/admin/order-statuses" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "code": "awaiting_pickup",
    "name": "Awaiting Pickup",
    "name_pt": "Aguardando retirada",
    "color": "#3b82f6",
    "position": 55,
    "notify_customer": true,
    "params": { "inventory": "D" }
  }'

# Remover, movendo os pedidos para "processing"
curl -X DELETE "$BASE_URL/api/v1/admin/order-statuses/awaiting_pickup?reassign_to=processing" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Lista de status
json
{
  "total": 2,
  "statuses": [
    {
      "code": "pending",
      "letter_code": "O",
      "name": "Pendente",
      "name_pt": "Pendente",
      "color": "#f59e0b",
      "position": 20,
      "type": "initial",
      "notify_customer": false,
      "notify_vendor": false,
      "notify_admin": false,
      "show_in_kanban": true,
      "is_active": true,
      "visible_to_customer": true,
      "visible_to_vendor": true,
      "flow_stage": "",
      "params": { "repay": "Y" },
      "effective_inventory": "",
      "inventory_locked_by_platform": false,
      "created_at": "2026-03-06T10:07:44.511287Z",
      "updated_at": "2026-07-19T01:51:30.652512Z"
    },
    {
      "code": "failed",
      "letter_code": "F",
      "name": "Failed",
      "name_pt": "Pagamento Recusado",
      "color": "#dc2626",
      "position": 45,
      "type": "cancelled",
      "notify_customer": false,
      "notify_vendor": false,
      "notify_admin": false,
      "show_in_kanban": true,
      "is_active": true,
      "visible_to_customer": true,
      "visible_to_vendor": true,
      "flow_stage": "",
      "effective_inventory": "I",
      "inventory_locked_by_platform": true,
      "created_at": "2026-09-11T11:36:32.996113Z",
      "updated_at": "2026-09-11T11:36:32.996113Z"
    }
  ]
}
201Status criado
json
{
  "code": "awaiting_pickup",
  "letter_code": "J",
  "name": "Awaiting Pickup",
  "name_pt": "Aguardando retirada",
  "color": "#3b82f6",
  "position": 55,
  "type": "",
  "notify_customer": true,
  "notify_vendor": false,
  "notify_admin": false,
  "show_in_kanban": true,
  "is_active": true,
  "visible_to_customer": true,
  "visible_to_vendor": true,
  "flow_stage": "",
  "params": { "inventory": "D" },
  "effective_inventory": "",
  "inventory_locked_by_platform": false,
  "created_at": "2026-10-11T20:33:45.852888Z",
  "updated_at": "2026-10-11T20:33:45.852888Z"
}
200Status removido
json
{ "message": "order status reassigned and deleted", "reassigned_to": "processing" }

Campos da resposta

codestring
Identificador estável do status. Use-o em filtros (status=processing), em PUT /orders/{id}/status e em reassign_to.
letter_codestring
Letra gravada em orders.status. É o que o pedido devolve no campo status.
namestring
Nome em inglês.
name_ptstring
Nome em português.
colorstring
Cor em hexadecimal.
positioninteger
Ordem de exibição.
typestring
Categoria livre do status.
notify_customerboolean
Envia e-mail ao cliente ao entrar neste status.
show_in_kanbanboolean
Aparece como coluna do kanban.
is_activeboolean
Aceito como destino de mudança.
paramsobject
Comportamentos configurados (ausente quando não há nenhum).
effective_inventorystring
DI
O que o estoque realmente faz ao entrar neste status: D baixa, I devolve, vazio não mexe. Só leitura. A plataforma devolve estoque em cancelado, reembolsado e falho por regra própria, não pelo parâmetro.
inventory_locked_by_platformboolean
true quando o valor acima vem dessa regra e não pode ser mudado por params.
created_atstring
Criação. RFC 3339.
updated_atstring
Última alteração. RFC 3339.
totalinteger
(Lista) Quantidade de status.

Erros

StatusQuandoCorpo
400Corpo inválido; code diferente da URL no PUT; letra já usada; reassign_to igual ao status ou inexistente{"error":"code_immutable","detail":"code is immutable; create a new status if needed"}, {"error":"letter \"S\" is already used by status \"shipped\""}, {"error":"cannot reassign status to itself"}, {"error":"reassign target not found","detail":"..."}
400Já existe um status com o mesmo code{"error":"já existe um registro com esse valor (regra de unicidade/integridade do recurso). Use outro valor ou edite o registro que já existe."}
401Sem token ou token expirado{"error":"invalid or expired token"}
403Sem manage_order_statuses (ou, na lista, sem nenhum dos privilégios aceitos){"error":"insufficient privileges", ...}
404Status inexistente{"error":"order status not found"}
409Remoção de status em uso{"error":"status_in_use","message":"status_in_use: 146 orders reference status pending","code":"pending","in_use_by":146}
409Remoção de status referenciado pelo histórico ou pelo fluxo{"error":"status_referenced","message":"...","code":"...","history":0,"transitions":0}
422Campo inválido na criação{"error":"code may only contain letters, digits, underscore, or hyphen (no spaces)"}, {"error":"name is required"}, {"error":"flow_stage must be ..."}
O código de um status não muda, e a letra não é a inicial

Planeje o code com cuidado: renomear exige criar outro status e mover os pedidos com reassign_to. E não presuma letras: C é "entregue", I é "cancelado" e E pode ser "em espera" em uma loja e "faturado" em outra. A única fonte confiável é o cadastro da loja.

Como mover pedidos de um status que você vai aposentar

Em vez de apagar de uma vez, considere desativar (is_active: false): o status deixa de aceitar novos pedidos, mas o histórico e os relatórios continuam resolvendo o nome. Use DELETE ... ?reassign_to= quando realmente quiser removê-lo do cadastro.

Veja também

  • Alterar o status
  • Traduções dos status
  • Fluxo de status personalizado
Anterior
Dados financeiros e auditoria
Próxima
Traduções dos status
Nesta página
  • Os status padrão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também