Coupons
Requires scope merchant-coupons-read.
Lists the store’s coupons.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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
1 <= value <= 100Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted under Dashboard → Settings → API keys. 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/coupons?limit=1&discount_type=percentage&status=active" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": "019a2e91-0b1c-7d2e-8f3a-4b5c6d7e8f01", "code": "LEKKI10", "title": "Lekki Launch 10% Off", "description": "10% off your first order from our Lekki kitchen.", "discount_type": "percentage", "discount_value": "10.00", "applies_to": "all_products", "target_product_ids": [], "target_category_ids": [], "minimum_order_amount": "5000.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"}Requires scope merchant-coupons-create.
Creates a coupon.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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 under Dashboard → Settings → API keys. 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/coupons" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "title": "Lekki Launch 10% Off", "description": "10% off your first order from our Lekki kitchen.", "code": "LEKKI10", "discount_type": "percentage", "discount_value": 10, "minimum_order_amount": "5000.00", "applies_to": "all_products", "usage_limit": 500, "usage_limit_per_user": 1 }'{ "success": true, "data": { "id": "019a2e91-0b1c-7d2e-8f3a-4b5c6d7e8f01", "code": "LEKKI10", "title": "Lekki Launch 10% Off", "description": "10% off your first order from our Lekki kitchen.", "discount_type": "percentage", "discount_value": "10.00", "applies_to": "all_products", "target_product_ids": [], "target_category_ids": [], "minimum_order_amount": "5000.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"}