API atual/Referência completa/Pedidos e conta do cliente

Cancelar pedido

Consulta se o cliente pode cancelar e então cancela na hora ou solicita o cancelamento.

O cliente não cancela o pedido por conta própria em toda loja: a loja decide se aceita, até quando (por status e por dias desde a compra) e se o cancelamento é automático ou passa por análise do seller. Por isso o fluxo tem duas chamadas: primeiro pergunte se dá (GET .../cancellation), e só então peça (POST .../cancel).

GET/api/v1/storefront/orders/{id}/cancellationCliente

Consulta se o pedido pode ser cancelado pelo cliente

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/cancellation" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Situação do cancelamento

json

{
  "enabled": true,
  "eligible": true,
  "mode": "automatic",
  "explanation": "request qualifies for automatic cancellation",
  "auto_by_status": true,
  "auto_by_days": true
}

Campos da resposta

enabledboolean

false quando a loja não aceita pedido de cancelamento do cliente. Esconda o botão.

eligibleboolean

true quando este pedido, agora, pode ser cancelado ou ter o cancelamento solicitado.

modestring

automaticreview

Só quando eligible é true ou há um pedido em curso: automatic (cancela na hora) ou review (vira uma solicitação que o seller ou a loja analisa).

explanationstring

Motivo em inglês, para log e depuração: customer cancellation requests are disabled, order is already in a terminal payment or cancellation state, request qualifies for automatic cancellation, request will be sent to the seller or platform administrator for review, automatic cancellation period or status limit has expired, a cancellation request is already awaiting review, the cancellation request has already been approved, the cancellation request was rejected; contact the seller if you have questions ou the order is already cancelled or refunded; the request is closed. Não exiba o texto cru ao cliente; use enabled, eligible e mode.

requestobject

O pedido de cancelamento em curso ou já decidido, quando existe (formato abaixo).

auto_by_statusboolean

true quando o status atual do pedido ainda está dentro do limite do cancelamento automático.

auto_by_daysboolean

true quando ainda está dentro do prazo em dias desde a compra.

status_tracestring

Diagnóstico de como a regra de status decidiu. Pode faltar; é só para suporte.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	O id não existe ou o pedido não é seu (a API nunca diz qual dos dois)	`{"error":"order not found"}`
500	Falha ao avaliar a regra	`{"error":"failed to evaluate cancellation"}`

POST/api/v1/storefront/orders/{id}/cancelCliente

Cancela o pedido ou solicita o cancelamento

Revalida a regra no servidor (não confie no GET anterior para segurança) e então age conforme o mode: em automatic cancela na hora, devolve o estoque e, se o pagamento já tinha sido capturado e a loja estiver configurada para isso, dispara o estorno; em review registra uma solicitação e avisa o seller por e-mail. O cliente recebe um e-mail de confirmação do pedido de cancelamento nos dois casos.

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Corpo da requisição

reasonstring

Motivo informado pelo cliente. Opcional; o corpo pode ser vazio.

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Comprei sem querer."
}'

200Cancelado na hora (automatic)

json

{
  "message": "order cancelled successfully",
  "request": {
    "id": "0d7c3b6e-2c1b-4d0a-9c53-6f0b2a4d9e10",
    "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_number": "PEDIDO-20261011-0009",
    "status": "auto_approved",
    "processing_mode": "automatic",
    "request_reason": "Comprei sem querer.",
    "requested_by": "264a70c1-9c69-458d-ac73-838543f87da2",
    "previous_order_status": "O",
    "resulting_order_status": "I",
    "refund_requested": true,
    "refund_completed": false,
    "created_at": "2026-10-11T21:10:00Z",
    "updated_at": "2026-10-11T21:10:00Z"
  }
}

202Enviado para análise (review)

json

{
  "message": "cancellation request submitted for review",
  "request": {
    "id": "0d7c3b6e-2c1b-4d0a-9c53-6f0b2a4d9e10",
    "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_number": "PEDIDO-20261011-0009",
    "status": "pending",
    "processing_mode": "review",
    "request_reason": "Comprei sem querer.",
    "requested_by": "264a70c1-9c69-458d-ac73-838543f87da2",
    "previous_order_status": "O",
    "resulting_order_status": "I",
    "refund_requested": true,
    "refund_completed": false,
    "created_at": "2026-10-11T21:10:00Z",
    "updated_at": "2026-10-11T21:10:00Z"
  },
  "cancellation": {
    "enabled": true,
    "eligible": false,
    "mode": "review",
    "explanation": "a cancellation request is already awaiting review"
  }
}

Campos da resposta

messagestring

Texto em inglês do resultado.

request.iduuid

Id da solicitação de cancelamento.

request.statusstring

pendingprocessingapprovedauto_approvedrejectedclosed

pending e processing (em análise), approved e auto_approved (aprovado), rejected (recusado) ou closed (o pedido já tinha sido cancelado ou reembolsado por outra via).

request.processing_modestring

automaticreview

automatic ou review.

request.request_reasonstring

Motivo informado pelo cliente. decision_reason traz a justificativa de quem decidiu.

request.previous_order_statusstring

Letra do status que o pedido tinha ao pedir. Se o pedido for recusado, ele volta para esse status.

request.refund_requestedboolean

