Get Profitability Cohort Analysis
Returns a retention matrix by cohort: each row groups customers by the start of their relationship with the store, and each column shows how many of them come back in the following periods (months, with pct as a decimal and absolute).
view=logo(default) measures by number of customers;view=revenueby revenue × contribution margin.groupBy=month|quarter|semesterchanges only the column size. Rows remain monthly cohorts and column0is always the entry month.breakBychooses what each row is:cohort(default, first-purchase month),product(first-purchase product),origem(channel),campanha(campaign) orcupom(coupon). Outsidecohort, each customer starts at their own month 0. The response shape depends onbreakBy.- Cells and rows whose period has not ended yet have
maturing: true: the value is partial. - With
breakBy=product, rows overlap and must not be added together. In the product, channel, campaign and coupon breakdowns, showcoveragenext to the numbers: it tells how much of the base could be attributed.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringOrganization identifier (required)
startDate?stringFirst day of the period, inclusive (YYYY-MM-DD). Applied only together with endDate; without both, the API uses the whole history.
dateendDate?stringLast day of the period, inclusive (YYYY-MM-DD). Applied only together with startDate; without both, the API uses the whole history.
dateview?stringCohort view mode: logo for customer-count retention, revenue for revenue-based retention (default: logo)
"logo""logo""revenue"groupBy?stringSize of the matrix's period columns: month (default), quarter or semester. Rows do not change: they remain monthly cohorts, and column 0 is always the entry month. Column K covers months (K−1)·step+1 to K·step after entry.
"month""month""quarter""semester"breakBy?stringWhat each matrix row represents: cohort (default, one row per first-purchase month), product (one row per first-purchase product, with per-product LTV and attribution coverage), origem (source channel), campanha (campaign name) or cupom (coupon code). Channel, campaign and coupon are identified on the customer's first purchase and share the same response shape.
"cohort""cohort""product""origem""campanha""cupom"Cohort analysis data retrieved successfully
application/json- response
view*stringActive cohort view mode: logo (customer-count) or revenue (margin-adjusted revenue)
groupBy*stringPeriod column size applied, echoing the request (default month). Rows are always monthly cohorts.
"month""quarter""semester"data*array<>Cohort retention matrix rows ordered by cohortMonth ascending
marginPercent*numberContribution margin percentage applied. 100 when no margin is configured
marginConfigured*booleanWhether a custom contribution margin has been configured for this organization
marginCompleteness?MarginCompletenessCompleteness of the item-by-item margin (gateway, tax, shipping and COGS): complete = every item resolved; partial = some item pending, so the margin is partial; none = no item-by-item composition (margin never configured, or configured as a single percentage; tell them apart with marginConfigured).
"complete""partial""none"marginItemStatus?|Status per item of the margin composition (synced = from the orders, configured = informed by the user, pending = not configured or missing data). null when the organization has no composition.
breakBy*"cohort"What each row represents in this response: cohort (first-purchase month).
"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"}