Queek docs
Merchant endpoint reference

Discounts

GET
/discounts

Requires scope merchant-discounts-read.

Lists the store’s discounts with type, status and published filters.

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.

type?|

One of percentage, fixed.

Value in

  • "percentage"
  • "fixed"
  • null
status?|

Only items with this status. One of active, inactive.

Value in

  • "active"
  • "inactive"
  • null
state?|

Only discounts in this state: active (applying now), scheduled (starts later), expired (ended, or its usage limit is used up), draft (unpublished) or inactive (switched off).

Value in

  • "inactive"
  • "draft"
  • "expired"
  • "scheduled"
  • "active"
  • null
is_published?|

Only discounts that are published (true) or still unpublished (false). A discount reaches shoppers only while it is both active and published.

search?|

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

Lengthlength <= 255
campaign_type?|

One of all, discount, promotion.

Value in

  • "all"
  • "discount"
  • "promotion"
  • null
method?|

automatic (the default: discounts applied at the price), code (discount codes) or all (both, one list: each row carries method, kind and value_type, and the response a counts object).

Value in

  • "all"
  • "automatic"
  • "code"
  • null
sort_by?|

Field to sort the list by. One of created_at, title, usage_count, valid_from, valid_until.

Value in

  • "created_at"
  • "title"
  • "usage_count"
  • "valid_from"
  • "valid_until"
  • null
sort_order?|

Sort direction. One of asc, desc.

