Queek docs
Merchant endpoint reference

Customers

GET
/customers

Requires scope merchant-customers-read.

Lists customers with cursor pagination (limit up to 100 + starting_after, has_more/next_cursor); profile fields match customers/* webhooks and email_marketing_consent and sms_marketing_consent are present only with merchant-customers-contact-read. Use audience=campaign to include non-buyers; that mode requires the contact scope. not_opted_out means only that the person has not used Queek’s email unsubscribe; it is not permission to send. An import that stores info.marketing_opt_in=false excludes that contact from email campaigns only; SMS reachability is unchanged. Optional updated_after walks customer rows changed after a timestamp, oldest change first, by each customer’s updated_at (second precision); start each poll five minutes before the previous poll start, deduplicate ids, keep filters fixed and walk sequentially. With updated_after, sort_by, sort_order, page and per_page return 422; a cursor is bound to the same timestamp and filters. Changes stored outside the customer record (order history, consent changes recorded elsewhere) and deleted customers may be missed. The filter time is not returned; this is not a snapshot or deletion feed.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

from_date?|

Only customers added to the store on or after this day (YYYY-MM-DD, by the day the customer record was created). Ignored when date_range is sent.

Formatdate
to_date?|

Only customers added to the store on or before this day, inclusive (YYYY-MM-DD). Must not be earlier than from_date. Ignored when date_range is sent.

Formatdate
date_range?|

One of today, this_week, this_month.

Value in

  • "today"
  • "this_week"
  • "this_month"
  • null
audience?|

One of campaign.

Value in

  • "campaign"
  • null
search?|

Free-text filter: only items matching this text are returned.

Lengthlength <= 255
tag?|

Only customers carrying this tag (one of the store's own customer tags; matching ignores case).

Lengthlength <= 255
sort_by?|

Field to sort the list by. One of created_at, updated_at, joined_date, name, email, phone, p_id, customer_orders_count.

Value in

  • "created_at"
  • "updated_at"
  • "joined_date"
  • "name"
  • "email"
  • "phone"
  • "p_id"
  • "customer_orders_count"
  • null
sort_order?|

Sort direction. One of asc, desc.

Value in

  • "asc"
  • "desc"
  • null
updated_after?string

Only items changed after this ISO-8601 timestamp.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers?limit=2&sort_by=created_at&sort_order=desc" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": 90342,      "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a62",      "name": "Sam Rivera",      "email": "[email protected]",      "phone": "+12025550149",      "avatar": null,      "tags": [],      "metafields": {},      "created_at": "2026-08-11T08:40:00+01:00",      "updated_at": "2026-09-18T20:02:00+01:00",      "email_marketing_consent": {        "state": "not_opted_out",        "consent_updated_at": null      },      "sms_marketing_consent": {        "state": "not_subscribed",        "opt_in_level": null,        "consent_updated_at": null      }    },    {      "id": 90341,      "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a61",      "name": "Alex Morgan",      "email": "[email protected]",      "phone": "+12025550148",      "avatar": null,      "tags": [        "vip",        "wholesale"      ],      "metafields": {},      "created_at": "2026-07-03T19:12:00+01:00",      "updated_at": "2026-09-24T12:58:00+01:00",      "email_marketing_consent": {        "state": "not_opted_out",        "consent_updated_at": null      },      "sms_marketing_consent": {        "state": "not_subscribed",        "opt_in_level": null,        "consent_updated_at": null      }    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6OTAzNDEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}
GET
/customers/followers

Requires scope merchant-customers-read.

Lists the store’s followers; a follower who is a customer carries its customer id. Contact shows only when shared or a customer, and is masked without the contact scope.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 50
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

search?|

Free-text filter: only items matching this text are returned.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/followers?limit=2" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": "019a2f33-1a2b-7c3d-8e4f-5a6b7c8d9e02",      "customer_id": null,      "name": "Taylor Brooks",      "email": "[email protected]",      "phone": "+12025550150",      "avatar": "https://media.usequeek.com/uploads/avatars/taylor-brooks.jpg",      "shared_contact": true,      "is_customer": false,      "followed_at": "2026-09-21T11:30:00+01:00"    },    {      "id": "019a2f33-1a2b-7c3d-8e4f-5a6b7c8d9e01",      "customer_id": 90341,      "name": "Alex Morgan",      "email": "[email protected]",      "phone": "+12025550148",      "avatar": "https://media.usequeek.com/uploads/avatars/alex-morgan.jpg",      "shared_contact": false,      "is_customer": true,      "followed_at": "2026-07-03T19:15:00+01:00"    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6IjAxOWEyZjMzLTFhMmItN2MzZC04ZTRmLTVhNmI3YzhkOWUwMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}
GET
/customers/{customer}

Requires scope merchant-customers-detail.

Retrieves one customer — the profile fields match customers/* webhooks; email_marketing_consent and sms_marketing_consent are present only with merchant-customers-contact-read. {customer} is this store’s p_id, uid, or user id. Contact fields are masked without the contact scope.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

customer*string

Identifier of the customer, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/90341" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Customer retrieved",  "data": {    "id": 90341,    "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a61",    "name": "Alex Morgan",    "email": "[email protected]",    "phone": "+12025550148",    "avatar": null,    "tags": [      "vip",      "wholesale"    ],    "metafields": {},    "created_at": "2026-07-03T19:12:00+01:00",    "updated_at": "2026-09-24T12:58:00+01:00",    "email_marketing_consent": {      "state": "not_opted_out",      "consent_updated_at": null    },    "sms_marketing_consent": {      "state": "not_subscribed",      "opt_in_level": null,      "consent_updated_at": null    }  }}
POST
/customers/{customer}/email-marketing-consent

Requires scope merchant-customers-consent-update.

Records Queek email unsubscribe or app-reported opt-in evidence. Clearing a Queek unsubscribe re-enables the vendor’s own campaign email. To clear it, send state=not_opted_out with source, opt_in_level and consent_updated_at strictly later than the stored unsubscribe and no later than the allowed clock skew; the customer must have a non-empty email. Otherwise the response is 422 with an email or consent_updated_at field error. state=unsubscribed needs no evidence fields. The 200 response contains only id and email_marketing_consent.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

customer*string

Identifier of the customer, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

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

curl -X POST "https://example.com/customers/90341/email-marketing-consent" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "state": "unsubscribed"  }'
{  "id": 90341,  "email_marketing_consent": {    "state": "unsubscribed",    "opt_in_level": null,    "consent_updated_at": "2026-10-04T10:00:00+01:00"  }}
POST
/customers/{customer}/sms-marketing-consent

Requires scope merchant-customers-sms-consent-update.

Records explicit app-reported SMS marketing consent for this customer. state=subscribed requires source, opt_in_level, consent_updated_at, and a valid phone number; state=unsubscribed needs no evidence fields or phone. Future unsubscribe timestamps are treated as the current time. The stored consent time never moves backward; an unsubscribe older than the existing time keeps the existing time. If an earlier subscribe time is still future-dated, the response may retain that time to preserve consent ordering. The 200 response contains only id and sms_marketing_consent. This operation does not send SMS.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

customer*string

Identifier of the customer, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

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

curl -X POST "https://example.com/customers/90341/sms-marketing-consent" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "state": "unsubscribed"  }'
{  "id": 90341,  "sms_marketing_consent": {    "state": "unsubscribed",    "opt_in_level": null,    "consent_updated_at": "2026-10-04T10:00:00+01:00"  }}
PUT
/customers/{customer}/tags

Requires scope merchant-customers-update.

Replaces the customer’s tags with the list you send: the tags you send become the whole list, so a tag you leave out is removed and [] clears them all. Send tags every time (omitting it answers 422). A customer has at most 250 tags of up to 255 characters each, and one call sets at most 100 tags; tags are trimmed, lowercased and deduplicated, so VIP and vip are one tag, and the customer object answers them sorted. Tags are private to this store: they are the same tags the merchant sees and filters by in the dashboard, and another store’s tags never mix with them. Two writers at the same moment are last-write-wins, so read the customer, change the list, and send the whole list back. Fires customers/update only when the list actually changed; the same list again changes nothing and fires nothing. {customer} is a p_id or UUID of this store’s customer; another store’s customer, a team member and a subscriber who has never bought answer 404 Customer not found. Answers the customer as GET customers/{customer} reads it, with the new tags. Send an Idempotency-Key so a retried call replays the first answer.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

customer*string

Identifier of the customer, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Replace a customer's tags with the list you send.

Send tags every time: the list you send becomes the whole list, and [] clears it. One call sets at most 100 tags of up to 255 characters each.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/customers/90341/tags" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "tags": [      "vip",      "wholesale"    ]  }'
{  "status": "success",  "message": "Customer tags updated",  "data": {    "id": 90341,    "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a61",    "name": "Alex Morgan",    "email": "[email protected]",    "phone": "+12025550148",    "avatar": null,    "tags": [      "vip",      "wholesale"    ],    "metafields": {},    "created_at": "2026-07-03T19:12:00+01:00",    "updated_at": "2026-09-24T12:58:00+01:00",    "email_marketing_consent": {      "state": "not_opted_out",      "consent_updated_at": null    },    "sms_marketing_consent": {      "state": "not_subscribed",      "opt_in_level": null,      "consent_updated_at": null    }  }}
GET
/customers/{customer}/wishlist-items

Requires scope merchant-customers-detail.

Lists this store customer’s saved products with cursor pagination at the price the storefront customer saw. The merchant and apps holding merchant-customers-detail can read these saved items.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

customer*string

Identifier of the customer, as returned by the Merchant API.

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/90341/wishlist-items?limit=2&starting_after=eyJjdXN0b21lcl93aXNobGlzdF9pdGVtcy5jcmVhdGVkX2F0IjoiMjAyNi0wOS0yNCAxMjowMDowMCIsImN1c3RvbWVyX3dpc2hsaXN0X2l0ZW1zLmlkIjoiMDE5YTFkNTItM2M4ZS03ZjQxLWIwZDItNmEzZTljMWY0YjI4IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "created_at": "2026-09-20T11:00:00+01:00",      "product": {        "shop_id": "019a0b3a-af57-72d0-9c13-7036c3805892",        "id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22",        "p_id": 20418,        "title": "Fresh Lemonade",        "slug": "fresh-lemonade",        "excerpt": "Fresh lemonade with mint and lemon slices.",        "description": "Our house lemonade, mixed fresh every morning. Served chilled.",        "image": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp",        "thumbnail_image": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp",        "video_url": null,        "video_poster_url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp",        "type": null,        "commerce_mode": "shop",        "currency": "USD",        "price": "5.75",        "discount_price": "5.75",        "compare_at_price": null,        "is_price_from": true,        "price_range": {          "min": "5.75",          "max": "9.66"        },        "has_variants": true,        "has_addons": false,        "tax_inclusive": false,        "purchase_mode": "buy",        "negotiable": false,        "price_per": null,        "discount": null,        "discounts": [],        "media": {          "thumbnail": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp",          "image": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp",          "original": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",          "primary_variant_image": null,          "image_variants": {            "thumb": {              "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp",              "w": null,              "h": null            },            "card": {              "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp",              "w": 480,              "h": 480            },            "card2x": {              "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card2x.webp",              "w": 800,              "h": 800            },            "view": {              "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp",              "w": 1200,              "h": 1200            },            "wa": {              "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg",              "w": 1080,              "h": 1080            },            "original": {              "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",              "w": 1200,              "h": 1200            }          },          "primary_variant_image_variants": null,          "images": [            {              "id": 88220,              "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp",              "alt": "Two bottles of chilled lemonade with lemon slices",              "variants": {                "thumb": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp",                  "w": null,                  "h": null                },                "card": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp",                  "w": 480,                  "h": 480                },                "card2x": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card2x.webp",                  "w": 800,                  "h": 800                },                "view": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp",                  "w": 1200,                  "h": 1200                },                "wa": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg",                  "w": 1080,                  "h": 1080                },                "original": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",                  "w": 1200,                  "h": 1200                }              }            }          ],          "video_url": null,          "video_poster_url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp"        },        "inventory": {          "in_stock": true,          "tracking": true,          "quantity": 60,          "allow_backorder": false,          "low_stock_threshold": 5,          "updated_at": "2026-09-22T16:05:00+01:00"        },        "variant_summary": {          "count": 2,          "min_price": "5.75",          "max_price": "9.66",          "total_stock": 60,          "tracks_inventory": true,          "in_stock": true        },        "variants_count": 2,        "rating": 4.8,        "review_count": 14,        "flags": {          "featured": false,          "is_marketplace": false,          "is_new": false        },        "metafields": {},        "created_at": "2026-07-15T11:30:00+01:00",        "updated_at": "2026-09-22T16:05:00+01:00",        "shop": {          "id": "019a0b3a-af57-72d0-9c13-7036c3805892",          "name": "Northwind Goods",          "slug": "northwind-goods",          "logo": "https://media.usequeek.com/uploads/stores/1095/logo.png",          "rating": 4.8,          "rating_count": 231        },        "addons": [],        "latest_reviews": [],        "taxonomy": {          "categories": [],          "tags": [],          "brand": null,          "collections": []        },        "purchase_limits": {          "min_qty": 1,          "max_qty": null,          "step_qty": 1        },        "measurement": {          "weight": null,          "dimensions": null        },        "specs": [],        "options": [          {            "name": "Size",            "position": 0,            "type": "size",            "values": [              "16 oz",              "32 oz"            ],            "values_detailed": [              {                "value": "16 oz",                "color_code": null,                "image": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg"              },              {                "value": "32 oz",                "color_code": null,                "image": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg"              }            ]          }        ],        "variants": [          {            "id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31",            "sku": "NWG-LEM-16OZ",            "barcode": "0012345137001",            "title": "16 oz",            "option_values": {              "Size": "16 oz"            },            "price": "5.75",            "discount_price": "5.75",            "discount_amount": "0.00",            "has_discount": false,            "compare_at_price": null,            "stock": 36,            "track_inventory": true,            "is_active": true,            "in_stock": true,            "weight": 0.55,            "position": 0,            "media": {              "thumbnail": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",              "image": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",              "image_media_id": null,              "image_variants": {                "thumb": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp",                  "w": null,                  "h": null                },                "card": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp",                  "w": 480,                  "h": 480                },                "card2x": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card2x.webp",                  "w": 800,                  "h": 800                },                "view": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp",                  "w": 1200,                  "h": 1200                },                "wa": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg",                  "w": 1080,                  "h": 1080                },                "original": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",                  "w": 1200,                  "h": 1200                }              },              "images": [                {                  "id": 88220,                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp",                  "alt": "Two bottles of chilled lemonade with lemon slices",                  "variants": {                    "thumb": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp",                      "w": null,                      "h": null                    },                    "card": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp",                      "w": 480,                      "h": 480                    },                    "card2x": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card2x.webp",                      "w": 800,                      "h": 800                    },                    "view": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp",                      "w": 1200,                      "h": 1200                    },                    "wa": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg",                      "w": 1080,                      "h": 1080                    },                    "original": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",                      "w": 1200,                      "h": 1200                    }                  }                }              ],              "video_url": null,              "source": "product"            },            "metafields": {}          },          {            "id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32",            "sku": "NWG-LEM-32OZ",            "barcode": "0012345137002",            "title": "32 oz",            "option_values": {              "Size": "32 oz"            },            "price": "9.66",            "discount_price": "9.66",            "discount_amount": "0.00",            "has_discount": false,            "compare_at_price": null,            "stock": 24,            "track_inventory": true,            "is_active": true,            "in_stock": true,            "weight": 1.05,            "position": 1,            "media": {              "thumbnail": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",              "image": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",              "image_media_id": null,              "image_variants": {                "thumb": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp",                  "w": null,                  "h": null                },                "card": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp",                  "w": 480,                  "h": 480                },                "card2x": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card2x.webp",                  "w": 800,                  "h": 800                },                "view": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp",                  "w": 1200,                  "h": 1200                },                "wa": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg",                  "w": 1080,                  "h": 1080                },                "original": {                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",                  "w": 1200,                  "h": 1200                }              },              "images": [                {                  "id": 88220,                  "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp",                  "alt": "Two bottles of chilled lemonade with lemon slices",                  "variants": {                    "thumb": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-thumb.webp",                      "w": null,                      "h": null                    },                    "card": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card.webp",                      "w": 480,                      "h": 480                    },                    "card2x": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-card2x.webp",                      "w": 800,                      "h": 800                    },                    "view": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-view.webp",                      "w": 1200,                      "h": 1200                    },                    "wa": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade-wa.jpg",                      "w": 1080,                      "h": 1080                    },                    "original": {                      "url": "https://media.usequeek.com/uploads/stores/1095/fresh-lemonade.jpg",                      "w": 1200,                      "h": 1200                    }                  }                }              ],              "video_url": null,              "source": "product"            },            "metafields": {}          }        ],        "fulfillment": {          "type": "delivery_or_pickup",          "is_digital": false,          "delivery_available": true,          "pickup_available": true,          "lead_time_min": null,          "lead_time_max": null        },        "compliance": {          "warranty_months": 0,          "country_of_origin": null,          "safety_notes": null        },        "seo": null,        "analytics": {          "sales_count": 31,          "view_count": 218,          "favorite_count": 0,          "review_count": 14        }      },      "variant": {        "id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31",        "p_id": 7731,        "title": "16 oz",        "option_values": {          "Size": "16 oz"        }      }    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6IjAxOWIwYzRkLTVlNmYtN2E4Yi05YzBkLTFlMmYzYTRiNWM5OSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}
GET
/customer-segments

Requires scope merchant-customer-segments-read.

Lists the store’s saved customer segments, newest first, with cursor pagination (limit + starting_after, has_more/next_cursor); search matches the name and is_active filters. The dashboard’s built-in default segments are not listed: reproduce one with rules. A segment is auto (its rules pick the customers each time) or static (a hand-picked list). cached_recipient_count is the count stored when the segment was last saved; use the preview for the live count. Members are never listed here.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

search?|

Free-text filter: only items matching this text are returned.

Lengthlength <= 255
is_active?|

Only items that are active (true) or switched off (false).

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customer-segments?limit=10&is_active=true" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4b01",      "name": "Repeat buyers who spent over $100",      "description": null,      "type": "auto",      "rules": {        "order_count_gte": 2,        "total_spend_gte": "100.00"      },      "is_active": true,      "cached_recipient_count": 41,      "cached_count_computed_at": "2026-09-24T10:00:00+01:00",      "created_at": "2026-09-01T10:00:00+01:00",      "updated_at": "2026-09-24T10:00:00+01:00"    },    {      "id": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4b02",      "name": "Wedding guests",      "description": "Hand-picked for the October wedding order.",      "type": "static",      "rules": [],      "is_active": true,      "cached_recipient_count": 2,      "cached_count_computed_at": "2026-09-24T10:00:00+01:00",      "created_at": "2026-09-01T10:00:00+01:00",      "updated_at": "2026-09-24T10:00:00+01:00"    }  ],  "has_more": true,  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0wMSAxMDowMDowMCIsImlkIjoiMDE5YTJiN2MtNGUxMS03ZDkwLWEzYjUtNmM4ZDBlMmY0YjAyIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}
POST
/customer-segments

Requires scope merchant-customer-segments-create.

Creates a saved segment. type auto takes rules (any of order_count_gte/lte, last_order_before/after, total_spend_gte/lte, inactive_days_gte, active_days_lte, joined_days_lte, is_customer, is_follower, is_subscriber); type static takes customer_ids, up to 1,000 distinct customer ids of this store (customers/* ids), and ignores rules. An unknown or foreign customer id answers 422. The merchant can send campaigns to a saved segment, so only create segments the merchant asked for. Answers 201 with the segment.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Creates a customer segment: the same fields and limits as the merchant dashboard, with a static segment's members named by store customer id.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/customer-segments" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "name": "Repeat buyers who spent over $100",    "type": "auto",    "rules": {      "order_count_gte": 2,      "total_spend_gte": "100.00"    },    "is_active": true  }'
{  "status": "success",  "message": "Customer segment created",  "data": {    "id": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4b01",    "name": "Repeat buyers who spent over $100",    "description": null,    "type": "auto",    "rules": {      "order_count_gte": 2,      "total_spend_gte": "100.00"    },    "is_active": true,    "cached_recipient_count": 41,    "cached_count_computed_at": "2026-09-24T10:00:00+01:00",    "created_at": "2026-09-01T10:00:00+01:00",    "updated_at": "2026-09-01T10:00:00+01:00"  }}
GET
/customer-segments/{segment}

Requires scope merchant-customer-segments-read.

Retrieves one saved segment of this store by its id (a UUID). A static segment also carries customer_ids (store customer ids, the first 1,000 by id) and customer_ids_has_more. No member contact is returned. An id of another store, of a default segment or one that does not exist answers 404.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

segment*string

Identifier of the customer segment, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customer-segments/019a2b7c-4e11-7d90-a3b5-6c8d0e2f4b01" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Customer segment retrieved",  "data": {    "id": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4b02",    "name": "Wedding guests",    "description": "Hand-picked for the October wedding order.",    "type": "static",    "rules": [],    "is_active": true,    "cached_recipient_count": 2,    "cached_count_computed_at": "2026-09-24T10:00:00+01:00",    "customer_ids": [      90341,      90350    ],    "customer_ids_has_more": false,    "created_at": "2026-09-01T10:00:00+01:00",    "updated_at": "2026-09-24T10:00:00+01:00"  }}
PATCH
/customer-segments/{segment}

Requires scope merchant-customer-segments-update.

Changes any of name, description, is_active, type, rules and customer_ids of a saved segment; sending customer_ids replaces a static segment’s members. Changing the rules or members of a segment a campaign already uses changes who that campaign reaches, and what it costs the merchant, at its next send. An id of another store or a default segment answers 404.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

segment*string

Identifier of the customer segment, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Changes a customer segment: the same fields and limits as the merchant dashboard, with a static segment's members named by store customer id.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/customer-segments/019a2b7c-4e11-7d90-a3b5-6c8d0e2f4b01" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "name": "Big spenders",    "rules": {      "order_count_gte": 3,      "total_spend_gte": "200.00"    }  }'
{  "status": "success",  "message": "Customer segment updated",  "data": {    "id": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4b01",    "name": "Repeat buyers who spent over $100",    "description": null,    "type": "auto",    "rules": {      "order_count_gte": 2,      "total_spend_gte": "100.00"    },    "is_active": true,    "cached_recipient_count": 41,    "cached_count_computed_at": "2026-09-24T10:00:00+01:00",    "created_at": "2026-09-01T10:00:00+01:00",    "updated_at": "2026-09-24T10:00:00+01:00"  }}
DELETE
/customer-segments/{segment}

Requires scope merchant-customer-segments-delete.

Deletes a saved segment of this store. A campaign that used it keeps its other settings, and its audience becomes only the customers hand-picked on that campaign. Answers the deleted id.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

segment*string

Identifier of the customer segment, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/customer-segments/019a2b7c-4e11-7d90-a3b5-6c8d0e2f4b01" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Customer segment deleted",  "data": {    "id": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4b01",    "deleted": true  }}
POST
/customer-segments/preview

Requires scope merchant-customer-segments-read.

Counts who a set of rules (or an existing segment, by customer_segment_id) matches right now and returns up to 10 of them as customers. Nothing is saved. A sampled customer’s name, email and phone are null unless the key also holds merchant-customers-contact-read.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Previews a customer segment: the same rules as the merchant dashboard; reads only, nothing is saved.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/customer-segments/preview" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "rules": {      "order_count_gte": 2,      "inactive_days_gte": 30    }  }'
{  "status": "success",  "message": "Segment preview computed",  "data": {    "count": 41,    "sample": [      {        "id": 90341,        "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a61",        "name": "Alex Morgan",        "email": "[email protected]",        "phone": "+12025550148",        "avatar": null,        "tags": [          "vip",          "wholesale"        ],        "metafields": {},        "created_at": "2026-07-03T19:12:00+01:00",        "updated_at": "2026-09-24T12:58:00+01:00"      },      {        "id": 90342,        "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a62",        "name": "Sam Rivera",        "email": "[email protected]",        "phone": "+12025550149",        "avatar": null,        "tags": [],        "metafields": {},        "created_at": "2026-08-11T08:40:00+01:00",        "updated_at": "2026-09-18T20:02:00+01:00"      }    ]  }}