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

Listar e medir carrinhos abandonados

Lista e detalha carrinhos abandonados e devolve os indicadores de recuperação.

A lista mostra cada carrinho com os itens guardados, o valor e o histórico de e-mails. Os indicadores (stats) resumem o período: quantos carrinhos, quanto dinheiro parado e que fatia foi recuperada. Os registros vêm do mais novo para o mais antigo.

Listar carrinhos abandonados

GET/api/v1/admin/abandoned-cartsAdmin

Lista carrinhos abandonados com filtros

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. Fora disso volta a 20.
emailstring
Parte do e-mail (do registro ou da conta), sem diferenciar maiúsculas.
searchstring
Busca por e-mail, nome, sobrenome ou razão social do cliente.
recoveredboolean
true só os recuperados; qualquer outro valor não vazio (por exemplo false) só os não recuperados. Omita para todos.
date_fromstring
Abandonados a partir desta data/hora (2026-10-01 ou RFC 3339).
date_tostring
Abandonados até esta data/hora.

Exemplo de requisição: listar

bash
curl "$BASE_URL/api/v1/admin/abandoned-carts?recovered=false&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Página de carrinhos
json
{
  "carts": [
    {
      "id": "02981785-4f6f-43d4-adbf-4177a7490550",
      "user_id": "476752ce-1e36-429f-9d77-753a1f08d2cc",
      "email": "maria.souza@example.com",
      "cart_data": [
        {
          "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
          "name": "Notebook Slim Rosa",
          "sku": "SD-002373",
          "quantity": 2,
          "unit_price": 11500,
          "total": 23000,
          "image_url": "/uploads/.../notebook.png"
        }
      ],
      "cart_total_cents": 23000,
      "item_count": 1,
      "recovery_token": "cc9aeeffb08f7c80109ef0d3aca2963482cafe331f764622352b95d8bd4fd0f5",
      "token_expires_at": "2026-10-10T23:53:17.651165Z",
      "recovery_emails_sent": 0,
      "last_campaign_step": 0,
      "recovered": false,
      "abandoned_at": "2026-10-07T21:51:47.165907Z",
      "created_at": "2026-10-07T23:53:17.658413Z",
      "updated_at": "2026-10-07T23:53:17.658413Z",
      "user_email": "maria.souza@example.com"
    }
  ],
  "total": 330,
  "page": 1,
  "per_page": 20,
  "total_pages": 17
}

Campos da resposta

cartsarray

Registros da página.

iduuid
Identificador do registro de carrinho abandonado.
user_iduuid | omitted
Cliente logado dono do carrinho. Ausente em visitante que deixou o e-mail.
emailstring | omitted
E-mail do cliente ou do visitante.
user_emailstring | omitted
E-mail da conta do cliente, quando existe.
customer_documentstring | omitted
CNPJ do cliente (ou CPF, se não houver CNPJ). Ausente em visitante.
cart_dataarray
Itens do carrinho no momento em que foi marcado como abandonado: produto, nome, SKU, quantidade, preço unitário e total (centavos), imagem.
cart_total_centsinteger
Valor do carrinho, em centavos.
item_countinteger
Número de linhas do carrinho.
recovery_tokenstring | omitted
Segredo do link de recuperação. Trate como senha: quem o tem reabre o carrinho.
token_expires_atstring (RFC 3339) | omitted
Quando o token expira (72 horas depois da detecção ou do último e-mail).
recovery_emails_sentinteger
E-mails de recuperação já enviados.
last_email_sent_atstring (RFC 3339) | omitted
Quando saiu o último e-mail.
matched_rule_idinteger | omitted
Regra de recuperação (campanha automática) que atendeu o carrinho.
last_campaign_stepinteger
Maior passo da campanha já enviado: 0 nenhum, 1 primeiro, 2 segundo, 3 terceiro.
recoveredboolean
true quando o cliente concluiu um pedido depois do aviso.
recovered_atstring (RFC 3339) | omitted
Quando foi recuperado.
recovered_order_iduuid | omitted
Pedido que recuperou o carrinho.
abandoned_atstring (RFC 3339)
Última atividade do carrinho antes do abandono.
created_atstring (RFC 3339)
Quando o registro foi criado.
updated_atstring (RFC 3339)
Última alteração do registro.
totalinteger
Total que casa com os filtros.
pageinteger
Página devolvida.
per_pageinteger
Tamanho da página.
total_pagesinteger
Total de páginas.

Erros: listar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403O módulo abandoned-cart está desligado na loja.{"error":"module_disabled","module":"abandoned-cart"}
403Falta o privilégio manage_abandoned_carts (ou manage_orders). Vale também para leitura.{"error":"insufficient privileges","required":"manage_abandoned_carts"}
500Falha ao consultar (por exemplo data em formato que o banco não aceita).{"error":"failed to list abandoned carts","detail":"..."}

Detalhar um carrinho

GET/api/v1/admin/abandoned-carts/{id}Admin

Detalha um carrinho abandonado

Parâmetros de caminho

iduuidobrigatório
Id do registro (não é o id do carrinho original).

Exemplo de requisição: detalhar

