Coupons

Permission: coupons (read / write).

GET /v1/coupons. Filters: code, is_active, updated_since, limit, cursor.

GET /v1/coupons/{id}

{
  "object": "coupon",
  "id": 9,
  "code": "MARKETDAY",
  "name": "Market day 15% off candles",
  "type": "percent",
  "value": 10,
  "scope": "category",
  "channel": "store_online",
  "category_id": 530,
  "product_id": null,
  "min_subtotal_cents": 5000,
  "starts_at": "2026-09-01T04:00:00Z",
  "ends_at": null,
  "max_uses": null,
  "uses": 41,
  "is_active": true,
  "updated_at": "2026-09-20T12:00:00Z"
}

Field	Values
type	percent (value is a whole percent) or fixed (value in cents)
scope	all, category, product
channel	store (counter only) or store_online (also on BigCommerce)

Create, update, delete

POST /v1/coupons with code, name, type and value required; optional scope (default all), channel (default store), category_id / product_id (for the scope), min_subtotal_cents, starts_at, ends_at, max_uses, is_active (default true), notes.

curl -X POST https://app.blackbeachpos.com/api/v1/coupons \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"code": "welcome-8f3k2", "name": "Welcome 10%", "type": "percent", "value": 10, "max_uses": 1, "channel": "store_online", "ends_at": "2026-12-31T23:59:59Z"}'

• Codes are normalised to upper case (letters, numbers and dashes). A taken code is 409 CODE_TAKEN.
• A percent coupon can't exceed 100; ends_at must be after starts_at (400 VALIDATION_ERROR).
• A store_online coupon also works at BigCommerce checkout: it syncs to the connected store within about a minute. Its category or product has to be linked to BigCommerce.
• The typical use is an email tool minting one unique code per customer with max_uses: 1.

PATCH /v1/coupons/{id} changes any of the same fields. DELETE /v1/coupons/{id} removes it (and its BigCommerce copy) and returns { "object": "coupon", "id": 9, "code": "…", "deleted": true }.