true quando há dinheiro a devolver. refund_completed indica se já foi devolvido; refund_amount (centavos), refund_reference e refund_confirmed_at comprovam o estorno.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	O id não existe ou o pedido não é seu (a API nunca diz qual dos dois)	`{"error":"order not found"}`
409	Não elegível agora (desligado, prazo vencido, já cancelado, já em análise)	`{"error":"cancellation_not_available","detail":"customer cancellation requests are disabled","cancellation":{...}}`
409	Já existe uma solicitação pendente	`{"error":"cancellation request already pending"}`
502	O estorno do pagamento ou a mudança de status falhou. Nada foi cancelado.	`{"error":"order cannot be cancelled right now","detail":"payment refund or order transition could not be processed; no cancellation was applied"}`
500	Falha ao carregar a política ou gravar a solicitação	`{"error":"failed to create cancellation request"}`

Veja também

Cancelar pedido

Consulta se o cliente pode cancelar e então cancela na hora ou solicita o cancelamento.

GET/api/v1/storefront/orders/{id}/cancellationCliente

Consulta se o pedido pode ser cancelado pelo cliente

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/cancellation" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Situação do cancelamento

json

{
  "enabled": true,
  "eligible": true,
  "mode": "automatic",
  "explanation": "request qualifies for automatic cancellation",
  "auto_by_status": true,
  "auto_by_days": true
}

Campos da resposta

enabledboolean

false quando a loja não aceita pedido de cancelamento do cliente. Esconda o botão.

eligibleboolean

true quando este pedido, agora, pode ser cancelado ou ter o cancelamento solicitado.

modestring

automaticreview

Só quando eligible é true ou há um pedido em curso: automatic (cancela na hora) ou review (vira uma solicitação que o seller ou a loja analisa).

explanationstring

requestobject

O pedido de cancelamento em curso ou já decidido, quando existe (formato abaixo).

auto_by_statusboolean

true quando o status atual do pedido ainda está dentro do limite do cancelamento automático.

auto_by_daysboolean

true quando ainda está dentro do prazo em dias desde a compra.

status_tracestring

Diagnóstico de como a regra de status decidiu. Pode faltar; é só para suporte.

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	O id não existe ou o pedido não é seu (a API nunca diz qual dos dois)	`{"error":"order not found"}`
500	Falha ao avaliar a regra	`{"error":"failed to evaluate cancellation"}`

POST/api/v1/storefront/orders/{id}/cancelCliente

Cancela o pedido ou solicita o cancelamento

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Corpo da requisição

reasonstring

Motivo informado pelo cliente. Opcional; o corpo pode ser vazio.

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Comprei sem querer."
}'

200Cancelado na hora (automatic)

json

{
  "message": "order cancelled successfully",
  "request": {
    "id": "0d7c3b6e-2c1b-4d0a-9c53-6f0b2a4d9e10",
    "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_number": "PEDIDO-20261011-0009",
    "status": "auto_approved",
    "processing_mode": "automatic",
    "request_reason": "Comprei sem querer.",
    "requested_by": "264a70c1-9c69-458d-ac73-838543f87da2",
    "previous_order_status": "O",
    "resulting_order_status": "I",
    "refund_requested": true,
    "refund_completed": false,
    "created_at": "2026-10-11T21:10:00Z",
    "updated_at": "2026-10-11T21:10:00Z"
  }
}

202Enviado para análise (review)

json

{
  "message": "cancellation request submitted for review",
  "request": {
    "id": "0d7c3b6e-2c1b-4d0a-9c53-6f0b2a4d9e10",
    "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_number": "PEDIDO-20261011-0009",
    "status": "pending",
    "processing_mode": "review",
    "request_reason": "Comprei sem querer.",
    "requested_by": "264a70c1-9c69-458d-ac73-838543f87da2",
    "previous_order_status": "O",
    "resulting_order_status": "I",
    "refund_requested": true,
    "refund_completed": false,
    "created_at": "2026-10-11T21:10:00Z",
    "updated_at": "2026-10-11T21:10:00Z"
  },
  "cancellation": {
    "enabled": true,
    "eligible": false,
    "mode": "review",
    "explanation": "a cancellation request is already awaiting review"
  }
}

Campos da resposta

messagestring

Texto em inglês do resultado.

request.iduuid

Id da solicitação de cancelamento.

request.statusstring

pendingprocessingapprovedauto_approvedrejectedclosed

pending e processing (em análise), approved e auto_approved (aprovado), rejected (recusado) ou closed (o pedido já tinha sido cancelado ou reembolsado por outra via).

request.processing_modestring

automaticreview

automatic ou review.

request.request_reasonstring

Motivo informado pelo cliente. decision_reason traz a justificativa de quem decidiu.

request.previous_order_statusstring

Letra do status que o pedido tinha ao pedir. Se o pedido for recusado, ele volta para esse status.

request.refund_requestedboolean

true quando há dinheiro a devolver. refund_completed indica se já foi devolvido; refund_amount (centavos), refund_reference e refund_confirmed_at comprovam o estorno.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	O id não existe ou o pedido não é seu (a API nunca diz qual dos dois)	`{"error":"order not found"}`
409	Não elegível agora (desligado, prazo vencido, já cancelado, já em análise)	`{"error":"cancellation_not_available","detail":"customer cancellation requests are disabled","cancellation":{...}}`
409	Já existe uma solicitação pendente	`{"error":"cancellation request already pending"}`
502	O estorno do pagamento ou a mudança de status falhou. Nada foi cancelado.	`{"error":"order cannot be cancelled right now","detail":"payment refund or order transition could not be processed; no cancellation was applied"}`
500	Falha ao carregar a política ou gravar a solicitação	`{"error":"failed to create cancellation request"}`