VYG Docs

Customers

Customer fields

GET/v1/customers/fields

Scope: customers:read. MCP tool: list_customer_fields.

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

List customers

GET/v1/customers

Scope: customers:read. MCP tool: list_customers.

View customers with spending, order counts and recent activity. Sort by spending, order count, date added, last order or last activity. Filter by minimum orders or spending. 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

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

Find a customer

GET/v1/customers/search

Scope: customers:read. MCP tool: search_customers.

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

Customer profile

GET/v1/customers/{id}

Scope: customers:read. MCP tool: get_customer.

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",  "identities": [    {      "type": "string",      "value": "string",      "source": "string",      "verified": true    }  ],  "merged_customer_ids": [    "string"  ],  "first_order_at": "string",  "name_lookup_failed": true,  "rfm_group": "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"  }}

Customer activity

GET/v1/customers/{id}/timeline

Scope: customers:read. MCP tool: get_customer_activity.

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

Customer order history

GET/v1/customers/{id}/orders

Scope: customers:read. MCP tool: list_customer_orders.

View a customer’s orders, newest first, including linked profiles. Includes orders available in VYG. To view orders across your store, use list_orders.

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

Customer subscriptions

GET/v1/customers/{id}/subscriptions

Scope: customers:read. MCP tool: list_customer_subscriptions.

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

Customer's segments

GET/v1/customers/{id}/segments

Scope: segments:read. MCP tool: list_customer_segments.

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

Conversations

Previous Page

Segments

Next Page