VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa/API v2

Devoluções

Lista e consulta devoluções (RMAs) e abre uma devolução em nome do cliente pela equipe da loja.

Uma devolução (RMA, "return merchandise authorization") é o pedido de um cliente para devolver um item comprado: por defeito, por arrependimento ou por erro de envio. Cada devolução passa por uma sequência de situações, do pedido do cliente até o reembolso, e a loja decide a resolução: reembolsar, trocar o produto ou dar crédito na loja.

Use estas operações para sincronizar devoluções com um sistema de logística reversa ou de atendimento. A criação pela v2 é uma ação da equipe (atendimento ou balcão), não do cliente: a devolução nasce ligada ao cliente do pedido.

Situações de uma devolução
requested→approved→item_received→refunded→closed

requested (pedida, aguardando análise), approved (aprovada), item_received (item recebido de volta), refunded (reembolsada), rejected (recusada, depois vai para closed), closed (encerrada) e cancelled (cancelada pelo cliente, só enquanto estava requested).

GET/api/v2/returnsAdmin

Listar devoluções

Da mais nova para a mais antiga. Cada item já traz o número do pedido, o nome e o e-mail do cliente e o nome do produto.

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100.
statusstring
requestedapproveditem_receivedrefundedrejectedclosedcancelled
Situação, pelo nome. Um valor desconhecido não gera erro: é tratado como requested.
customer_iduuid
Somente devoluções deste cliente.
vendor_iduuid
Somente devoluções de itens deste seller.
date_fromstring
Criadas a partir desta data (YYYY-MM-DD).
date_tostring
Criadas até o fim deste dia (YYYY-MM-DD, o dia entra inteiro).
fieldsstring
Chaves a devolver em cada item, separadas por vírgula.
GET/api/v2/returns/{id}Admin

Ler uma devolução

Devolve uma devolução com os mesmos campos da lista.

Parâmetros de caminho

iduuidobrigatório
Id da devolução.
POST/api/v2/returnsAdmin

Abrir uma devolução pela equipe

Cria uma devolução na situação requested para um pedido já pago ou entregue. O cliente é o dono do pedido. O pedido precisa estar pago ou entregue/concluído: pedidos cancelados ou reembolsados não aceitam devolução.

Corpo da requisição

order_iduuidobrigatório
Pedido da devolução.
order_item_iduuid
Item do pedido. Sem ele, a devolução vale para o pedido todo.
reason_iduuid
Id de um motivo cadastrado na loja.
reasonstring
Motivo em texto livre.
resolutionstringpadrão: refund
refundreplacementstore_credit
O que a loja oferece: reembolso, troca ou crédito na loja.
quantityintegerpadrão: 1
Quantidade devolvida. Menor que 1 vira 1.
refund_amountinteger
Valor a reembolsar, em centavos.
restock_warehouse_iduuid
Depósito para onde o item volta ao estoque.
bypass_windowbooleanpadrão: false
Registra na devolução que o prazo de devolução foi dispensado, com o id de quem abriu.

Exemplo de requisição

bash
curl "$BASE_URL/api/v2/returns?status=requested&date_from=2026-10-01&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Abrir uma devolução:

bash
curl -X POST "$BASE_URL/api/v2/returns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "order_item_id": "936266b5-fb89-4a3f-84b6-05155f1c54d9",
  "resolution": "refund",
  "quantity": 1,
  "refund_amount": 4990,
  "reason": "Produto com defeito"
}'

Resposta

200Devoluções retornadas
json
{
  "data": [
    {
      "id": "2f495c2f-dab7-4580-8004-54e39fa56c75",
      "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68",
      "order_item_id": "936266b5-fb89-4a3f-84b6-05155f1c54d9",
      "customer_id": "220b672c-90fe-4841-ae86-bd4f1ace982e",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "reason_id": "0bc9dc6e-3655-44bc-96ba-b2645336a403",
      "reason": "Produto com defeito",
      "status": "closed",
      "admin_notes": "Reembolso processado pelo administrador",
      "customer_notes": "Veio quebrado",
      "resolution": "refund",
      "refund_amount": 49980,
      "quantity": 1,
      "created_at": "2026-07-12T13:41:51.351302Z",
      "updated_at": "2026-07-21T06:49:58.472408Z",
      "processed_at": "2026-07-21T06:49:58.472408Z",
      "processed_by": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
      "order_number": "97213",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com",
      "product_name": "Smartphone Roxo",
      "reason_name": "Defective product"
    }
  ],
  "meta": { "pagination": { "page": 1, "per_page": 20, "total": 1534, "total_pages": 77 } }
}

Campos da resposta

data[].iduuid
Id da devolução.
data[].order_iduuid
Pedido de origem.
data[].order_item_iduuid | null
Item devolvido. Ausente quando a devolução é do pedido todo.
data[].customer_iduuid
Cliente dono do pedido.
data[].vendor_iduuid | null
Seller do pedido.
data[].reason_iduuid | null
Motivo cadastrado, quando houve.
data[].reasonstring
Motivo em texto livre.
data[].statusstring
requestedapproveditem_receivedrefundedrejectedclosedcancelled
Situação atual, em palavra (não em letra).
data[].admin_notesstring
Observações da equipe. Pode ser vazia.
data[].customer_notesstring
Observações do cliente. Pode ser vazia.
data[].resolutionstring
refundreplacementstore_credit
Resolução escolhida.
data[].refund_amountinteger
Valor reembolsado ou a reembolsar, em centavos.
data[].quantityinteger
Quantidade devolvida.
data[].created_atstring
Criação (RFC 3339, UTC).
data[].updated_atstring
Última alteração (RFC 3339, UTC).
data[].processed_atstring | null
Quando a equipe decidiu.
data[].processed_byuuid | null
Usuário que decidiu ou que abriu a devolução.
data[].order_numberstring
Número do pedido mostrado ao cliente.
data[].customer_namestring
Nome do cliente.
data[].customer_emailstring
E-mail do cliente.
data[].product_namestring
Nome do produto devolvido.
data[].reason_namestring
Nome do motivo cadastrado.

A criação responde 201 com { "data": { ... } }, o mesmo objeto sem os campos de apoio (order_number, customer_name, customer_email, product_name, reason_name) e com processed_by igual ao usuário que abriu.

Erros

StatusQuandoCorpo
400order_id ausente{"error":{"code":"bad_request","message":"order_id is required"}}
400Corpo que não é JSON{"error":{"code":"bad_request","message":"invalid request body","details":"..."}}
404Devolução inexistente (GET por id){"error":{"code":"not_found","message":"return not found"}}
409Já existe devolução ativa para o pedido ou item{"error":{"code":"active_return_exists","message":"an active return already exists for this order/item"}}
500Falha inesperada{"error":{"code":"internal_error","message":"an unexpected error occurred","details":"..."}}
A criação pode responder 500

Só order_id ausente e corpo que não é JSON voltam como 400. Pedido inexistente, pedido em status que não aceita devolução, order_item_id de outro pedido e resolution inválida saem como 500 internal_error nesta rota, com a causa em details, e não como 400. Se a criação falhar com 500 até para um pedido válido, abra a devolução pela API de administração /api/v1/admin e avise o suporte.

Filtre sempre pelo nome da situação

O status do filtro e o status da resposta usam o nome (requested, item_received), não a letra guardada pela loja. Um nome com erro de digitação não dá erro: vira requested e você recebe a fila errada.

Veja também

  • Visão geral da API v2
  • Cupons: consulta
  • Autenticação
Anterior
Cupons: escrita
Próxima
Sellers
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também