VYG Docs

Segments

GET/v1/events/catalog

Scope: segments:read.

View the events you can use in segment rules, grouped by where they come from, with whether each one is available for your store, when it last happened and how often in the last 30 days. Use an event id in a segment rule.

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/events/catalog"
{  "data": [    {      "id": "string",      "label": "string",      "availability": "connected",      "unavailable_reason": "string",      "entries": [        {          "id": "string",          "label": "string",          "verb": "string",          "description": "string",          "availability": "connected",          "unavailable_reason": "string",          "properties": [            {              "key": "string",              "label": "string",              "type": "text",              "operators": [                "string"              ],              "choices": [                {                  "value": "string",                  "label": "string"                }              ],              "suggest": "products"            }          ],          "activity": {            "last_seen_at": "string",            "count_30d": 0          }        }      ]    }  ],  "next_cursor": "string",  "activity_window_days": 0,  "activity_as_of": "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/events/campaigns

Scope: segments:read.

List the campaigns and flows a text-message segment rule can name, busiest first by texts sent and links clicked in the last 90 days. Use an option's value in the rule's campaign detail.

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/events/campaigns"
{  "data": [    {      "value": "string",      "label": "string",      "kind": "blast",      "status": "string",      "activity": {        "count": 0,        "last_seen_at": "string"      }    }  ],  "next_cursor": "string",  "activity_window_days": 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"  }}
GET/v1/segments/summaries

Scope: segments:read.

Read what the Segments list shows for each segment: people, a 30-day size trend from stored counts, last update time, a plain health hint, and the rule document. Newest first; filter by active, archived or all. Up to 200 per page by default, 500 at most; pass next_cursor as cursor for the next page.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

status?string|null
limit?integer
cursor?|

next_cursor from the previous page.

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/segments/summaries"
{  "data": [    {      "id": "string",      "name": "string",      "definition": {        "property1": null,        "property2": null      },      "people": 0,      "counting": true,      "size_series": [        {          "date": "string",          "people": 0        }      ],      "updated_at": "string",      "refresh_interval_minutes": 0,      "built_in": true,      "archived": true,      "health": {        "kind": "no_matches",        "message": "string",        "suggestion": "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/segments/estimate/batch

Scope: segments:read.

Check how many customers match each of up to 10 draft definitions at once, in one count. Give each definition a key; counts come back under the same keys. A definition with invalid rules gets a null count and a message saying what to fix. Results are cached for about 10 minutes.

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/segments/estimate/batch" \  -H "Content-Type: application/json" \  -d '{    "definitions": [      {        "key": "string",        "definition": {          "property1": null,          "property2": null        }      }    ]  }'
{  "counts": {    "property1": 0,    "property2": 0  },  "errors": {    "property1": "string",    "property2": "string"  },  "estimated_at": "string",  "cached": 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/segments/goal-defaults

Scope: segments:read.

Read the figures that size segment goals to this brand: the usual days between a repeat customer's orders, when repeat customers usually come back, and the total spend of the top 25% and top 10% of buyers. A figure is null when too few customers stand behind it. Updated every few hours.

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/segments/goal-defaults"
{  "reorder_gap_days": 0,  "repeat_window_days": {    "from": 0,    "to": 0  },  "spend_p75": 0,  "spend_p90": 0,  "buyers": 0,  "repeat_buyers": 0,  "computed_at": "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/segments

Scope: segments:read.

View saved customer segments, newest first, with their member counts and last update time. Filter by active, archived or all. Returns up to 200 segments per page by default, with a maximum of 500; pass next_cursor as cursor for the next page.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

status?string|null
limit?integer
cursor?|

next_cursor from the previous page.

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/segments"
{  "data": [    {      "id": "string",      "name": "string",      "description": "string",      "status": "active",      "current_version_id": "string",      "created_by": "string",      "built_in": true,      "refresh_interval_minutes": 0,      "created_at": "string",      "updated_at": "string",      "audience": {        "evaluation_status": "not_evaluated",        "member_count": 0,        "generation": 0,        "evaluated_at": "string",        "last_run_at": "string",        "current_version_evaluated": true      }    }  ],  "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/segments

Requires sign-in (OAuth). Scope: segments:write.

Create a customer segment using your chosen rules. Members update within the next 15-minute refresh. Use estimate_segment to check its size before saving. Invalid rules return the field that needs correcting.

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

application/json

curl -X POST "https://example.com/v1/segments" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "definition": {      "property1": null,      "property2": null    }  }'
{  "id": "string",  "name": "string",  "description": "string",  "status": "active",  "current_version_id": "string",  "created_by": "string",  "built_in": true,  "refresh_interval_minutes": 0,  "created_at": "string",  "updated_at": "string",  "audience": {    "evaluation_status": "not_evaluated",    "member_count": 0,    "generation": 0,    "evaluated_at": "string",    "last_run_at": "string",    "current_version_evaluated": true  },  "version": 0,  "schema_version": 0,  "definition": {    "property1": null,    "property2": null  }}
{  "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"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/segments/estimate

Scope: segments:read.

Check how many customers match a segment. Supply a draft definition or the ID of a saved segment. To preview an edit, supply both: the new definition and the segment it would replace; the result also says how many customers would join and leave. Results can take a few seconds.

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/segments/estimate" \  -H "Content-Type: application/json" \  -d '{}'
{  "count": 0,  "segment_id": "string",  "version": 0,  "estimated_at": "string",  "change": {    "current_count": 0,    "both_count": 0,    "joining": 0,    "leaving": 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"  }}
POST/v1/segments/count

Scope: segments:read.

Count the customers a draft segment definition matches: total, emailable (subscribed email channel), SMS (a2p marketing consent) and a small sample. A count that runs long returns partial=true; ask again with wait=true for the final counts.

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/segments/count" \  -H "Content-Type: application/json" \  -d '{    "definition": {      "property1": null,      "property2": null    }  }'
{  "total": 0,  "emailable": 0,  "sms": 0,  "sample": [    {      "customer_id": "string",      "email": "string",      "phone": "string"    }  ],  "computed_at": "string",  "partial": 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/segments/value

Scope: segments:read.

Order value of the customers a draft segment definition matches right now: total sales, orders, average order value and lifetime value, all time, completed orders in the brand primary currency. Same definitions as segments.audience with include=value. A failed read returns value_unavailable=true instead of an error.

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/segments/value" \  -H "Content-Type: application/json" \  -d '{    "definition": {      "property1": null,      "property2": null    }  }'
{  "value": {    "currency_code": "string",    "total_sales": "string",    "orders": 0,    "buyers": 0,    "aov": "string",    "ltv": "string"  },  "value_unavailable": true,  "computed_at": "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/segments/{id}

Scope: segments:read.

View a segment’s rules, version and latest member count.

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/segments/string"
{  "id": "string",  "name": "string",  "description": "string",  "status": "active",  "current_version_id": "string",  "created_by": "string",  "built_in": true,  "refresh_interval_minutes": 0,  "created_at": "string",  "updated_at": "string",  "audience": {    "evaluation_status": "not_evaluated",    "member_count": 0,    "generation": 0,    "evaluated_at": "string",    "last_run_at": "string",    "current_version_evaluated": true  },  "version": 0,  "schema_version": 0,  "definition": {    "property1": null,    "property2": null  }}
{  "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"  }}
PATCH/v1/segments/{id}

Requires sign-in (OAuth). Scope: segments:write.

Update a segment’s rules. Previous versions are kept. Archived and built-in segments cannot be edited; duplicate a built-in segment to customize it.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

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

application/json

curl -X PATCH "https://example.com/v1/segments/string" \  -H "Content-Type: application/json" \  -d '{    "definition": {      "property1": null,      "property2": null    }  }'
{  "id": "string",  "name": "string",  "description": "string",  "status": "active",  "current_version_id": "string",  "created_by": "string",  "built_in": true,  "refresh_interval_minutes": 0,  "created_at": "string",  "updated_at": "string",  "audience": {    "evaluation_status": "not_evaluated",    "member_count": 0,    "generation": 0,    "evaluated_at": "string",    "last_run_at": "string",    "current_version_evaluated": true  },  "version": 0,  "schema_version": 0,  "definition": {    "property1": null,    "property2": null  }}
{  "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"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/segments/{id}/archive

Requires sign-in (OAuth). Scope: segments:write.

Archive a segment to stop updates and remove it from the active list. Its history is kept and its name can be reused. Remove references from other active segments before archiving. Built-in segments cannot be archived.

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

application/json

curl -X POST "https://example.com/v1/segments/string/archive"
{  "id": "string",  "name": "string",  "description": "string",  "status": "active",  "current_version_id": "string",  "created_by": "string",  "built_in": true,  "refresh_interval_minutes": 0,  "created_at": "string",  "updated_at": "string",  "audience": {    "evaluation_status": "not_evaluated",    "member_count": 0,    "generation": 0,    "evaluated_at": "string",    "last_run_at": "string",    "current_version_evaluated": 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"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/segments/{id}/duplicate

Requires sign-in (OAuth). Scope: segments:write.

Copy a segment into a new segment you can edit, with the same rules. Use this to customize a built-in segment. The copy is named " (copy)" unless you pass a name, and its members update within the next 15-minute refresh.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

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

application/json

curl -X POST "https://example.com/v1/segments/string/duplicate" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "name": "string",  "description": "string",  "status": "active",  "current_version_id": "string",  "created_by": "string",  "built_in": true,  "refresh_interval_minutes": 0,  "created_at": "string",  "updated_at": "string",  "audience": {    "evaluation_status": "not_evaluated",    "member_count": 0,    "generation": 0,    "evaluated_at": "string",    "last_run_at": "string",    "current_version_evaluated": true  },  "version": 0,  "schema_version": 0,  "definition": {    "property1": null,    "property2": null  }}
{  "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"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/segments/{id}/audience

Scope: segments:read.

View a segment’s latest member count, update time and status. Segments you create refresh every 15 minutes; the built-in lifecycle segments refresh hourly (Visitors, Customers, Repeat Customers, Active Subscribers) or every 4 hours (High Value, At Risk, Churned). A new segment shows not_evaluated until its first update, within 15 minutes.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

include?string

value adds the order value of the published members (see value).

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/segments/string/audience"
{  "evaluation_status": "not_evaluated",  "member_count": 0,  "generation": 0,  "evaluated_at": "string",  "last_run_at": "string",  "current_version_evaluated": true,  "segment_id": "string",  "message": "string",  "value": {    "currency_code": "string",    "total_sales": "string",    "orders": 0,    "buyers": 0,    "aov": "string",    "ltv": "string"  },  "value_unavailable": 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/segments/{id}/members

Scope: segments:read.

View the customers in a segment, with their email, phone number, order count, total spend and last order date. Results reflect the latest segment update and are ordered by customer ID. Use cursor for the next page. The default page size is 100; the maximum is 5,000.

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/segments/string/members"
{  "data": [    {      "customer_id": "string",      "email": "string",      "phone": "string",      "lr_contact_id": "string",      "joined_at": "string",      "orders_count": 0,      "total_spend": 0,      "currency": "string",      "last_order_at": "string"    }  ],  "next_cursor": "string",  "generation": 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"  }}
GET/v1/segments/{id}/history

Scope: segments:read.

See who joined or left a segment, newest updates first. Filter by customer_id to include a customer’s linked profiles. Use cursor for the next page. The default page size is 100; the maximum is 1,000. History covers 180 days.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

customer_id?string|null
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/segments/string/history"
{  "data": [    {      "customer_id": "string",      "email": "string",      "phone": "string",      "current_customer_id": "string",      "action": "entered",      "reason": "string",      "generation": 0,      "changed_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"  }}