bash
curl "$BASE_URL/api/v1/admin/abandoned-carts/02981785-4f6f-43d4-adbf-4177a7490550" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Registro
json
{
  "id": "02981785-4f6f-43d4-adbf-4177a7490550",
  "user_id": "476752ce-1e36-429f-9d77-753a1f08d2cc",
  "email": "maria.souza@example.com",
  "cart_data": [
    {
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa",
      "sku": "SD-002373",
      "quantity": 2,
      "unit_price": 11500,
      "total": 23000,
      "image_url": "/uploads/.../notebook.png"
    }
  ],
  "cart_total_cents": 23000,
  "item_count": 1,
  "recovery_token": "cc9aeeffb08f7c80109ef0d3aca2963482cafe331f764622352b95d8bd4fd0f5",
  "token_expires_at": "2026-10-10T23:53:17.651165Z",
  "recovery_emails_sent": 0,
  "last_campaign_step": 0,
  "recovered": false,
  "abandoned_at": "2026-10-07T21:51:47.165907Z",
  "created_at": "2026-10-07T23:53:17.658413Z",
  "updated_at": "2026-10-07T23:53:17.658413Z",
  "user_email": "maria.souza@example.com"
}

Campos da resposta

iduuid
Identificador do registro de carrinho abandonado.
user_iduuid | omitted
Cliente logado dono do carrinho. Ausente em visitante que deixou o e-mail.
emailstring | omitted
E-mail do cliente ou do visitante.
user_emailstring | omitted
E-mail da conta do cliente, quando existe.
customer_documentstring | omitted
CNPJ do cliente (ou CPF, se não houver CNPJ). Ausente em visitante.
cart_dataarray
Itens do carrinho no momento em que foi marcado como abandonado: produto, nome, SKU, quantidade, preço unitário e total (centavos), imagem.
cart_total_centsinteger
Valor do carrinho, em centavos.
item_countinteger
Número de linhas do carrinho.
recovery_tokenstring | omitted
Segredo do link de recuperação. Trate como senha: quem o tem reabre o carrinho.
token_expires_atstring (RFC 3339) | omitted
Quando o token expira (72 horas depois da detecção ou do último e-mail).
recovery_emails_sentinteger
E-mails de recuperação já enviados.
last_email_sent_atstring (RFC 3339) | omitted
Quando saiu o último e-mail.
matched_rule_idinteger | omitted
Regra de recuperação (campanha automática) que atendeu o carrinho.
last_campaign_stepinteger
Maior passo da campanha já enviado: 0 nenhum, 1 primeiro, 2 segundo, 3 terceiro.
recoveredboolean
true quando o cliente concluiu um pedido depois do aviso.
recovered_atstring (RFC 3339) | omitted
Quando foi recuperado.
recovered_order_iduuid | omitted
Pedido que recuperou o carrinho.
abandoned_atstring (RFC 3339)
Última atividade do carrinho antes do abandono.
created_atstring (RFC 3339)
Quando o registro foi criado.
updated_atstring (RFC 3339)
Última alteração do registro.

Erros: detalhar

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403O módulo abandoned-cart está desligado na loja.{"error":"module_disabled","module":"abandoned-cart"}
403Falta o privilégio manage_abandoned_carts (ou manage_orders). Vale também para leitura.{"error":"insufficient privileges","required":"manage_abandoned_carts"}
500O id não é um UUID válido. Hoje a rota responde 500 (e não 400) nesse caso; detail explica.{"error":"failed to get abandoned cart","detail":"o valor \"xyz\" não é um uuid válido. ..."}
404Não existe registro com esse id.{"error":"abandoned cart not found"}

Indicadores de recuperação

GET/api/v1/admin/abandoned-carts/statsAdmin

Indicadores de carrinhos abandonados e recuperados

Parâmetros de consulta

date_fromstring
Início do período (pelo momento do abandono).
date_tostring
Fim do período.

Exemplo de requisição: indicadores

bash
curl "$BASE_URL/api/v1/admin/abandoned-carts/stats?date_from=2026-10-01&date_to=2026-10-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta: indicadores

200Indicadores
json
{
  "total_abandoned": 330,
  "emails_sent": 6641,
  "recovered": 59,
  "recovery_rate": 17.87878787878788,
  "total_value": 19146800,
  "avg_cart_value": 58021
}

Campos da resposta

total_abandonedinteger
Registros no período.
emails_sentinteger
Soma dos e-mails de recuperação enviados.
recoveredinteger
Registros recuperados.
recovery_ratenumber
recovered dividido por total_abandoned, em percentual de 0 a 100.
total_valueinteger
Soma dos valores dos carrinhos, em centavos.
avg_cart_valueinteger
Valor médio por carrinho, em centavos.

Erros: indicadores

StatusQuandoCorpo de exemplo
401Token ausente ou inválido.{"error":"authentication required"}
403O módulo abandoned-cart está desligado na loja.{"error":"module_disabled","module":"abandoned-cart"}
403Falta o privilégio manage_abandoned_carts (ou manage_orders). Vale também para leitura.{"error":"insufficient privileges","required":"manage_abandoned_carts"}
500Falha ao consultar.{"error":"failed to get abandoned cart stats","detail":"..."}
Caminhos fixos e ids

/abandoned-carts/stats, /detect e /cleanup são caminhos fixos e não ids. Um id sempre é um UUID.

Quem ainda dá para recuperar

Filtre recovered=false e olhe token_expires_at e last_campaign_step: carrinhos com token vencido ou com os 3 passos já enviados dificilmente voltam.

Veja também

  • Carrinhos abandonados: visão geral
  • Enviar e-mail de recuperação
  • Detectar e limpar
Anterior
Carrinhos abandonados
Próxima
Enviar e-mail de recuperação
Nesta página
  • Listar carrinhos abandonados
  • Exemplo de requisição: listar
  • Resposta: listar
  • Erros: listar
  • Detalhar um carrinho
  • Exemplo de requisição: detalhar
  • Resposta: detalhar
  • Erros: detalhar
  • Indicadores de recuperação
  • Exemplo de requisição: indicadores
  • Resposta: indicadores
  • Erros: indicadores
  • Veja também