Find Customers

Filter and rank your brand's whole customer base — top spenders, lapsed, by tag, spend, or recency — in one call.

POST /cdp/customers/find filters and ranks your brand's entire customer base over the materialized CDP profiles (order/spend facts, engagement, recency + 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 to act without a second lookup. It is the REST twin of the cdp_find_customers MCP tool: both return the same data, computed by one shared capability, so the two surfaces cannot drift.

Every read is bound to your brand's shop scope. See Tenant Isolation & Scope.

Request

POST /cdp/customers/find
Authorization: Bearer vyg_…
Content-Type: application/json

All fields are optional and combinable. Omit the body to page the whole base by the default sort.

Field	Type	Default	Description
`tags`	string[]	—	Any-of tag match: keep customers carrying at least one of these derived tags.
`total_spend_min`	number	—	Keep customers whose `total_spend` is `>=` this amount.
`total_spend_max`	number	—	Keep customers whose `total_spend` is `<=` this amount.
`orders_count_min`	integer	—	Keep customers whose `orders_count` is `>=` this.
`orders_count_max`	integer	—	Keep customers whose `orders_count` is `<=` this.
`recency_days_min`	integer	—	Keep customers whose `recency_days` is `>=` this (gone quiet).
`recency_days_max`	integer	—	Keep customers whose `recency_days` is `<=` this (recently active).
`engagement_score_min`	number	—	Keep customers whose `engagement_score` is `>=` this.
`engagement_score_max`	number	—	Keep customers whose `engagement_score` is `<=` this.
`last_order_from`	string	—	Keep customers whose `last_order_at` is `>=` this ISO-8601 timestamp.
`last_order_to`	string	—	Keep customers whose `last_order_at` is `<=` this ISO-8601 timestamp.
`sort`	string	`total_spend`	One of `total_spend`, `orders_count`, `recency_days`, `engagement_score`, `last_interaction_at`. Any other value returns `400`.
`direction`	string	`desc`	`asc` or `desc`.
`limit`	integer	`25`	Page size, clamped to `[1, 100]` — an over-cap value is clamped, never rejected.
`offset`	integer	`0`	Offset for offset-based paging.

{
	"tags": ["high_value"],
	"total_spend_min": 100,
	"sort": "total_spend",
	"direction": "desc",
	"limit": 5
}

Response `200`

{
	"list": [
		{
			"customerId": "8f2b…",
			"email": "jane@example.com",
			"phone": "+15551234567",
			"ordersCount": 12,
			"totalSpend": 1840.5,
			"aov": 153.38,
			"currency": "USD",
			"firstOrderAt": "2024-02-01T10:00:00.000Z",
			"lastOrderAt": "2026-06-20T14:30:00.000Z",
			"recencyDays": 19,
			"engagementScore": 88.2,
			"lastInteractionAt": "2026-06-30T09:12:00.000Z",
			"tags": ["high_value", "repeat"]
		}
	],
	"limit": 5,
	"offset": 0,
	"nextOffset": 5,
	"sort": "total_spend",
	"direction": "desc",
	"scope": "your-shop.myshopify.com"
}

list — the matching customers, each enriched with primary email / phone, order and spend facts, engagement/recency signals, and derived tags.
limit / offset — the effective paging window (after clamping).
nextOffset — offset + limit when the page came back full (there may be more), else null (the walk is exhausted).
sort / direction — the effective ordering applied.
scope — your brand's resolved shop domain.

Example

curl -s -X POST "https://cdp.vyg.app/cdp/customers/find" \
  -H "Authorization: Bearer vyg_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"sort":"total_spend","direction":"desc","limit":5}'

Errors

Status	When
`400`	Malformed body, or a filter references a disallowed property (`bad_request`).
`401`	Missing or invalid credential.
`403`	No connected Shopify integration resolves a scope for the brand.
`405`	Non-`POST` method.
`503`	The CDP is temporarily unavailable — retry (`upstream_unavailable`).

Request

Response 200

Example

Errors

On this page

Response `200`