Queek docs
Storefront endpoint reference

Promotions

GET
/store/promotions

Active promotions (sales, bundles) with their labels and dates. Use promotions/{promotion}/products for the items on offer.

Authorization

clientKey
X-Client-Key<token>

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

keyword?|

Only promotions whose title or description contains this text (at most 100 characters).

Lengthlength <= 100
sort?|

One of priority, ending_soon, newest.

Value in

  • "priority"
  • "ending_soon"
  • "newest"
  • null
per_page?|

Promotions per page, 1 to 50 (default 20). Alias of limit.

Range1 <= value <= 50
starting_after?string

Keyset 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.

limit?integer

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

X-Client-Key*string

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.

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/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}
GET
/store/promotions/{promotion}/products

Paginated products on one promotion.

Authorization

clientKey
X-Client-Key<token>

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

promotion*string

The promotion id (UUID), as returned by GET /store/promotions. The promotion's reference code is also accepted.

Query Parameters

keyword?|

Only products whose title, description or SKU contains this text (at most 100 characters).

Lengthlength <= 100
sort?|

One of newest, price_low, price_high, popular.

Value in

  • "newest"
  • "price_low"
  • "price_high"
  • "popular"
  • null
in_stock?|

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.

per_page?|

Products per page, 1 to 50 (default 20).

Range1 <= value <= 50
page?|

Page number, starting at 1 (default 1). This list is page-only; page 50 is the deepest served.

Range1 <= value
starting_after?string

This list is page-only (in-memory slice): any starting_after answers 422 validation_failed on starting_after. Walk with page (cap 50).

attributes?array<array<|>>

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.

locale?string

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

X-Client-Key*string

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.

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