Coortes de retenção

Matriz de retenção por mês de primeira compra e criação de uma audiência de CRM a partir de uma célula.

Uma coorte é o grupo de clientes que fez a primeira compra no mesmo mês. A matriz mostra, para cada coorte, quantos desses clientes voltaram a comprar 1, 2, 3 meses depois. É a forma mais honesta de responder "os clientes que conquistamos estão voltando?". A segunda rota transforma uma célula da matriz (por exemplo, quem comprou em março e não voltou em 3 meses) em uma audiência fixa do CRM, pronta para uma campanha.

Matriz de coortes

GET/api/v1/admin/analytics/cohortsAdmin

Matriz de retenção por coorte

Parâmetros de consulta

metricstringpadrão: retention

retentionltv

Como a UI deve ler a matriz. É só devolvido no campo metric: os dois valores (retained e revenue_cum_cents) vêm sempre preenchidos. Outro valor vira retention.

monthsintegerpadrão: 12

Quantas coortes (meses) mostrar, contando o mês atual. Valor fora de 1 a 36 vale 12.

channelstring

directpaid_searchpaid_socialorganic_searchorganic_socialreferralwhatsappcrm

Só clientes cuja primeira compra veio deste canal. Veja as chaves em Canais.

category_idstring

Aceito, mas hoje não filtra nada.

vendor_idstring

Aceito, mas hoje não filtra nada.

Exemplo de requisição (cohorts)

bash

curl "$BASE_URL/api/v1/admin/analytics/cohorts?months=6&metric=retention" \
  -H "Authorization: Bearer $TOKEN"

Resposta (cohorts)

200Matriz retornada

json

{
  "metric": "retention",
  "months": 2,
  "cohorts": [
    {
      "cohort_month": "2026-09",
      "size": 4,
      "cells": [
        { "offset": 0, "retained": 4, "retention_bps": 10000, "revenue_cum_cents": 193216 },
        { "offset": 1, "retained": 0, "retention_bps": 0, "revenue_cum_cents": 193216 }
      ],
      "partial_last": true,
      "small_sample": true
    }
  ]
}

Campos da resposta

metricstring

retention ou ltv, como pedido.

monthsinteger

Número de coortes pedido, já corrigido.

cohortsarray

Uma linha por mês de primeira compra, do mais antigo para o mais novo.

cohorts[].cohort_monthstring

Mês da primeira compra, YYYY-MM.

cohorts[].sizeinteger

Clientes da coorte.

cohorts[].cellsarray

Uma célula por mês desde a coorte, até o mês atual.

cohorts[].cells[].offsetinteger

Meses depois da primeira compra. 0 é o próprio mês.

cohorts[].cells[].retainedinteger

Clientes da coorte que compraram nesse mês.

cohorts[].cells[].retention_bpsinteger

retained sobre size, em pontos-base (10000 = 100%).

cohorts[].cells[].revenue_cum_centsinteger

Receita acumulada da coorte até esse mês, em centavos.

cohorts[].partial_lastboolean

Sempre true: a última célula é o mês atual, ainda incompleto.

cohorts[].small_sampleboolean

true quando a coorte tem menos de 10 clientes: evite tirar conclusões.

Erros (cohorts)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha ao consultar os dados.	`{"error":"failed to ..."}`

Audiência a partir de uma célula

POST/api/v1/admin/analytics/cohorts/segmentAdmin

Criar audiência de CRM a partir de uma célula

Corpo da requisição

cohort_monthstringobrigatório

Mês da coorte, YYYY-MM.

offsetintegerpadrão: 1

Meses depois da primeira compra. Menor que 1 vale 1.

modestringpadrão: not_returned

returnednot_returned

returned: quem comprou no mês M+offset. not_returned: quem não comprou de novo até M+offset. Outro valor vira not_returned.

namestring

Nome da audiência. Se vazio, a plataforma gera um nome.

Exemplo de requisição (segment)

bash

curl -X POST "$BASE_URL/api/v1/admin/analytics/cohorts/segment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cohort_month": "2026-03", "offset": 3, "mode": "not_returned", "name": "Março sem recompra"}'

Resposta (segment)

200Audiência criada

json

{
  "audience_id": "6b1c0d6e-4e5a-4a2f-9a55-3f0f2f5c9a10",
  "customers": 42
}

Campos da resposta

audience_idstring

Id da audiência criada no CRM (UUID).

customersinteger

Quantos clientes entraram na audiência.

