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"gtmMotionId?stringGTM motion of the organization (UUID), as listed by GET /v1/gtm-motions. Optional: without it, or with the default GTM motion, the response is the organization data, exactly as before. Any other GTM motion of the organization is answered with that motion's own rows, read from the *_by_gtm_motion twins of the models behind the route (obt_profitability_daily/monthly/cohorts/product_cohorts/cohorts_by_dimension, obt_acquisition_customers, obt_acquisition_product_cohorts, fct_transactions and fct_media_daily), and the monetary figures are priced with the motion's own contribution margin (V4MOS-2707). A motion with no store linked has no orders or customers: the route answers with zeros or empty lists, never an error. Not a UUID: 400. Not a live GTM motion of the organization: 403 GTM_MOTION_NOT_IN_ORGANIZATION.
uuidDados 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>mMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"{ "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"}