Brand LTV

GET /cdp/insights/ltv — brand-wide lifetime-value aggregates across all of your purchasing customers: total revenue, the number of customers who have purchased, average LTV, and the distribution of customers across LTV buckets.

Requires the beta:cdp-commerce permission on your brand.

What counts

Aggregates are computed over completed orders only (state = "complete"); orders in any other state — pending, cancelled, refunded — are excluded. Each customer’s LTV is the sum of their completed-order totals; orders not attributed to a customer are excluded from the customer grouping. Amounts are denominated in the store’s currency as dollar-value decimal strings (e.g. "2050.00", not cents).

Metrics are computed on read from your synced orders, so they always reflect your current data. The response contract is stable: if computation is later cached or materialized, the shape below does not change (a cache would carry at most a few minutes of staleness).

Request

GET /cdp/insights/ltv
Authorization: Bearer vyg_…

This endpoint takes no path or query parameters.

Response 200

{
  "scope": "your-shop.myshopify.com",
  "total_revenue": "2050.00",
  "customer_count": 4,
  "average_ltv": "512.50",
  "currency_code": "USD",
  "distribution": [
    { "label": "0-100", "min": 0, "max": 100, "customer_count": 1 },
    { "label": "100-250", "min": 100, "max": 250, "customer_count": 1 },
    { "label": "250-500", "min": 250, "max": 500, "customer_count": 1 },
    { "label": "500-1000", "min": 500, "max": 1000, "customer_count": 0 },
    { "label": "1000+", "min": 1000, "max": null, "customer_count": 1 }
  ]
}

Field	Type	Description
scope	string | null	Your connected shop domain.
total_revenue	string	Sum of all customers’ lifetime value, as a decimal string.
customer_count	integer	Number of distinct customers with at least one completed order.
average_ltv	string	total_revenue / customer_count, as a decimal string ("0.00" when there are no customers).
currency_code	string | null	Currency of the completed orders, or null when there are none.
distribution	array	Fixed LTV buckets over dollar-denominated LTV; every bucket is always present, even with count 0.
distribution[].label	string	Human-readable bucket label, e.g. "0-100" / "1000+".
distribution[].min	number	Inclusive lower bound of the bucket, in dollars.
distribution[].max	number | null	Exclusive upper bound in dollars; null for the open-ended top bucket.
distribution[].customer_count	integer	Number of customers whose LTV falls in this bucket.

The bucket customer_count values always sum to the top-level customer_count.

Example

curl -s "https://cdp.vyg.app/cdp/insights/ltv" \
  -H "Authorization: Bearer vyg_your_key_here"

Errors

Status	When
401	Missing or invalid credential.
403	Brand not enrolled in the commerce beta (beta_not_enabled), or no connected Shopify integration (integration_not_connected).
405	Non-GET method.

See Customer Insights for the per-customer summary, and Tenant Isolation & Scope for how each brand’s aggregate is computed only over its own orders.