MCPToolsCDP tools
Find Customers
Filter and rank your whole customer base
cdp_find_customers
Filters and ranks your entire customer base over the materialized CDP profiles — order and spend facts, engagement, recency, and derived tags. It answers questions like "top 50 spenders," "high-value customers who have gone quiet," or "lapsed repeat buyers" in one call. Each row carries enough (customer id, email/phone, spend facts, tags) to act on without a second lookup.
All filters are optional and combinable. Read-only and hard-scoped to your brand.
Parameters
| Name | Type | Required | Description | Default |
|---|---|---|---|---|
tags | string[] | No | Any-of tag match: keep customers carrying at least one of these tags (e.g. ["high_value"]). | — |
total_spend_min | number | No | Keep customers whose total spend is ≥ this amount. | — |
total_spend_max | number | No | Keep customers whose total spend is ≤ this amount. | — |
orders_count_min | number | No | Keep customers whose order count is ≥ this. | — |
orders_count_max | number | No | Keep customers whose order count is ≤ this. | — |
recency_days_min | number | No | Keep customers whose recency (days since last activity) is ≥ this (gone quiet). | — |
recency_days_max | number | No | Keep customers whose recency is ≤ this (recently active). | — |
engagement_score_min | number | No | Keep customers whose engagement score is ≥ this. | — |
engagement_score_max | number | No | Keep customers whose engagement score is ≤ this. | — |
last_order_from | string | No | Keep customers whose last order is ≥ this ISO-8601 timestamp. | — |
last_order_to | string | No | Keep customers whose last order is ≤ this ISO-8601 timestamp. | — |
sort | string | No | Sort field: total_spend, orders_count, recency_days, engagement_score, or last_interaction_at. | total_spend |
direction | string | No | asc or desc. | desc |
limit | number | No | Max rows, clamped to 100. | 25 |
offset | number | No | Offset for offset-based paging. | 0 |
Returns
- The matching customers, each with customer id, primary identities (email/phone where present), spend facts, and tags.
- Paging metadata, including a
nextOffsetthat points at the next page when a full page is returned. coverage—{ since, note }, the brand's order-data coverage floor. Thetotal_spend/orders_count/recencyfacts are CDP-witnessed since this date, not lifetime Shopify history.
Example prompts
Who are my top 25 customers by total spend?Show me high-value customers who haven't ordered in 60+ daysList customers tagged lapsed or high_value, sorted by engagementNotes
tagsis an any-of match — a customer is kept if they carry at least one of the listed tags.limitis clamped to 100 rather than rejected — asking for more simply returns the cap.- Every query is hard-scoped to your brand id, so results only ever include your own customers.
- Spend, order-count, and recency filters range only over what the CDP has witnessed since
coverage.since— for lifetime/all-time questions (e.g. "customers with more than 5 orders"), useshopify_admin_graphqlinstead.