Lucratividade

Clientes novos vs. recorrentes ao longo do tempo

GET
/v1/profitability/new-vs-recurring

Retorna uma série temporal com clientes novos (primeira compra no período do ponto) e recorrentes (já tinham comprado antes) que fizeram pedido. Ideal para gráficos de barras empilhadas ou de área.

  • Períodos de até 31 dias retornam pontos diários, respeitando exatamente startDate–endDate.
  • Períodos maiores, ou sem datas, retornam pontos mensais, com o período expandido para meses inteiros.
  • O campo granularity informa qual granularidade foi usada.

Autorização

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Parâmetros de query

organizationId*string

Identificador da organização (obrigatório)

startDate?string

Primeiro dia do período, inclusivo (YYYY-MM-DD). Só é aplicado junto com endDate; sem os dois, a API considera todo o histórico.

Formatodate
endDate?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.

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

Formatouuid

Corpo da resposta

Dados de novos vs recorrentes obtidos com sucesso

application/json
  1. response
data*array<>

Detalhamento de clientes novos vs recorrentes por período (mês ou dia, veja granularity)

granularity?string

Granularidade da série, definida pelo tamanho do período: daily para até 31 dias, monthly para períodos maiores ou sem datas.

Valor em"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"}