API reference
Coupons
Discount codes. The code and the discount are fixed once created (orders keep what they used); every other rule can change.
Endpoints
GET/couponscoupons:read
List coupons.
| Query parameters | Type | Description |
|---|---|---|
| active | Type: true | false | Only usable codes (active and not expired), or only unusable ones. |
| code | Type: string | Code contains this text. |
| limit | Type: 1..200 | Page size. Default 50. |
| cursor | Type: string | nextCursor from the previous page. |
curl https://api.sellhidden.com/v1/coupons \
-H "Authorization: Bearer hsk_live_…"200 OKjson
{ "ok": true, "coupons": [ { "id": "clx…", "code": "LAUNCH20", "type": "percent", "value": 20, "minOrderUsd": null, "maxUses": 100, "usedCount": 12, "active": true, "expiresAt": null, "createdAt": "…" } ], "nextCursor": null, "hasMore": false }POST/couponscoupons:writeIdempotency-Key201
Create a coupon.
| Body | Type | Description |
|---|---|---|
| coderequired | Type: string | 2-40 characters: letters, digits, - and _. Stored upper-case. |
| percentOff | Type: 1..100 | Either this or amountOffUsd. |
| amountOffUsd | Type: number | Fixed discount in USD. |
| maxUses | Type: integer | null | Total uses; null = unlimited. |
| perCustomerLimit | Type: 1..1000 | null | Uses per buyer email. |
| firstOrderOnly | Type: boolean | Only buyers who never paid here. |
| minOrderUsd | Type: number | null | Smallest cart subtotal (before the discount). |
| maxDiscountUsd | Type: number | null | Cap on the discount. |
| startsAt | Type: ISO date | null | Not valid before. |
| expiresAt | Type: ISO date | null | Not valid after. |
| productIds | Type: string[] | Only these products (empty = all). |
| categoryIds | Type: string[] | Only these categories. |
| variantIds | Type: string[] | Only these variations. |
| paymentMethods | Type: string[] | "crypto", "balance" or a manual payment method id. |
| active | Type: boolean | Default true. |
curl -X POST https://api.sellhidden.com/v1/coupons \
-H "Authorization: Bearer hsk_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"code": "LAUNCH20",
"percentOff": 20,
"maxUses": 100,
"expiresAt": "2026-12-31T23:59:59Z"
}'GET/coupons/{id}coupons:read
Get a coupon.
curl https://api.sellhidden.com/v1/coupons/ID \
-H "Authorization: Bearer hsk_live_…"PATCH/coupons/{id}coupons:write
Update a coupon. Any rule except code, percentOff and amountOffUsd. null clears a limit or a date; null or [] clears a list.
| Body | Type | Description |
|---|---|---|
| active | Type: boolean | |
| maxUses | Type: integer | null | Not below the uses so far. |
| perCustomerLimit | Type: integer | null | |
| firstOrderOnly | Type: boolean | |
| minOrderUsd | Type: number | null | |
| maxDiscountUsd | Type: number | null | |
| startsAt | Type: ISO date | null | |
| expiresAt | Type: ISO date | null | |
| productIds | Type: string[] | null | |
| categoryIds | Type: string[] | null | |
| variantIds | Type: string[] | null | |
| paymentMethods | Type: string[] | null |
curl -X PATCH https://api.sellhidden.com/v1/coupons/ID \
-H "Authorization: Bearer hsk_live_…" \
-H "Content-Type: application/json" \
-d '{"active":false}'DELETE/coupons/{id}coupons:write
Delete a coupon.
curl -X DELETE https://api.sellhidden.com/v1/coupons/ID \
-H "Authorization: Bearer hsk_live_…"Get help
Send us the endpoint, the request or delivery id and the response you got. Security findings go through responsible disclosure. Live platform status is on the support page.
See also