Vouchers

The Vouchers API returns the voucher catalogue — discount codes, credit vouchers, and gift cards. Legacy discounts are also included with a voucher_legacy_ ID prefix.

All endpoints require the vouchers:read scope.

List vouchers

GET /vouchers

Returns all active vouchers for the company, including legacy discounts.

No pagination — vouchers are a small catalogue.

Example response

{
  "data": [
    {
      "id": "voucher_12",
      "type": "voucher",
      "voucher_type": "DISCOUNT",
      "name": "Early Bird",
      "code": "EARLY10",
      "discount_type": "PERCENTAGE",
      "discount_value": 10,
      "is_active": true,
      "expires": null,
      "created_at": "2025-06-15T10:00:00"
    },
    {
      "id": "voucher_15",
      "type": "voucher",
      "voucher_type": "CREDIT",
      "name": "Store Credit",
      "code": "CREDIT50",
      "initial_value_base100": 5000,
      "remaining_value_base100": 3500,
      "is_active": true,
      "expires": "2026-06-01T00:00:00",
      "created_at": "2025-06-15T10:00:00"
    },
    {
      "id": "voucher_20",
      "type": "voucher",
      "voucher_type": "GIFT_CARD",
      "name": "Gift Voucher",
      "min_purchase_base100": 1000,
      "max_discount_base100": 5000,
      "is_active": true,
      "expires_months": 6,
      "created_at": "2025-06-15T10:00:00"
    },
    {
      "id": "voucher_legacy_3",
      "type": "voucher",
      "voucher_type": "DISCOUNT",
      "name": "Staff Discount",
      "code": "",
      "discount_type": "FIXED",
      "discount_value": 5,
      "is_active": true,
      "expires": null,
      "created_at": null
    }
  ]
}

Get a single voucher

GET /voucher/{id}

Retrieve a single voucher by ID. Checks new vouchers first, then legacy discounts.

Path parameters

Parameter	Type	Description
`id`	string	Voucher ID (e.g. `voucher_12`)

The response has the same shape as an individual item from the list endpoint, wrapped in { "data": { ... } }.

Error responses

Status	Condition
403	Missing `vouchers:read` scope
404	Voucher ID does not exist for this company

Voucher types

The voucher_type field indicates the kind of voucher. Each type has different fields.

DISCOUNT

A percentage or fixed-amount discount code.

Field	Type	Description
`code`	string	Discount code customers enter at checkout
`discount_type`	string	`"PERCENTAGE"` or `"FIXED"`
`discount_value`	number	Discount amount (percentage as integer, or fixed amount)
`expires`	string or null	Expiry datetime, or `null` if no expiry

CREDIT

A prepaid credit voucher with a declining balance.

Field	Type	Description
`code`	string	Credit voucher code
`initial_value_base100`	number	Original value in smallest currency unit
`remaining_value_base100`	number	Remaining balance in smallest currency unit
`expires`	string or null	Expiry datetime, or `null` if no expiry

GIFT_CARD

A gift card with purchase constraints.

Field	Type	Description
`min_purchase_base100`	number	Minimum purchase amount to use this gift card
`max_discount_base100`	number	Maximum discount the gift card provides
`expires_months`	number	Number of months until the gift card expires

Common fields

These fields appear on all voucher types:

Field	Type	Description
`id`	string	Prefixed voucher ID (e.g. `voucher_12` or `voucher_legacy_3`)
`type`	string	Always `"voucher"`
`voucher_type`	string	`"DISCOUNT"`, `"CREDIT"`, or `"GIFT_CARD"`
`name`	string	Voucher name
`is_active`	boolean	Whether the voucher is currently active
`created_at`	string or null	ISO 8601 datetime, or `null` for legacy discounts

Caching

Both endpoints are cached for 5 minutes. See Scopes, Rate Limits, Caching & Errors for details.