Value in

  • "asc"
  • "desc"
  • null

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/discounts?limit=2&status=active" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e02",      "reference": "DSC-9P4R",      "title": "Holiday Season $4 Off",      "description": "$4 off party packs through December.",      "type": "fixed",      "currency": "USD",      "value": "4.00",      "product_ids": [        "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21"      ],      "category_ids": [],      "minimum_order_amount": "30.00",      "minimum_quantity": 1,      "capped_amount": null,      "capped_amount_per_user": null,      "max_usage_total": null,      "max_usage_per_user": 2,      "usage_count": 0,      "auto_apply": false,      "status": "active",      "state": "inactive",      "is_active": true,      "is_published": false,      "image_url": null,      "valid_from": "2026-12-01T00:00:00+01:00",      "valid_until": "2026-12-31T23:59:00+01:00",      "published_at": null,      "created_at": "2026-09-24T10:00:00+01:00",      "updated_at": "2026-09-24T10:00:00+01:00"    },    {      "id": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01",      "reference": "DSC-8K2M",      "title": "Party Pack Season 10% Off",      "description": "10% off every party pack until the end of the year.",      "type": "percentage",      "currency": "USD",      "value": "10.00",      "product_ids": [],      "category_ids": [        "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21"      ],      "minimum_order_amount": "20.00",      "minimum_quantity": 1,      "capped_amount": "10.00",      "capped_amount_per_user": null,      "max_usage_total": 1000,      "max_usage_per_user": 5,      "usage_count": 274,      "auto_apply": true,      "status": "active",      "state": "active",      "is_active": true,      "is_published": true,      "image_url": "https://media.usequeek.com/uploads/stores/1095/discounts/party-pack-season.jpg",      "valid_from": "2026-09-01T00:00:00+01:00",      "valid_until": "2026-12-31T23:59:00+01:00",      "published_at": "2026-09-01T09:00:00+01:00",      "created_at": "2026-08-29T15:20:00+01:00",      "updated_at": "2026-09-01T09:00:00+01:00"    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6IjAxOWEyZTkwLTdhMWItN2MyZC05ZTNmLTRhNWI2YzdkOGUwMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}
POST
/discounts

Requires scope merchant-discounts-create.

Creates a discount.

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/discounts" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "title": "Holiday Season $4 Off",    "description": "$4 off party packs through December.",    "type": "fixed",    "value": "4.00",    "product_ids": [      "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21"    ],    "minimum_order_amount": "30.00",    "minimum_quantity": 1,    "max_usage_per_user": 2,    "valid_from": "2026-12-01T00:00:00+01:00",    "valid_until": "2026-12-31T23:59:00+01:00",    "is_active": true,    "is_published": false,    "auto_apply": false  }'
{  "status": "success",  "message": "Discount created successfully",  "data": {    "id": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e02",    "reference": "DSC-9P4R",    "title": "Holiday Season $4 Off",    "description": "$4 off party packs through December.",    "type": "fixed",    "currency": "USD",    "value": "4.00",    "product_ids": [      "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21"    ],    "category_ids": [],    "minimum_order_amount": "30.00",    "minimum_quantity": 1,    "capped_amount": null,    "capped_amount_per_user": null,    "max_usage_total": null,    "max_usage_per_user": 2,    "usage_count": 0,    "auto_apply": false,    "status": "active",    "state": "inactive",    "is_active": true,    "is_published": false,    "image_url": null,    "valid_from": "2026-12-01T00:00:00+01:00",    "valid_until": "2026-12-31T23:59:00+01:00",    "published_at": null,    "created_at": "2026-09-24T10:00:00+01:00",    "updated_at": "2026-09-24T10:00:00+01:00"  }}
GET
/discounts/{discount}

Requires scope merchant-discounts-detail.

Retrieves one discount: type, value, targeting, limits, usage and dates.

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

discount*string

Identifier of the discount, 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/discounts/019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Discount retrieved successfully",  "data": {    "id": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01",    "reference": "DSC-8K2M",    "title": "Party Pack Season 10% Off",    "description": "10% off every party pack until the end of the year.",    "type": "percentage",    "currency": "USD",    "value": "10.00",    "product_ids": [],    "category_ids": [      "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21"    ],    "minimum_order_amount": "20.00",    "minimum_quantity": 1,    "capped_amount": "10.00",    "capped_amount_per_user": null,    "max_usage_total": 1000,    "max_usage_per_user": 5,    "usage_count": 274,    "auto_apply": true,    "status": "active",    "state": "active",    "is_active": true,    "is_published": true,    "image_url": "https://media.usequeek.com/uploads/stores/1095/discounts/party-pack-season.jpg",    "valid_from": "2026-09-01T00:00:00+01:00",    "valid_until": "2026-12-31T23:59:00+01:00",    "published_at": "2026-09-01T09:00:00+01:00",    "created_at": "2026-08-29T15:20:00+01:00",    "updated_at": "2026-09-01T09:00:00+01:00"  }}
PATCH
/discounts/{discount}

Requires scope merchant-discounts-update.

Changes any of a discount’s title, type, value, targeting, limits, dates and flags; fields left out keep their value. A new value or type takes effect for shoppers at once, and the price a shopper sees is the price charged. Editing a published discount changes the live offer. The discount keeps its usage count. Answers the updated discount.

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

discount*string

Identifier of the discount, 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 PATCH "https://example.com/discounts/019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "title": "Party Pack Season 15% Off",    "value": "15.00",    "valid_until": "2026-12-31T23:59:00+01:00"  }'
{  "status": "success",  "message": "Discount updated successfully",  "data": {    "id": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01",    "reference": "DSC-8K2M",    "title": "Party Pack Season 15% Off",    "description": "10% off every party pack until the end of the year.",    "type": "percentage",    "currency": "USD",    "value": "15.00",    "product_ids": [],    "category_ids": [      "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21"    ],    "minimum_order_amount": "20.00",    "minimum_quantity": 1,    "capped_amount": "10.00",    "capped_amount_per_user": null,    "max_usage_total": 1000,    "max_usage_per_user": 5,    "usage_count": 274,    "auto_apply": true,    "status": "active",    "state": "active",    "is_active": true,    "is_published": true,    "image_url": "https://media.usequeek.com/uploads/stores/1095/discounts/party-pack-season.jpg",    "valid_from": "2026-09-01T00:00:00+01:00",    "valid_until": "2026-12-31T23:59:00+01:00",    "published_at": "2026-09-01T09:00:00+01:00",    "created_at": "2026-08-29T15:20:00+01:00",    "updated_at": "2026-09-01T09:00:00+01:00"  }}
POST
/discounts/{discount}/publish

Requires scope merchant-discounts-update.

Publishes a discount, making it usable.

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

discount*string

Identifier of the discount, 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 POST "https://example.com/discounts/019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01/publish" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Discount published successfully",  "data": {    "is_published": true,    "published_at": "2026-09-01T09:00:00+01:00"  }}
POST
/discounts/{discount}/unpublish

Requires scope merchant-discounts-update.

Unpublishes a discount.

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

discount*string

Identifier of the discount, 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 POST "https://example.com/discounts/019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01/unpublish" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Discount unpublished successfully",  "data": {    "is_published": false,    "published_at": null  }}