VYG Docs

Customers

GET/v1/customers/fields

Scope: customers:read.

View customer fields. Set catalog=fields-v1 to include standard fields, contact identifiers and custom attributes.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

catalog?string

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"  }}
GET/v1/customers

Scope: 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
AuthorizationBearer <token>

In: header

Query Parameters

limit?integer
cursor?string|null
sort?string|null
direction?string|null
min_orders?string|null
min_spend?string|null
last_order_before?string|null
last_order_after?string|null
band?|

90-day purchase propensity band: top, high, middle or low. Requires beta:cdp-predictions.

min_probability?|

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"  }}
GET/v1/customers/search

Scope: 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
AuthorizationBearer <token>

In: header

Query Parameters

query?string|null
limit?integer

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"  }}
GET/v1/customers/propensity-status

Scope: customers:read.

Read the brand purchase propensity model readiness and its data thresholds.

Authorization

bearerAuth
AuthorizationBearer <token>

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"  }}
POST/v1/customers/propensity-batch

Scope: customers:read.

Read 90-day purchase likelihood for a batch of LiveRecover contacts in this brand.

Authorization

bearerAuth
AuthorizationBearer <token>

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"  }}
GET/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
AuthorizationBearer <token>

In: header

Path Parameters

id*string

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"  }}
GET/v1/customers/{id}/timeline

Scope: 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
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

limit?integer
cursor?string|null
event_type?string|null

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"  }}
GET/v1/customers/{id}/orders

Scope: customers:read.

View a customer’s orders, newest first, including linked profiles. Includes orders available in VYG.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

limit?integer
cursor?string|null

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"  }}
GET/v1/customers/{id}/subscriptions

Scope: customers:read.

View a customer’s subscriptions, newest first, including linked profiles.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

limit?integer
cursor?string|null

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"  }}
GET/v1/customers/{id}/segments

Scope: 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
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

cursor?string|null

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"  }}
POST/v1/customers/segments-batch

Scope: 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
AuthorizationBearer <token>

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"  }}