Lucratividade

Get Return Journeys

GET
/v1/profitability/return-journeys

How customers come back for their SECOND purchase. For every customer (cross-platform identity, customer_email of the store orders in analytics.fct_transactions: VTEX, Shopify, Tray, WooCommerce and Nuvemshop; won CRM deals and Mercos orders are left out) whose second purchase falls in the period, the second purchase is the first order on a later day than the first purchase (the first purchase may predate the period; an order split on the day of the first purchase is not a return). Second purchases are grouped by the channel, the coupon and the main product of that return order, and the five largest groups by customers are returned. Channel is the order's last-click channel from analytics.fct_order_acquisition_channel (an order the fact does not resolve reads Sem atribuição with isUnattributed: true, as in return-channels); coupon is the code typed on the order, from analytics.fct_order_coupons, normalized like the coupons endpoint (null without a coupon); main product is the product with the largest net sales in the order (analytics.fct_order_sku_sales), named and pictured from analytics.dim_product_catalog. medianDaysToReturn is the median of the days between the first and the second purchase; revenue is the official revenue (SUM(revenue)) of the second purchase only; totalCustomers and totalRevenue cover every second purchase of the period, and customerShare is over totalCustomers. Aggregates only: no customer identifier or personal data is returned. Both dates are required (UTC); the period spans at most 366 days.

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

First day of the period, inclusive (YYYY-MM-DD, UTC). The second purchase falls on or after it. Required.

Formatodate
endDate*string

Last day of the period, inclusive (YYYY-MM-DD, UTC). Required. At most 366 days from startDate.

Formatodate
gtmMotionId?string

GTM motion da organização (UUID), como listada por GET /v1/gtm-motions. Opcional: sem ele, a resposta cobre a GTM motion padrão da organização. Este endpoint ainda não é recortado por GTM motion: a motion padrão responde com os dados da organização, os mesmos números de quando o parâmetro é omitido, e qualquer outra GTM motion da organização recebe 422 GTM_MOTION_DATA_NOT_AVAILABLE. Não UUID: 400. GTM motion que não é uma motion ativa da organização: 403 GTM_MOTION_NOT_IN_ORGANIZATION.

Formatouuid

Corpo da resposta

Return journeys retrieved successfully

application/json
  1. response
period*
totalCustomers*integer

Customers whose second purchase falls in the period.

totalRevenue*number

Official revenue of every second purchase of the period.

journeys*array<>

Up to five journeys, by customers desc, then revenue desc.

Itensitems <= 5
curl -X GET "https://example.com/v1/profitability/return-journeys?organizationId=c0ad4763-173e-4a05-9cff-5208c8ea5f6a&startDate=2025-11-01&endDate=2026-10-31&gtmMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"
{  "period": {    "startDate": "2025-11-01",    "endDate": "2026-10-31"  },  "totalCustomers": 3120,  "totalRevenue": 1747200,  "journeys": [    {      "channel": "Meta Ads",      "isUnattributed": false,      "coupon": "VOLTE10",      "productId": "8812",      "productName": "Tênis 574",      "imageUrl": "https://cdn.example.com/574.webp",      "medianDaysToReturn": 42,      "customers": 420,      "customerShare": 13.46,      "revenue": 251580    },    {      "channel": "Orgânico",      "isUnattributed": false,      "coupon": null,      "productId": "9060",      "productName": "Tênis 9060",      "imageUrl": null,      "medianDaysToReturn": 68,      "customers": 188,      "customerShare": 6.03,      "revenue": 225412    },    {      "channel": "Sem atribuição",      "isUnattributed": true,      "coupon": null,      "productId": null,      "productName": null,      "imageUrl": null,      "medianDaysToReturn": 55,      "customers": 126,      "customerShare": 4.04,      "revenue": 70560    }  ]}