> Documentation index: https://docs.sellhidden.com/llms.txt

# Coupons

Source: https://docs.sellhidden.com/reference/coupons

Discount codes. The code and the discount are fixed once created (orders keep what they used); every other rule can change.

## Endpoints

5 endpoints · [coupons:read](https://docs.sellhidden.com/start?scope=coupons%3Aread#scopes) · [coupons:write](https://docs.sellhidden.com/start?scope=coupons%3Awrite#scopes)

Base URL https://api.sellhidden.com/v1 · Authorization: Bearer · 120/min per key · cursor pagination · Idempotency-Key on POST · No test mode

### GET /coupons — List coupons

Scope `coupons:read`.

**Query parameters**

| Query parameters | Type | Description |
| --- | --- | --- |
| `active` | true \| false | Only usable codes (active and not expired), or only unusable ones. |
| `code` | string | Code contains this text. |
| `limit` | 1..200 | Page size. Default 50. |
| `cursor` | string | nextCursor from the previous page. |

```bash
curl https://api.sellhidden.com/v1/coupons \
  -H "Authorization: Bearer hsk_live_…"
```

Response (200):

```json
{ "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 /coupons — Create a coupon

Scope `coupons:write`. Accepts `Idempotency-Key`. Returns 201.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `code` (required) | string | 2-40 characters: letters, digits, - and _. Stored upper-case. |
| `percentOff` | 1..100 | Either this or amountOffUsd. |
| `amountOffUsd` | number | Fixed discount in USD. |
| `maxUses` | integer \| null | Total uses; null = unlimited. |
| `perCustomerLimit` | 1..1000 \| null | Uses per buyer email. |
| `firstOrderOnly` | boolean | Only buyers who never paid here. |
| `minOrderUsd` | number \| null | Smallest cart subtotal (before the discount). |
| `maxDiscountUsd` | number \| null | Cap on the discount. |
| `startsAt` | ISO date \| null | Not valid before. |
| `expiresAt` | ISO date \| null | Not valid after. |
| `productIds` | string[] | Only these products (empty = all). |
| `categoryIds` | string[] | Only these categories. |
| `variantIds` | string[] | Only these variations. |
| `paymentMethods` | string[] | "crypto", "balance" or a manual payment method id. |
| `active` | boolean | Default true. |

```bash
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} — Get a coupon

Scope `coupons:read`.

```bash
curl https://api.sellhidden.com/v1/coupons/ID \
  -H "Authorization: Bearer hsk_live_…"
```

### PATCH /coupons/{id} — Update a coupon

Any rule except code, percentOff and amountOffUsd. null clears a limit or a date; null or [] clears a list. Scope `coupons:write`.

**Body**

| Body | Type | Description |
| --- | --- | --- |
| `active` | boolean |  |
| `maxUses` | integer \| null | Not below the uses so far. |
| `perCustomerLimit` | integer \| null |  |
| `firstOrderOnly` | boolean |  |
| `minOrderUsd` | number \| null |  |
| `maxDiscountUsd` | number \| null |  |
| `startsAt` | ISO date \| null |  |
| `expiresAt` | ISO date \| null |  |
| `productIds` | string[] \| null |  |
| `categoryIds` | string[] \| null |  |
| `variantIds` | string[] \| null |  |
| `paymentMethods` | string[] \| null |  |

```bash
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} — Delete a coupon

Scope `coupons:write`.

```bash
curl -X DELETE https://api.sellhidden.com/v1/coupons/ID \
  -H "Authorization: Bearer hsk_live_…"
```