Promotions
Active promotions (sales, bundles) with their labels and dates. Use promotions/{promotion}/products for the items on offer.
Authorization
clientKey The connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.
In: header
Query Parameters
Only promotions whose title or description contains this text (at most 100 characters).
length <= 100One of priority, ending_soon, newest.
Value in
- "priority"
- "ending_soon"
- "newest"
- null
Promotions per page, 1 to 50 (default 20). Alias of limit.
1 <= value <= 50Keyset cursor: pass the previous page next_cursor. Walk while has_more is true; a stale, tampered, cross-list or filter-changed cursor answers 422 validation_failed with the failure on starting_after. Never combine with page.
Items per read (alias of per_page, max 50). page mode caps at page 50 (a deeper page answers 422 validation_failed on page); walk the cursor past that.
Header Parameters
Your connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.
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/store/promotions?limit=15" \ -H "X-Client-Key: {{clientKey}}"{ "status": "success", "message": "Promotions retrieved", "data": [ { "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c31", "title": "Spring Season 15% Off", "description": "15% off every dress through the season.", "image_url": "https://media.usequeek.com/uploads/stores/2207/discounts/spring-season.jpg", "type": "percentage", "currency": "USD", "value": "15.00", "priority": 0, "valid_from": "2026-09-01T00:00:00+01:00", "valid_until": "2027-12-31T23:59:00+01:00", "status": "active", "is_live": true } ], "has_more": false, "next_cursor": null}Paginated products on one promotion.
Authorization
clientKey The connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.
In: header
Path Parameters
The promotion id (UUID), as returned by GET /store/promotions. The promotion's reference code is also accepted.
Query Parameters
Only products whose title, description or SKU contains this text (at most 100 characters).
length <= 100One of newest, price_low, price_high, popular.
Value in
- "newest"
- "price_low"
- "price_high"
- "popular"
- null
When true, only products that can be bought now: a product with stock left, or one with an active variant that is in stock. False or omitted returns everything.
Products per page, 1 to 50 (default 20).
1 <= value <= 50Page number, starting at 1 (default 1). This list is page-only; page 50 is the deepest served.
1 <= valueThis list is page-only (in-memory slice): any starting_after answers 422 validation_failed on starting_after. Walk with page (cap 50).
Filter by variant options: attributes[Size]=M, or several values for one option as attributes[Size]=M,L. A product matches when an active variant carries any of the values listed for an option, and every option you send must match. Matching ignores letter case; an option or value the list does not carry is ignored.
Render this read in a published store locale (see GET store/locales). Unknown or unpublished codes fall back to the primary locale; the answer carries the locale used in Content-Language.
Header Parameters
Your connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.
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/store/promotions/019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c31/products?per_page=15" \ -H "X-Client-Key: {{clientKey}}"{ "status": "success", "message": "Promotion products retrieved", "data": [ { "shop_id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c01", "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c11", "p_id": 31501, "title": "Cotton Midi Dress", "slug": "cotton-midi-dress", "excerpt": "Flared cotton midi with pockets, cut in New York.", "description": "Our signature flared midi in premium cotton, with side pockets and a concealed back zip. Cut and finished in our New York atelier.", "image": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-card.webp", "thumbnail_image": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-thumb.webp", "video_url": null, "video_poster_url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-card.webp", "type": "product", "commerce_mode": "shop", "currency": "USD", "price": "60.00", "discount_price": "51.00", "compare_at_price": "60.00", "is_price_from": false, "price_range": { "min": "60.00", "max": "60.00" }, "has_variants": true, "has_addons": false, "tax_inclusive": false, "purchase_mode": "buy", "negotiable": false, "price_per": null, "discount": { "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c31", "title": "Spring Season 15% Off", "type": "percentage", "value": "15.00", "amount": "9.00", "final_price": "51.00", "image_url": "https://media.usequeek.com/uploads/stores/2207/discounts/spring-season.jpg" }, "discounts": [ { "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c31", "title": "Spring Season 15% Off", "type": "percentage", "value": "15.00", "amount": "9.00", "final_price": "51.00", "image_url": "https://media.usequeek.com/uploads/stores/2207/discounts/spring-season.jpg" } ], "media": { "thumbnail": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-thumb.webp", "image": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-card.webp", "original": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress.jpg", "primary_variant_image": null, "image_variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-card.webp", "w": 480, "h": 600 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-card2x.webp", "w": 800, "h": 1000 }, "view": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-view.webp", "w": 1200, "h": 1500 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-wa.jpg", "w": 1080, "h": 1350 }, "original": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress.jpg", "w": 1200, "h": 1500 } }, "primary_variant_image_variants": null, "images": [ { "id": 77101, "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-card.webp", "alt": "Cotton midi dress on a mannequin", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-card.webp", "w": 480, "h": 600 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-card2x.webp", "w": 800, "h": 1000 }, "view": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-view.webp", "w": 1200, "h": 1500 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-wa.jpg", "w": 1080, "h": 1350 }, "original": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress.jpg", "w": 1200, "h": 1500 } } }, { "id": 77103, "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-back-card.webp", "alt": "Cotton midi dress, back view", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-back-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-back-card.webp", "w": 480, "h": 600 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-back-card2x.webp", "w": 800, "h": 1000 }, "view": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-back-view.webp", "w": 1200, "h": 1500 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-back-wa.jpg", "w": 1080, "h": 1350 }, "original": { "url": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress-back.jpg", "w": 1200, "h": 1500 } } } ] }, "inventory": { "in_stock": true, "tracking": true, "quantity": 18 }, "variant_summary": { "count": 3, "min_price": "60.00", "max_price": "60.00", "total_stock": 18, "tracks_inventory": true, "in_stock": true }, "variants_count": 3, "rating": 4.5, "review_count": 132, "flags": { "featured": false, "is_marketplace": false, "is_wholesale": false, "is_new": false }, "metafields": {}, "created_at": "2026-06-18T09:40:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "shop": { "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c01", "name": "Northwind Goods", "slug": "northwind-goods", "logo": "https://media.usequeek.com/uploads/stores/2207/logo.png", "rating": 4.7, "rating_count": 486 }, "accepts_offers": false } ], "meta": { "promotion": { "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c31", "title": "Spring Season 15% Off", "description": "15% off every dress through the season.", "image_url": "https://media.usequeek.com/uploads/stores/2207/discounts/spring-season.jpg", "type": "percentage", "currency": "USD", "value": "15.00", "priority": 0, "valid_from": "2026-09-01T00:00:00+01:00", "valid_until": "2027-12-31T23:59:00+01:00", "status": "active", "is_live": true }, "filters": { "attributes": [ { "name": "Size", "slug": "size", "type": "size", "values": [ { "value": "L", "slug": "l", "count": 1, "selected": false, "color_code": null }, { "value": "M", "slug": "m", "count": 1, "selected": false, "color_code": null }, { "value": "S", "slug": "s", "count": 1, "selected": false, "color_code": null } ] } ] } }, "has_more": false, "next_cursor": null}