Erros (segment)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid body"}`
400	Falta `cohort_month`.	`{"error":"cohort_month required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"crm"}`
500	`cohort_month` fora do formato `YYYY-MM` ou falha ao criar a audiência. Hoje esses casos voltam como 500, não 400.	`{"error":"failed to create cohort segment"}`

Veja também

Coortes de retenção

Matriz de retenção por mês de primeira compra e criação de uma audiência de CRM a partir de uma célula.

Matriz de coortes

GET/api/v1/admin/analytics/cohortsAdmin

Matriz de retenção por coorte

Parâmetros de consulta

metricstringpadrão: retention

retentionltv

Como a UI deve ler a matriz. É só devolvido no campo metric: os dois valores (retained e revenue_cum_cents) vêm sempre preenchidos. Outro valor vira retention.

monthsintegerpadrão: 12

Quantas coortes (meses) mostrar, contando o mês atual. Valor fora de 1 a 36 vale 12.

channelstring

directpaid_searchpaid_socialorganic_searchorganic_socialreferralwhatsappcrm

Só clientes cuja primeira compra veio deste canal. Veja as chaves em Canais.

category_idstring

Aceito, mas hoje não filtra nada.

vendor_idstring

Aceito, mas hoje não filtra nada.

Exemplo de requisição (cohorts)

bash

curl "$BASE_URL/api/v1/admin/analytics/cohorts?months=6&metric=retention" \
  -H "Authorization: Bearer $TOKEN"

Resposta (cohorts)

200Matriz retornada

json

{
  "metric": "retention",
  "months": 2,
  "cohorts": [
    {
      "cohort_month": "2026-09",
      "size": 4,
      "cells": [
        { "offset": 0, "retained": 4, "retention_bps": 10000, "revenue_cum_cents": 193216 },
        { "offset": 1, "retained": 0, "retention_bps": 0, "revenue_cum_cents": 193216 }
      ],
      "partial_last": true,
      "small_sample": true
    }
  ]
}

Campos da resposta

metricstring

retention ou ltv, como pedido.

monthsinteger

Número de coortes pedido, já corrigido.

cohortsarray

Uma linha por mês de primeira compra, do mais antigo para o mais novo.

cohorts[].cohort_monthstring

Mês da primeira compra, YYYY-MM.

cohorts[].sizeinteger

Clientes da coorte.

cohorts[].cellsarray

Uma célula por mês desde a coorte, até o mês atual.

cohorts[].cells[].offsetinteger

Meses depois da primeira compra. 0 é o próprio mês.

cohorts[].cells[].retainedinteger

Clientes da coorte que compraram nesse mês.

cohorts[].cells[].retention_bpsinteger

retained sobre size, em pontos-base (10000 = 100%).

cohorts[].cells[].revenue_cum_centsinteger

Receita acumulada da coorte até esse mês, em centavos.

cohorts[].partial_lastboolean

Sempre true: a última célula é o mês atual, ainda incompleto.

cohorts[].small_sampleboolean

true quando a coorte tem menos de 10 clientes: evite tirar conclusões.

Erros (cohorts)

Status	Quando	Corpo
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha ao consultar os dados.	`{"error":"failed to ..."}`

Audiência a partir de uma célula

POST/api/v1/admin/analytics/cohorts/segmentAdmin

Criar audiência de CRM a partir de uma célula

Corpo da requisição

cohort_monthstringobrigatório

Mês da coorte, YYYY-MM.

offsetintegerpadrão: 1

Meses depois da primeira compra. Menor que 1 vale 1.

modestringpadrão: not_returned

returnednot_returned

returned: quem comprou no mês M+offset. not_returned: quem não comprou de novo até M+offset. Outro valor vira not_returned.

namestring

Nome da audiência. Se vazio, a plataforma gera um nome.

Exemplo de requisição (segment)

bash

curl -X POST "$BASE_URL/api/v1/admin/analytics/cohorts/segment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cohort_month": "2026-03", "offset": 3, "mode": "not_returned", "name": "Março sem recompra"}'

Resposta (segment)

200Audiência criada

json

{
  "audience_id": "6b1c0d6e-4e5a-4a2f-9a55-3f0f2f5c9a10",
  "customers": 42
}

Campos da resposta

audience_idstring

Id da audiência criada no CRM (UUID).

customersinteger

Quantos clientes entraram na audiência.

Erros (segment)

Status	Quando	Corpo
400	Corpo que não é JSON.	`{"error":"invalid body"}`
400	Falta `cohort_month`.	`{"error":"cohort_month required"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"crm"}`
500	`cohort_month` fora do formato `YYYY-MM` ou falha ao criar a audiência. Hoje esses casos voltam como 500, não 400.	`{"error":"failed to create cohort segment"}`