Profitability

Get New vs Recurring Customers Over Time

GET
/v1/profitability/new-vs-recurring

Returns a time series of new customers (first purchase in the point's period) and returning customers (had bought before) who placed an order. Suited to stacked bar or area charts.

  • Periods of up to 31 days return daily points, matching startDate–endDate exactly.
  • Longer periods, or no dates, return monthly points, with the period expanded to whole months.
  • The granularity field tells which granularity was used.

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

New vs recurring data retrieved successfully

application/json
  1. response
data*array<>

New vs recurring customer breakdown per period (month or day, see granularity)

granularity?string

Series granularity, set by the period length: daily for up to 31 days, monthly for longer periods or no dates.

Value in"monthly""daily"
curl -X GET "https://example.com/v1/profitability/new-vs-recurring?organizationId=c0ad4763-173e-4a05-9cff-5208c8ea5f6a&startDate=2025-01-01&endDate=2025-12-31&gtmMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"
{  "data": [    {      "month": "2025-10-01",      "newCustomers": 210,      "recurringCustomers": 140,      "totalCustomers": 350    },    {      "month": "2025-11-01",      "newCustomers": 195,      "recurringCustomers": 158,      "totalCustomers": 353    }  ],  "granularity": "monthly"}