Profitability

Get Profitability Cohort Analysis

GET
/v1/profitability/cohort

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=revenue by revenue × contribution margin.
  • groupBy=month|quarter|semester changes only the column size. Rows remain monthly cohorts and column 0 is always the entry month.
  • breakBy chooses what each row is: cohort (default, first-purchase month), product (first-purchase product), origem (channel), campanha (campaign) or cupom (coupon). Outside cohort, each customer starts at their own month 0. The response shape depends on breakBy.
  • 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, show coverage next to the numbers: it tells how much of the base could be attributed.

Authorization

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Query Parameters

organizationId*string

Organization identifier (required)

startDate?string

First day of the period, inclusive (YYYY-MM-DD). Applied only together with endDate; without both, the API uses the whole history.

Formatdate
endDate?string

Last day of the period, inclusive (YYYY-MM-DD). Applied only together with startDate; without both, the API uses the whole history.

Formatdate
view?string

Cohort view mode: logo for customer-count retention, revenue for revenue-based retention (default: logo)

Default"logo"
Value in"logo""revenue"
groupBy?string

Size 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.

Default"month"
Value in"month""quarter""semester"
breakBy?string

What 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.

Default"cohort"
Value in"cohort""product""origem""campanha""cupom"
gtmMotionId?string

GTM 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.

Formatuuid

Response Body

Cohort analysis data retrieved successfully

application/json
  1. response
view*string

Active cohort view mode: logo (customer-count) or revenue (margin-adjusted revenue)

groupBy*string

Period column size applied, echoing the request (default month). Rows are always monthly cohorts.

Value in"month""quarter""semester"
data*array<>

Cohort retention matrix rows ordered by cohortMonth ascending

marginPercent*number

Contribution margin percentage applied. 100 when no margin is configured

marginConfigured*boolean

Whether a custom contribution margin has been configured for this organization

marginCompleteness?MarginCompleteness

Completeness 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).

Value in"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).

Value in"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&gtmMotionId=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"}