Insights

Customer lifetime value

GET/v1/insights/ltv

Scope: insights:read. MCP tool: get_lifetime_value.

See total and average customer spending, with a breakdown by spend range.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

`application/json`

curl -X GET "https://example.com/v1/insights/ltv"

{  "scope": "string",  "total_revenue": "string",  "customer_count": 0,  "average_ltv": "string",  "currency_code": "string",  "distribution": [    {      "label": "string",      "min": 0,      "max": 0,      "customer_count": 0    }  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Lifetime value by year

GET/v1/insights/ltv-by-year

Scope: insights:read. MCP tool: get_lifetime_value_by_year.

See total completed-order revenue per calendar year for the last 5 years, in the primary currency.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

`application/json`

curl -X GET "https://example.com/v1/insights/ltv-by-year"

{  "scope": "string",  "currency_code": "string",  "coverage_from": "string",  "years": [    {      "year": 0,      "total_revenue": "string"    }  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

RFM tiers

GET/v1/insights/rfm

Scope: insights:read. MCP tool: get_rfm_tiers.

See customer groups based on how recently they bought, how often they buy and how much they spend. Use as_of as the date for measuring time since the last purchase; the default is now.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

`application/json`

curl -X GET "https://example.com/v1/insights/rfm"

{  "scope": "string",  "as_of": "string",  "customer_count": 0,  "distribution": [    {      "tier": "string",      "customer_count": 0,      "share": 0    }  ],  "definitions": [    {      "tier": "string",      "description": "string",      "rule": "string"    }  ],  "grid": [    {      "recency_score": 0,      "frequency_score": 0,      "customer_count": 0    }  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Top-selling products

GET/v1/insights/products

Scope: insights:read. MCP tool: get_top_products.

See top products by revenue and order count, based on completed orders. The default period is the 30 days ending at created_at_lte, or today if omitted. Date ranges longer than 31 days return bad_request.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

created_at_gte?string|null

created_at_lte?string|null

Response Body

`application/json`

curl -X GET "https://example.com/v1/insights/products"

{  "scope": "string",  "top_by_revenue": [    {      "product_id": "string",      "title": "string",      "quantity": 0,      "order_count": 0,      "customer_count": 0,      "revenue": "string",      "repeat_purchase_rate": 0    }  ],  "top_by_order_count": [    {      "product_id": "string",      "title": "string",      "quantity": 0,      "order_count": 0,      "customer_count": 0,      "revenue": "string",      "repeat_purchase_rate": 0    }  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Customers at risk of churning

GET/v1/insights/at-risk

Scope: insights:read. MCP tool: list_at_risk_customers.

Find repeat customers who are overdue for their next order. Includes customers with purchases on at least two different days who have gone more than twice their usual interval without ordering. Use as_of as the date for measuring time since the last purchase; the default is now.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

limit?integer

cursor?string|null

as_of?string|null

Response Body

`application/json`

curl -X GET "https://example.com/v1/insights/at-risk"

{  "data": [    {      "contact_id": "string",      "name": "string",      "email": "string",      "phone": "string",      "external_id": "string",      "last_order_at": "string",      "days_since_last_order": 0,      "median_inter_order_days": 0,      "brand_median_inter_order_days": 0,      "at_risk": true,      "at_risk_score": 0    }  ],  "next_cursor": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Lifecycle stage counts

GET/v1/insights/lifecycle

Scope: insights:read. MCP tool: get_lifecycle_stages.

See lifecycle stage counts (Visitors, Customers, Repeat Customers, and more) read from the brand seeded lifecycle segments, with conversion ratios between adjacent stages.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/insights/lifecycle"

{  "stages": [    {      "node": "string",      "segment_id": "string",      "name": "string",      "member_count": 0,      "evaluated_at": "string",      "state": "evaluating",      "delta_30d": 0    }  ],  "edges": [    {      "from": "string",      "to": "string",      "ratio": 0    }  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Customer overview

GET/v1/insights/overview

Scope: insights:read. MCP tool: get_customer_overview.

See active buyers, average order value, orders per customer and total value for a 7, 30 or 90 day window, with the previous window for comparison, daily series for both windows and the new vs returning customer value split.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

window_days?string|null

segment?string|null

Response Body

`application/json`

curl -X GET "https://example.com/v1/insights/overview"

{  "window_days": 0,  "segment": "all",  "currency_code": "string",  "coverage_from": "string",  "active_buyers": 0,  "average_order_value": "string",  "orders_per_customer": 0,  "total_value": "string",  "previous_active_buyers": 0,  "previous_average_order_value": "string",  "previous_orders_per_customer": 0,  "previous_total_value": "string",  "series": [    {      "date": "string",      "active_buyers": 0,      "orders": 0,      "total_value": "string",      "average_order_value": "string",      "orders_per_customer": 0    }  ],  "previous_series": [    {      "date": "string",      "active_buyers": 0,      "orders": 0,      "total_value": "string",      "average_order_value": "string",      "orders_per_customer": 0    }  ],  "revenue_split": {    "new_value": "string",    "returning_value": "string",    "new_buyers": 0,    "returning_buyers": 0,    "previous": {      "new_value": "string",      "returning_value": "string",      "new_buyers": 0,      "returning_buyers": 0    }  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Product performance

GET/v1/insights/product-performance

Scope: insights:read. MCP tool: get_product_performance.

See per-product viewers, add to cart, checkouts, orders, buyers, units and revenue for a 7, 30 or 90 day window with the previous window for comparison, and the store funnel from visits to purchases.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

window_days?string|null

Response Body

`application/json`

curl -X GET "https://example.com/v1/insights/product-performance"

{  "window_days": 0,  "currency_code": "string",  "browse_coverage_from": "string",  "products": [    {      "product_id": "string",      "title": "string",      "image_url": "string",      "viewers": 0,      "add_to_cart": 0,      "checkouts": 0,      "orders": 0,      "buyers": 0,      "units": 0,      "revenue": "string",      "previous": {        "viewers": 0,        "add_to_cart": 0,        "checkouts": 0,        "orders": 0,        "buyers": 0,        "units": 0,        "revenue": "string"      }    }  ],  "funnel": {    "visits": 0,    "product_views": 0,    "add_to_cart": 0,    "checkout_started": 0,    "purchases": 0,    "previous": {      "visits": 0,      "product_views": 0,      "add_to_cart": 0,      "checkout_started": 0,      "purchases": 0    }  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

First products bought

GET/v1/insights/first-product

Scope: insights:read. MCP tool: get_first_products.

See which products customers buy first: the top 10 line-item titles from each customer's earliest completed order, with a count and share of all purchasing customers.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/insights/first-product"

{  "denominator": 0,  "products": [    {      "title": "string",      "count": 0,      "share": 0    }  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

First-order acquisition sources

GET/v1/insights/sources

Scope: insights:read. MCP tool: get_acquisition_sources.

See where first orders come from: customers counted by the utm_source of their earliest completed order, falling back to referrer_host then 'direct'. Top 8 sources plus 'other'.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/insights/sources"

{  "denominator": 0,  "sources": [    {      "source": "string",      "count": 0,      "share": 0    }  ]}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`