Customers
Requires scope merchant-customers-read.
Lists the store’s customers with cursor pagination (limit up to 100 + starting_after, has_more/next_cursor) — the same object customers/* webhooks send. Contact fields are masked without the contact scope.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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
1 <= value <= 100datedateValue in
- "today"
- "this_week"
- "this_month"
- null
length <= 255Value in
- "created_at"
- "updated_at"
- "joined_date"
- "name"
- "email"
- "phone"
- "p_id"
- "customer_orders_count"
- null
Value in
- "asc"
- "desc"
- null
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted under Dashboard → Settings → API keys. 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.
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": "Tunde Bakare", "email": "[email protected]", "phone": "+2348059876543", "avatar": null, "created_at": "2026-08-11T08:40:00+01:00", "updated_at": "2026-09-18T20:02:00+01:00" }, { "id": 90341, "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a61", "name": "Chiamaka Obi", "email": "[email protected]", "phone": "+2348031234567", "avatar": null, "created_at": "2026-07-03T19:12:00+01:00", "updated_at": "2026-09-24T12:58:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6OTAzNDEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}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 The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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
1 <= value <= 50Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted under Dashboard → Settings → API keys. 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.
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": "Ngozi Eze", "email": "[email protected]", "phone": "+2348123456789", "avatar": "https://media.usequeek.com/uploads/avatars/ngozi-eze.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": "Chiamaka Obi", "email": "[email protected]", "phone": "+2348031234567", "avatar": "https://media.usequeek.com/uploads/avatars/chiamaka-obi.jpg", "shared_contact": false, "is_customer": true, "followed_at": "2026-07-03T19:15:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEyZjMzLTFhMmItN2MzZC04ZTRmLTVhNmI3YzhkOWUwMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}Requires scope merchant-customers-detail.
Retrieves one customer — the same object customers/* webhooks send. {customer} is the customer’s id (p_id) or uid of this store. Contact fields are masked without the contact scope.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted under Dashboard → Settings → API keys. 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.
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": "Chiamaka Obi", "email": "[email protected]", "phone": "+2348031234567", "avatar": null, "created_at": "2026-07-03T19:12:00+01:00", "updated_at": "2026-09-24T12:58:00+01:00" }}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 The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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
Query Parameters
1 <= value <= 100Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted under Dashboard → Settings → API keys. 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.
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-20T09:00:00.000000Z", "product": { "shop_id": "019a0b3a-af57-72d0-9c13-7036c3805892", "id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "p_id": 20418, "title": "Homemade Chapman", "slug": "homemade-chapman", "excerpt": "Fresh Chapman with cucumber and orange slices.", "description": "Our house Chapman, mixed fresh every morning. Served chilled.", "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "thumbnail_image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "video_url": null, "video_poster_url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "type": null, "commerce_mode": "shop", "currency": "NGN", "price": 2875, "discount_price": 2875, "compare_at_price": null, "is_price_from": true, "price_range": { "min": 2875, "max": 4830 }, "has_variants": true, "has_addons": false, "tax_inclusive": false, "discount": null, "discounts": [], "media": { "thumbnail": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "original": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "primary_variant_image": null, "image_variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } }, "primary_variant_image_variants": null, "images": [ { "id": 88220, "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "alt": "Two bottles of chilled Chapman with cucumber slices", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } } } ], "video_url": null, "video_poster_url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp" }, "inventory": { "in_stock": true, "tracking": true, "quantity": 60, "allow_backorder": false, "low_stock_threshold": 5, "updated_at": "2026-09-22 16:05:00" }, "variant_summary": { "count": 2, "min_price": 2875, "max_price": 4830, "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-15 11:30:00", "updated_at": "2026-09-22 16:05:00", "shop": { "id": "019a0b3a-af57-72d0-9c13-7036c3805892", "name": "Adeyemi Foods", "slug": "adeyemi-foods", "logo": "https://media.usequeek.com/uploads/stores/1095/logo.png", "rating": 4.8, "rating_count": 231 }, "addons": [], "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", "type": "size", "values": [ "50cl", "1 litre" ], "values_detailed": [ { "value": "50cl", "color_code": null, "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg" }, { "value": "1 litre", "color_code": null, "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg" } ] } ], "variants": [ { "id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "sku": "ADF-CHP-50CL", "title": "50cl", "option_values": { "Size": "50cl" }, "price": 2875, "discount_price": 2875, "discount_amount": 0, "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/homemade-chapman.jpg", "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "image_media_id": null, "image_variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } }, "images": [ { "id": 88220, "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "alt": "Two bottles of chilled Chapman with cucumber slices", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } } } ], "video_url": null, "source": "product" } }, { "id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "ADF-CHP-1L", "title": "1 litre", "option_values": { "Size": "1 litre" }, "price": 4830, "discount_price": 4830, "discount_amount": 0, "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/homemade-chapman.jpg", "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "image_media_id": null, "image_variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } }, "images": [ { "id": 88220, "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "alt": "Two bottles of chilled Chapman with cucumber slices", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } } } ], "video_url": null, "source": "product" } } ], "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": { "meta_title": null, "meta_description": null, "canonical_url": null, "keywords": [] }, "analytics": { "sales_count": 31, "view_count": 218, "favorite_count": 0, "review_count": 14 } }, "variant": { "id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "p_id": 7731, "title": "50cl", "option_values": { "Size": "50cl" } } } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWIwYzRkLTVlNmYtN2E4Yi05YzBkLTFlMmYzYTRiNWM5OSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}