Análise de safras de lucratividade
Retorna uma matriz de retenção por coorte: cada linha agrupa clientes pelo início da relação com a loja e cada coluna mostra quanto deles volta nos períodos seguintes (months, com pct em decimal e absolute).
view=logo(padrão) mede por número de clientes;view=revenue, por receita × margem de contribuição.groupBy=month|quarter|semestermuda apenas o tamanho das colunas. As linhas continuam sendo safras mensais e a coluna0é sempre o mês de entrada.breakByescolhe o que é cada linha:cohort(padrão, mês da primeira compra),product(produto da primeira compra),origem(canal),campanhaoucupom. Fora decohort, cada cliente começa no seu próprio mês 0. O formato da resposta muda conformebreakBy.- Células e linhas cujo período ainda não terminou vêm com
maturing: true: o valor é parcial. - Em
breakBy=productas linhas se sobrepõem e não devem ser somadas. Nas quebras por produto, canal, campanha e cupom, exibacoveragejunto dos números: ele indica quanto da base pôde ser atribuído.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringIdentificador da organização (obrigatório)
startDate?stringPrimeiro dia do período, inclusivo (YYYY-MM-DD). Só é aplicado junto com endDate; sem os dois, a API considera todo o histórico.
dateendDate?stringÚltimo dia do período, inclusivo (YYYY-MM-DD). Só é aplicado junto com startDate; sem os dois, a API considera todo o histórico.
dateview?stringModo de visão da coorte: logo para retenção por quantidade de clientes, revenue para retenção baseada em receita (padrão: logo)
"logo""logo""revenue"groupBy?stringTamanho das colunas de período da matriz: month (padrão), quarter (trimestre) ou semester (semestre). As linhas não mudam: continuam sendo safras mensais, e a coluna 0 é sempre o mês de entrada. A coluna K cobre os meses (K−1)·passo+1 a K·passo após a entrada.
"month""month""quarter""semester"breakBy?stringO que cada linha da matriz representa: cohort (padrão, uma linha por mês da primeira compra), product (uma linha por produto da primeira compra, com LTV por produto e cobertura de atribuição), origem (canal de origem), campanha (nome da campanha) ou cupom (código do cupom). Origem, campanha e cupom são identificados na primeira compra do cliente e compartilham o mesmo formato de resposta.
"cohort""cohort""product""origem""campanha""cupom"Dados da análise de coorte obtidos com sucesso
application/json- response
view*stringModo de visão da coorte ativo: logo (quantidade de clientes) ou revenue (receita ajustada pela margem)
groupBy*stringTamanho das colunas de período aplicado, igual ao da requisição (padrão month). As linhas são sempre safras mensais.
"month""quarter""semester"data*array<>Linhas da matriz de retenção por coorte ordenadas por cohortMonth crescente
marginPercent*numberPercentual de margem de contribuição aplicado. 100 quando nenhuma margem está configurada
marginConfigured*booleanIndica se uma margem de contribuição personalizada foi configurada para esta organização
marginCompleteness?MarginCompletenessCompletude da margem configurada item a item (gateway, imposto, frete e CMV): complete = todos os itens resolvidos; partial = algum item pendente, então a margem é parcial; none = não há composição por item (margem nunca configurada ou configurada como percentual único; diferencie pelos valores de marginConfigured).
"complete""partial""none"marginItemStatus?|Status por item da composição da margem (synced = vindo dos pedidos, configured = informado pelo usuário, pending = não configurado ou com dados ausentes). null quando a organização não tem composição.
breakBy*"cohort"O que cada linha representa nesta resposta: cohort (mês da primeira compra).
"cohort"curl -X GET "https://example.com/v1/profitability/cohort?organizationId=c0ad4763-173e-4a05-9cff-5208c8ea5f6a&startDate=2025-01-01&endDate=2025-12-31&view=logo&groupBy=quarter&breakBy=product"{ "view": "logo", "groupBy": "month", "data": [ { "cohortMonth": "2025-10-01", "initialValue": 210, "acquisitionInvestment": 42000, "roi": 0.85, "months": { "0": { "pct": 1, "absolute": 210, "complementary": 77700 }, "1": { "pct": 0.52, "absolute": 109, "complementary": 31080 }, "2": { "pct": 0.38, "absolute": 80, "complementary": 22200 } } } ], "marginPercent": 35, "marginConfigured": true, "marginCompleteness": "none", "marginItemStatus": null, "breakBy": "cohort"}