Insights

Insights turn your order history into per-customer and brand-wide metrics: lifetime value, RFM tiers, product patterns, and churn risk.

They share a few ground rules:

• Completed orders only. Every metric is computed over orders in state = "complete". Pending, draft, delivered, cancelled, and refunded orders are excluded. See Commerce Data.
• Dollar decimal strings. Money is a decimal string in the store’s currency (e.g. "300.00"), never cents.
• Computed on read. Metrics are computed from your synced completed orders at request time, so they always reflect your current data.
• Stable contract. If a metric is later cached or materialized for performance, the response shape does not change.
• For reporting and personalization, not financial settlement.

LTV and spend

Lifetime value is the sum of a customer’s completed-order totals.

Per customer — GET /cdp/customers/{identifier}/insights:

Field	Meaning
ltv	Sum of the customer’s completed-order totals.
order_count	Count of completed orders.
aov	Average order value = ltv / order_count.
first_order_at / last_order_at	Earliest / latest completed-order timestamps.
currency_code	Currency of the completed orders.

A customer that resolves but has no completed orders yet returns the all-zero summary (ltv: "0.00", order_count: 0, aov: "0.00", timestamps and currency_code null) — a 200, not a 404.

Brand-wide — GET /cdp/insights/ltv:

Field	Meaning
total_revenue	Sum of every purchasing customer’s LTV.
customer_count	Distinct customers with at least one completed order (unattributed orders excluded).
average_ltv	total_revenue / customer_count.
distribution	Customer counts across fixed dollar LTV buckets (see below).

The distribution has five fixed, dollar-denominated buckets — 0-100, 100-250, 250-500, 500-1000, and 1000+. Each bucket is half-open [min, max), the top bucket is open-ended (max: null), every bucket is always present (even with count 0), and the bucket counts always sum to customer_count.

RFM

RFM scores three dimensions of purchasing behavior, each on a 1-5 scale:

• Recency — how recently the customer last ordered. More recent is better: a smaller gap since the last order scores higher.
• Frequency — how many completed orders. More orders score higher.
• Monetary — completed-order spend. Higher spend scores higher.

Scores are brand-relative — ranked quintile-style within your brand only. A 5 means the top group for your brand, not across the whole Voyage network. Named tiers (champion, loyal, new, at_risk, lapsed, promising, needs_attention) are derived from the scores.

For the tier rules and definitions, see RFM; for the brand-wide tier distribution, see Brand RFM. The per-customer scores and tier are also returned inline on Customer Insights under insights.rfm.

Product patterns

GET /cdp/insights/products ranks products over a selectable order-date window, two ways:

• top_by_revenue — products ranked by completed-order revenue.
• top_by_order_count — products ranked by how many completed orders included them.

Each product also carries a repeat_purchase_rate: the share of that product’s customers who bought it in two or more distinct orders. Line items come from your synced order data, so a product that has since been removed from the catalog still appears by its product_id and the title recorded on the order.

A single customer’s top products are also returned inline on Customer Insights under insights.top_products.

Churn and at-risk

GET /cdp/insights/at-risk flags customers whose purchase cadence has slipped, per customer:

Field	Meaning
days_since_last_order	Days since the customer’s most recent completed order.
median_inter_order_days	The median gap between that customer’s own consecutive orders.
brand_median_inter_order_days	The brand-wide median cadence — the fallback for single-order customers, who have no gaps of their own.
at_risk_score	days_since_last_order / effective_cadence (the customer’s own median, else the brand median).
at_risk	true when at_risk_score exceeds 2 — roughly twice the customer’s normal cadence.

Rows are sorted by at_risk_score descending, and the brand endpoint is paginated. The same churn signals for a single customer are returned inline on Customer Insights under insights.churn.

Per-customer vs brand-wide

Every insight comes in a per-customer form and a brand-wide form. Customer Insights bundles all four per-customer signals into one response — LTV & spend at the top level, plus insights.rfm, insights.top_products, and insights.churn. Each also has its own brand-wide endpoint.

Metric	Per customer	Brand-wide
LTV & spend	Customer Insights	Brand LTV
RFM	Customer Insights insights.rfm	Brand RFM
Products	Customer Insights insights.top_products	Product Insights
Churn / at-risk	Customer Insights insights.churn	At-Risk Customers