Queek docs
Merchant endpoint reference

Coupons

GET
/coupons

Requires scope merchant-coupons-read.

Lists the store’s coupons.

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.

discount_type?|

Only coupons of this type: percentage or fixed.

status?|

active returns the coupons that are switched on; any other value returns the switched-off ones.

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/coupons?limit=1&discount_type=percentage&status=active" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": "019a2e91-0b1c-7d2e-8f3a-4b5c6d7e8f01",      "code": "OPENING10",      "title": "Grand Opening 10% Off",      "description": "10% off your first order from our New York kitchen.",      "discount_type": "percentage",      "currency": "USD",      "discount_value": "10.00",      "applies_to": "all_products",      "target_product_ids": [],      "target_category_ids": [],      "minimum_order_amount": "10.00",      "capped_amount": null,      "capped_amount_per_user": null,      "usage_limit": 500,      "usage_limit_per_user": 1,      "used_count": 37,      "is_active": true,      "is_valid": true,      "is_expired": false,      "image_url": null,      "starts_at": "2026-08-30T11:45:00+01:00",      "expires_at": null,      "created_at": "2026-08-30T11:45:00+01:00",      "updated_at": "2026-09-24T09:10:00+01:00"    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6IjAxOWEyZTkxLTBiMWMtN2QyZS04ZjNhLTRiNWM2ZDdlOGYwMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}
POST
/coupons

Requires scope merchant-coupons-create.

Creates a coupon.

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/coupons" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "title": "Grand Opening 10% Off",    "description": "10% off your first order from our New York kitchen.",    "code": "OPENING10",    "discount_type": "percentage",    "discount_value": 10,    "minimum_order_amount": "10.00",    "applies_to": "all_products",    "usage_limit": 500,    "usage_limit_per_user": 1  }'
{  "success": true,  "data": {    "id": "019a2e91-0b1c-7d2e-8f3a-4b5c6d7e8f01",    "code": "OPENING10",    "title": "Grand Opening 10% Off",    "description": "10% off your first order from our New York kitchen.",    "discount_type": "percentage",    "currency": "USD",    "discount_value": "10.00",    "applies_to": "all_products",    "target_product_ids": [],    "target_category_ids": [],    "minimum_order_amount": "10.00",    "capped_amount": null,    "capped_amount_per_user": null,    "usage_limit": 500,    "usage_limit_per_user": 1,    "used_count": 0,    "is_active": true,    "is_valid": true,    "is_expired": false,    "image_url": null,    "starts_at": "2026-08-30T11:45:00+01:00",    "expires_at": null,    "created_at": "2026-08-30T11:45:00+01:00",    "updated_at": "2026-08-30T11:45:00+01:00"  },  "message": "Coupon created successfully"}
PATCH
/coupons/{coupon}

Requires scope merchant-coupons-update.

Changes a coupon’s title, discount, minimum order, targeting, usage limits, dates and active flag; fields left out keep their value. The code and the used count never change, and a usage limit below the redemptions already made answers 422. Answers the updated coupon.

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

coupon*string

Identifier of the coupon, 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/coupons/019a2e91-0b1c-7d2e-8f3a-4b5c6d7e8f01" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "usage_limit": 1000,    "expires_at": "2026-12-31T23:59:00+01:00"  }'
{  "success": true,  "data": {    "id": "019a2e91-0b1c-7d2e-8f3a-4b5c6d7e8f01",    "code": "OPENING10",    "title": "Grand Opening 10% Off",    "description": "10% off your first order from our New York kitchen.",    "discount_type": "percentage",    "currency": "USD",    "discount_value": "10.00",    "applies_to": "all_products",    "target_product_ids": [],    "target_category_ids": [],    "minimum_order_amount": "10.00",    "capped_amount": null,    "capped_amount_per_user": null,    "usage_limit": 1000,    "usage_limit_per_user": 1,    "used_count": 37,    "is_active": true,    "is_valid": true,    "is_expired": false,    "image_url": null,    "starts_at": "2026-08-30T11:45:00+01:00",    "expires_at": "2026-12-31T23:59:00+01:00",    "created_at": "2026-08-30T11:45:00+01:00",    "updated_at": "2026-09-24T09:10:00+01:00"  },  "message": "Coupon updated successfully"}