Profitability

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.

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, UTC). The second purchase falls on or after it. Required.

Formatdate
endDate*string

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

Formatdate
gtmMotionId?string

GTM motion of the organization (UUID), as listed by GET /v1/gtm-motions. Optional: without it, the response covers the organization's default GTM motion. This endpoint is not split by GTM motion yet: the default motion is answered with the organization's data, the same numbers as when the parameter is omitted, and any other GTM motion of the organization returns 422 GTM_MOTION_DATA_NOT_AVAILABLE. Not a UUID: 400. Not a live GTM motion of the organization: 403 GTM_MOTION_NOT_IN_ORGANIZATION.

Formatuuid

Response Body

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.

Itemsitems <= 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    }  ]}