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

Métricas de clientes

Taxa de recompra, valor de vida (LTV), tempo entre pedidos e segmentação RFM.

Quatro indicadores clássicos de retenção, todos calculados sobre os clientes que compraram na janela escolhida. Todos usam o mesmo formato de período: from e to (datas) ou o atalho period. Sem nenhum dos dois, vale os últimos 30 dias. Só entram pedidos que contam como venda (sem cancelados, reembolsados, falhos, chargeback ou anulados) e só pedidos pai.

Taxa de recompra

GET/api/v1/admin/analytics/repurchaseAdmin

Clientes novos e recorrentes na janela

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.
tostring
Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.
periodstringpadrão: 30days
today7days30days90daysthis_monthlast_monththis_year
Atalho de janela quando from/to não são enviados.

Exemplo de requisição (repurchase)

bash
curl "$BASE_URL/api/v1/admin/analytics/repurchase?period=90days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (repurchase)

200Taxa retornada
json
{
  "total_customers": 4,
  "new_customers": 2,
  "repeat_customers": 2,
  "new_pct": 50,
  "repeat_pct": 50
}

Campos da resposta

total_customersinteger
Clientes com pelo menos um pedido na janela.
new_customersinteger
Clientes com exatamente 1 pedido na janela.
repeat_customersinteger
Clientes com 2 ou mais pedidos na janela.
new_pctnumber
new_customers em porcentagem de 0 a 100.
repeat_pctnumber
repeat_customers em porcentagem de 0 a 100.

Erros (repurchase)

StatusQuandoCorpo
400period desconhecido.{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}
400from/to mal formatados, from depois de to, ou mais de 2 anos.{"error":"date range must not exceed 2 years"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}

Valor de vida (LTV)

GET/api/v1/admin/analytics/ltvAdmin

Valor de vida médio dos clientes ativos

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.
tostring
Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.
periodstringpadrão: 30days
today7days30days90daysthis_monthlast_monththis_year
Atalho de janela quando from/to não são enviados.

Exemplo de requisição (ltv)

bash
curl "$BASE_URL/api/v1/admin/analytics/ltv?period=90days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (ltv)

200LTV retornado
json
{
  "avg_ltv_centavos": 123072,
  "customer_count": 4
}

Campos da resposta

avg_ltv_centavosinteger
Gasto médio de todos os tempos, em centavos, dos clientes que compraram na janela.
customer_countinteger
Quantos clientes entraram na média.

Erros (ltv)

StatusQuandoCorpo
400period desconhecido.{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}
400from/to mal formatados, from depois de to, ou mais de 2 anos.{"error":"date range must not exceed 2 years"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}

Tempo entre pedidos

GET/api/v1/admin/analytics/time-betweenAdmin

Tempo médio entre pedidos do mesmo cliente

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.
tostring
Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.
periodstringpadrão: 30days
today7days30days90daysthis_monthlast_monththis_year
Atalho de janela quando from/to não são enviados.

Exemplo de requisição (time-between)

bash
curl "$BASE_URL/api/v1/admin/analytics/time-between?period=90days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (time-between)

200Tempo retornado
json
{
  "avg_days": 0.3033554136082176,
  "sample_count": 4
}

Campos da resposta

avg_daysnumber
Intervalo médio, em dias (com decimais), entre pedidos consecutivos do mesmo cliente dentro da janela. 0 se ninguém comprou duas vezes.
sample_countinteger
Quantos intervalos entre pedidos entraram na média.

Erros (time-between)

StatusQuandoCorpo
400period desconhecido.{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}
400from/to mal formatados, from depois de to, ou mais de 2 anos.{"error":"date range must not exceed 2 years"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}

Segmentação RFM

GET/api/v1/admin/analytics/rfmAdmin

Segmentação RFM dos clientes

Parâmetros de consulta

fromstring
Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.
tostring
Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.
periodstringpadrão: 30days
today7days30days90daysthis_monthlast_monththis_year
Atalho de janela quando from/to não são enviados.

Exemplo de requisição (rfm)

bash
curl "$BASE_URL/api/v1/admin/analytics/rfm?period=90days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (rfm)

200Segmentos retornados
json
{
  "champions": 0,
  "loyal": 1,
  "at_risk": 1,
  "lost": 1,
  "champions_pct": 0,
  "loyal_pct": 25,
  "at_risk_pct": 25,
  "lost_pct": 25
}

Campos da resposta

championsinteger
Recência, frequência e valor todos nos 40% melhores (nota 4 ou 5 nos três).
loyalinteger
Recência e frequência com nota 3 ou mais, fora do grupo dos campeões.
at_riskinteger
Compravam com frequência (nota 3 ou mais) mas não voltam há tempo (recência 1 ou 2).
lostinteger
Pouca frequência e pouca recência (notas 1 ou 2 nas duas).
champions_pctnumber
champions em porcentagem dos clientes ativos, 0 a 100.
loyal_pctnumber
loyal em porcentagem.
at_risk_pctnumber
at_risk em porcentagem.
lost_pctnumber
lost em porcentagem.

Erros (rfm)

StatusQuandoCorpo
400period desconhecido.{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}
400from/to mal formatados, from depois de to, ou mais de 2 anos.{"error":"date range must not exceed 2 years"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem o privilégio exigido.{"error":"insufficient privileges","required":"view_reports"}
403O módulo está desligado na loja.{"error":"module_disabled","module":"analytics"}
500Falha ao consultar os dados.{"error":"failed to ..."}
RFM: o que é e por que os grupos não somam 100%

RFM classifica cada cliente por Recência (há quanto tempo comprou), Frequência (quantos pedidos) e Valor monetário (quanto gastou). Cada medida recebe uma nota de 1 a 5 por quintis, calculados sobre os clientes da própria loja, então os cortes se adaptam ao seu volume. Clientes do meio do caminho não caem em nenhum dos quatro grupos, por isso champions_pct + loyal_pct + at_risk_pct + lost_pct pode ser menor que 100.

LTV não é restrito à janela

A janela só escolhe quais clientes entram. O valor gasto de cada um é o acumulado de todos os tempos.

Veja também

  • Clientes e maiores compradores
  • Coortes de retenção
Anterior
Clientes e maiores compradores
Próxima
Padrões de tempo
Nesta página
  • Taxa de recompra
  • Exemplo de requisição (repurchase)
  • Resposta (repurchase)
  • Erros (repurchase)
  • Valor de vida (LTV)
  • Exemplo de requisição (ltv)
  • Resposta (ltv)
  • Erros (ltv)
  • Tempo entre pedidos
  • Exemplo de requisição (time-between)
  • Resposta (time-between)
  • Erros (time-between)
  • Segmentação RFM
  • Exemplo de requisição (rfm)
  • Resposta (rfm)
  • Erros (rfm)
  • Veja também