Cancelar e excluir pedido

Cancela um pedido (o caminho normal) ou o remove de forma permanente (exceção, irreversível).

Pedido é um registro fiscal e financeiro. Por isso a plataforma tem dois níveis de "apagar":

Cancelar (DELETE /orders/{id}): o pedido continua existindo, com o status cancelado, e o estoque dos itens volta. É o que você quer em quase todos os casos: o cliente desistiu, o pagamento não saiu, o ERP recusou.
Excluir permanentemente (DELETE /orders/{id}/permanent): remove o pedido, os sub-pedidos e os registros ligados. Não há como desfazer. Existe para limpar pedidos de teste e dados criados por engano.

DELETE/api/v1/admin/orders/{id}Admin

Cancela um pedido

Cancela o pedido (status cancelled). Exige manage_orders. Só pedidos em pending, processing, paid, on_hold ou failed podem ser cancelados por aqui. Ao cancelar um pedido pago, a plataforma solicita o estorno ao gateway antes de concluir; se o estorno falhar, o pedido não é cancelado. O estoque dos itens é devolvido. O corpo é opcional.

Path parameters

iduuidobrigatório

Id do pedido.

Corpo da requisição (opcional)

reasonstring

Motivo do cancelamento, gravado no histórico. Se omitido, o histórico registra o código cancelled_by_admin.

DELETE/api/v1/admin/orders/{id}/permanentAdmin

Exclui um pedido definitivamente

Remove o pedido e tudo o que depende dele (sub-pedidos, itens, endereços, histórico), depois de devolver o estoque. Exige manage_orders. Irreversível. Funciona em qualquer status, inclusive cancelado, e apagar um pedido pai remove também os sub-pedidos.

Recusa o pedido que tem uma contestação (disputa) aberta: resolva-a primeiro.

Path parameters

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

# Cancelar, com motivo
curl -X DELETE "$BASE_URL/api/v1/admin/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Cliente desistiu da compra"}'

# Excluir de vez (irreversível)
curl -X DELETE "$BASE_URL/api/v1/admin/orders/$ORDER_ID/permanent" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedido cancelado

json

{
  "message": "order cancelled successfully",
  "order": {
    "id": "0b79d747-0343-415f-820a-4ccce9ca69df",
    "order_number": "PEDIDO-20261011-0004",
    "total": 8200,
    "status": "I",
    "status_text": "cancelled",
    "updated_at": "2026-10-11T20:21:05.114Z"
  }
}

200Exclusão permanente

json

{ "deleted": true, "permanent": true }

Campos da resposta

messagestring

(Cancelamento) Confirmação.

orderobject

(Cancelamento) O pedido já com o status cancelled (campos de Consultar pedido).

deletedboolean

(Exclusão permanente) true quando o pedido foi removido.

permanentboolean

(Exclusão permanente) Sempre true.

Erros

Status	Quando	Corpo
400	Corpo com `reason` de tipo errado	`{"error":"invalid request body","detail":"..."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão (`manage_orders`)	`{"error":"insufficient privileges","required":"manage_orders"}`
404	O pedido não existe	`{"error":"order not found"}`
409	Status que não pode mais ser cancelado: `shipped`, `delivered`, `completed`, `cancelled`, `refunded`. Ou transição recusada	`{"error":"cannot delete order in status 'shipped'","detail":"only orders in pending, processing, paid, on_hold, or failed status can be deleted"}`
409	(permanente) o pedido tem contestação aberta	`{"error":"order_has_disputes","detail":"this order has an open dispute; disputes outlive the order and must be resolved first"}`
423	O pedido é de um mês contábil já fechado	`{"error":"period_closed","competence":"2026-07"}`
500	Falha ao estornar no gateway ou falha interna	`{"error":"failed to cancel order","detail":"..."}`

Veja também

Cancelar e excluir pedido

Cancela um pedido (o caminho normal) ou o remove de forma permanente (exceção, irreversível).

Pedido é um registro fiscal e financeiro. Por isso a plataforma tem dois níveis de "apagar":

Cancelar (DELETE /orders/{id}): o pedido continua existindo, com o status cancelado, e o estoque dos itens volta. É o que você quer em quase todos os casos: o cliente desistiu, o pagamento não saiu, o ERP recusou.
Excluir permanentemente (DELETE /orders/{id}/permanent): remove o pedido, os sub-pedidos e os registros ligados. Não há como desfazer. Existe para limpar pedidos de teste e dados criados por engano.

DELETE/api/v1/admin/orders/{id}Admin

Cancela um pedido

Path parameters

iduuidobrigatório

Id do pedido.

Corpo da requisição (opcional)

reasonstring

Motivo do cancelamento, gravado no histórico. Se omitido, o histórico registra o código cancelled_by_admin.

DELETE/api/v1/admin/orders/{id}/permanentAdmin

Exclui um pedido definitivamente

Recusa o pedido que tem uma contestação (disputa) aberta: resolva-a primeiro.

Path parameters

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

# Cancelar, com motivo
curl -X DELETE "$BASE_URL/api/v1/admin/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Cliente desistiu da compra"}'

# Excluir de vez (irreversível)
curl -X DELETE "$BASE_URL/api/v1/admin/orders/$ORDER_ID/permanent" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedido cancelado

json

{
  "message": "order cancelled successfully",
  "order": {
    "id": "0b79d747-0343-415f-820a-4ccce9ca69df",
    "order_number": "PEDIDO-20261011-0004",
    "total": 8200,
    "status": "I",
    "status_text": "cancelled",
    "updated_at": "2026-10-11T20:21:05.114Z"
  }
}

200Exclusão permanente

json

{ "deleted": true, "permanent": true }

Campos da resposta

messagestring

(Cancelamento) Confirmação.

orderobject

(Cancelamento) O pedido já com o status cancelled (campos de Consultar pedido).

deletedboolean

(Exclusão permanente) true quando o pedido foi removido.

permanentboolean

(Exclusão permanente) Sempre true.

Erros

Status	Quando	Corpo
400	Corpo com `reason` de tipo errado	`{"error":"invalid request body","detail":"..."}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão (`manage_orders`)	`{"error":"insufficient privileges","required":"manage_orders"}`
404	O pedido não existe	`{"error":"order not found"}`
409	Status que não pode mais ser cancelado: `shipped`, `delivered`, `completed`, `cancelled`, `refunded`. Ou transição recusada	`{"error":"cannot delete order in status 'shipped'","detail":"only orders in pending, processing, paid, on_hold, or failed status can be deleted"}`
409	(permanente) o pedido tem contestação aberta	`{"error":"order_has_disputes","detail":"this order has an open dispute; disputes outlive the order and must be resolved first"}`
423	O pedido é de um mês contábil já fechado	`{"error":"period_closed","competence":"2026-07"}`
500	Falha ao estornar no gateway ou falha interna	`{"error":"failed to cancel order","detail":"..."}`