Insights
Understand customer spending, buying habits and repeat purchases.
Use insights to understand customer spending, buying habits, popular products and customers who may need a follow-up.
When reading these metrics:
- Completed orders only. Every metric is computed over orders in
state = "complete". Pending, draft, delivered, cancelled, and refunded orders are excluded. See Commerce data. - Decimal strings. Money is a decimal string in the store's currency
(e.g.
"300.00"), never cents. - For reporting and personalization, not financial settlement.
LTV and spend
Lifetime value is the sum of a customer's completed-order totals.
GET /v1/insights/ltv summarizes customer spending:
| 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 LTV buckets in the store's currency (see below). |
The distribution has five fixed buckets in the store's currency — 0-100, 100-250,
250-500, 500-1000, and 1000+. Each range includes its lower bound and excludes its upper bound. The last range has no upper
limit (max: null). All five ranges appear, including empty ones; their counts 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 compare purchasing behavior within your customer base. A 5
means the highest-scoring group. Named
tiers (champion, loyal, new, at_risk, lapsed, promising,
needs_attention) are derived from the scores.
The tier rules are below. The customer group breakdown is
GET /v1/insights/rfm, which is the
get_rfm_tiers MCP tool. These RFM tiers are not the same as saved
segments, which are rules you define.
RFM tiers
| Tier | Rule |
|---|---|
champion | R >= 4, F >= 4, M >= 4 |
loyal | F >= 4, M >= 3 |
new | R >= 4, F <= 2 |
at_risk | R <= 2, F >= 3 |
lapsed | R <= 2 |
promising | R >= 3 |
needs_attention | fallback |
Rules are checked top to bottom; a customer gets the first tier whose rule matches. R, F and M are the
recency_score, frequency_score and monetary_score, each from 1 to 5.
Product patterns
GET /v1/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 order history, so a product that has since been removed from the catalog
still appears by its product_id and the title recorded on the order.
Churn and at-risk
GET /v1/insights/at-risk lists
customers who completed purchases on at least two different days and have gone more
than twice their usual interval without ordering. Customers with only one purchase day
are excluded from this list.
| Field | Meaning |
|---|---|
days_since_last_order | Days since the customer's most recent completed order. |
median_inter_order_days | Median gap between the customer's purchase days. |
brand_median_inter_order_days | Store-wide median purchase interval, provided for context. |
at_risk_score | days_since_last_order / median_inter_order_days. |
at_risk | true when at_risk_score is greater than 2. |
Rows are sorted by at_risk_score descending. The endpoint returns { data, next_cursor }; pass
next_cursor back as cursor for the next page (see Pagination).