Customers
/v1/customers/fieldsScope: customers:read.
View customer fields. Set catalog=fields-v1 to include standard fields, contact identifiers and custom attributes.
Authorization
bearerAuth In: header
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/fields"{ "data": [ { "key": "string", "type": "string", "label": "string", "source": "string", "writable": true, "read_only_reason": "string" } ], "next_cursor": "string", "catalog_version": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customersScope: customers:read.
View customers with spending, order counts and recent activity. Sort by spending, order count, date added, last order, last activity or purchase propensity band. Filter by minimum orders or spending, or by 90-day purchase propensity band and minimum probability when beta:cdp-predictions is enabled. Order totals refresh about every 15 minutes; coverage_from shows the start of the available history.
Authorization
bearerAuth In: header
Query Parameters
90-day purchase propensity band: top, high, middle or low. Requires beta:cdp-predictions.
Minimum 90-day purchase probability from 0 to 1. Requires beta:cdp-predictions.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers"{ "data": [ { "id": "string", "created_at": "string", "email": "string", "phone": "string", "lr_contact_id": "string", "name": { "given": "string", "family": "string", "display": "string" }, "currency": "string", "orders_count": 0, "total_spend": 0, "total_refunded": 0, "last_order_at": "string", "coverage_from": "string", "events_30d": 0, "sessions_30d": 0, "product_views_30d": 0, "last_event_at": "string", "lifecycle": "prospect", "average_order_value": 0, "identity_source": "shopify", "first_order_utm_source": "string", "purchase_likelihood": { "probability": 0, "band": "top", "horizon": "90d", "model": "string", "reasons": [ "string" ], "computed_at": "string" } } ], "next_cursor": "string", "name_lookup_failed": true}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customers/searchScope: customers:read.
Find customers by email, phone number or customer ID. Enter at least three characters to match the start of an email, phone number or external ID. Returns up to 25 results, highest spend first.
Authorization
bearerAuth In: header
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/search"{ "data": [ { "id": "string", "created_at": "string", "email": "string", "phone": "string", "lr_contact_id": "string", "name": { "given": "string", "family": "string", "display": "string" }, "currency": "string", "orders_count": 0, "total_spend": 0, "total_refunded": 0, "last_order_at": "string", "coverage_from": "string", "events_30d": 0, "sessions_30d": 0, "product_views_30d": 0, "last_event_at": "string", "lifecycle": "prospect", "average_order_value": 0, "identity_source": "shopify", "first_order_utm_source": "string", "purchase_likelihood": { "probability": 0, "band": "top", "horizon": "90d", "model": "string", "reasons": [ "string" ], "computed_at": "string" } } ], "next_cursor": "string", "name_lookup_failed": true}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customers/propensity-statusScope: customers:read.
Read the brand purchase propensity model readiness and its data thresholds.
Authorization
bearerAuth In: header
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/propensity-status"{ "model_readiness": { "buyers_28d": 0, "buyers_required": 2000, "windows_collected": 0, "windows_required": 12, "model": "heuristic", "ready": true }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customers/propensity-batchScope: customers:read.
Read 90-day purchase likelihood for a batch of LiveRecover contacts in this brand.
Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/customers/propensity-batch" \ -H "Content-Type: application/json" \ -d '{ "contact_ids": [ "f4ae0292-6c1e-4caf-903f-b55ea2c1670a" ] }'{ "data": [ { "contact_id": "f245e2a3-e141-4d41-912c-b1c1f5bd5598", "purchase_likelihood": { "probability": 0, "band": "top" } } ]}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customers/{id}Scope: customers:read.
View a customer’s contact details, order totals and recent activity. Linked profiles are included in their combined history.
Authorization
bearerAuth In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/string"{ "id": "string", "created_at": "string", "email": "string", "phone": "string", "lr_contact_id": "string", "name": { "given": "string", "family": "string", "display": "string" }, "currency": "string", "orders_count": 0, "total_spend": 0, "total_refunded": 0, "last_order_at": "string", "coverage_from": "string", "events_30d": 0, "sessions_30d": 0, "product_views_30d": 0, "last_event_at": "string", "lifecycle": "prospect", "average_order_value": 0, "identity_source": "shopify", "first_order_utm_source": "string", "purchase_likelihood": { "probability": 0, "band": "string", "horizon": "90d", "model": "string", "reasons": [ "string" ], "computed_at": "string", "items": [ { "line_id": "string", "product_key": "string", "title": "string", "band": "string", "probability": 0 } ] }, "identities": [ { "type": "string", "value": "string", "source": "string", "verified": true } ], "merged_customer_ids": [ "string" ], "first_order_at": "string", "name_lookup_failed": true, "rfm_group": "string", "location": { "city": "string", "region": "string", "country": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customers/{id}/timelineScope: customers:read.
View a customer’s activity, newest first: website visits, orders, subscriptions and messages. Filter with event_type. Includes activity from linked profiles.
Authorization
bearerAuth In: header
Path Parameters
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/string/timeline"{ "data": [ { "event_key": "string", "occurred_at": "string", "event_type": "string", "source_system": "string", "entity_kind": "string", "entity_key": "string", "currency": "string", "amount": 0, "status": "string", "product_key": "string", "page_path": "string", "page_title": "string", "referrer_host": "string", "utm_source": "string", "utm_medium": "string", "utm_campaign": "string", "session_id": "string" } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customers/{id}/ordersScope: customers:read.
View a customer’s orders, newest first, including linked profiles. Includes orders available in VYG.
Authorization
bearerAuth In: header
Path Parameters
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/string/orders"{ "data": [ { "order_key": "string", "created_at": "string", "updated_at": "string", "source_system": "string", "status": "string", "financial_status": "string", "fulfillment_status": "string", "currency": "string", "subtotal": 0, "total": 0, "refunded": 0, "items": [ { "line_id": "string", "product_key": "string", "variant_key": "string", "title": "string", "quantity": 0, "unit_price": 0 } ] } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customers/{id}/subscriptionsScope: customers:read.
View a customer’s subscriptions, newest first, including linked profiles.
Authorization
bearerAuth In: header
Path Parameters
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/string/subscriptions"{ "data": [ { "subscription_key": "string", "created_at": "string", "updated_at": "string", "source_system": "string", "status": "string", "currency": "string", "amount": 0, "billing_interval": "string", "next_billing_at": "string", "items": [ { "line_id": "string", "product_key": "string", "variant_key": "string", "title": "string", "quantity": 0, "unit_price": 0 } ] } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customers/{id}/segmentsScope: segments:read.
View the active segments a customer currently belongs to, most recently joined first. Archived segments are excluded. Returns up to 100 segments per page; pass next_cursor as cursor for the next page.
Authorization
bearerAuth In: header
Path Parameters
Query Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/string/segments"{ "data": [ { "id": "string", "name": "string", "joined_at": "string" } ], "next_cursor": "string"}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}/v1/customers/segments-batchScope: segments:read.
View the active segments of up to 100 customers at once: for each, the 3 most recently joined and the total count. Archived segments are excluded.
Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/customers/segments-batch" \ -H "Content-Type: application/json" \ -d '{ "ids": [ "string" ] }'{ "data": [ { "customer_id": "string", "segments": [ { "id": "string", "name": "string" } ], "segment_count": 0 } ]}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}{ "error": { "code": "bad_request", "message": "string" }}