Discounts
Requires scope merchant-discounts-read.
Lists the store’s discounts with type, status and published filters.
Authorization
merchantKey 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
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
One of percentage, fixed.
Value in
- "percentage"
- "fixed"
- null
Only items with this status. One of active, inactive.
Value in
- "active"
- "inactive"
- null
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
Only discounts that are published (true) or still unpublished (false). A discount reaches shoppers only while it is both active and published.
Free-text filter: only items matching this text are returned.
length <= 255One of all, discount, promotion.
Value in
- "all"
- "discount"
- "promotion"
- null
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
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 direction. One of asc, desc.
Value in
- "asc"
- "desc"
- null
Header Parameters
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.
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"}Requires scope merchant-discounts-create.
Creates a discount.
Authorization
merchantKey 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
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.
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.
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" }}Requires scope merchant-discounts-detail.
Retrieves one discount: type, value, targeting, limits, usage and dates.
Authorization
merchantKey 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
Identifier of the discount, as returned by the Merchant API.
Header Parameters
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.
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" }}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 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
Identifier of the discount, as returned by the Merchant API.
Header Parameters
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.
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.
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" }}Requires scope merchant-discounts-update.
Publishes a discount, making it usable.
Authorization
merchantKey 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
Identifier of the discount, as returned by the Merchant API.
Header Parameters
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.
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.
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" }}Requires scope merchant-discounts-update.
Unpublishes a discount.
Authorization
merchantKey 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
Identifier of the discount, as returned by the Merchant API.
Header Parameters
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.
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.
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 }}