Sign in
VoucherCodes

List VoucherCodes

Returns a paginated list of VoucherCodes. Use the query parameters to narrow the result set by code substring, status, amount, balance, creation date, site, voucher type, expiry window, or fulfilment status. The result is ordered by created_at descending so the newest voucher codes appear first.

This endpoint powers the voucher management screens in the Trybe dashboard and any third-party integration that needs the same view — for example a fulfilment provider polling for vouchers with fulfillment_status=needs_dispatching.

get/shop/voucher-codes

Query parameters

pageinteger

The page to retrieve results from

per_pageinteger

The number of results to return per page

site_idstring uuid

Filter the list of voucher codes to a single site.

codestring

Partial, case-insensitive substring match on the voucher redemption code.

statusstring[]

Filter by voucher code status. Pass multiple statuses as a comma-separated list.

amountstring

Filter by voucher amount. Supports comparison operators (>1000, <5000, >=2500, <=2500, =1000) — values are in the smallest unit of the voucher's currency.

balancestring

Filter by remaining voucher balance. Supports the same comparison operators as amount.

created_sincestring date-time

Filter for voucher codes created on or after this date-time.

voucher_type_idstring[]

Filter to voucher codes whose voucher_type_id matches one of the given IDs.

expired_range_fromstring date

Filter to voucher codes whose valid_to_date is on or after this date.

expired_range_tostring date

Filter to voucher codes whose valid_to_date is before this date.

fulfillment_statusstring

Filter by fulfilment status — needs_dispatching for vouchers awaiting physical delivery, dispatched once sent, not_required for digital deliveries.

Response

Successfully retrieved VoucherCodes.

Example response

{
  "links": {
    "first": "http://example.com?page=1",
    "next": "https://example.com?page=3",
    "prev": "https://example.com?page=1",
    "last": "https://example.com?page=4"
  },
  "meta": {
    "from": 1,
    "to": 2,
    "total": 2,
    "current_page": 1,
    "last_page": 2,
    "per_page": 15,
    "path": "http://example.com/api"
  },
  "data": [
    {
      "code": "ABC123XYZ",
      "valid_from_date": "2026-01-01T00:00:00+00:00",
      "valid_to_date": "2027-01-01T00:00:00+00:00",
      "amount": 5000,
      "balance": 2500,
      "currency": "gbp",
      "value": 5000,
      "partially_redeemable": true,
      "uses_total": 7,
      "uses_remaining": 5,
      "fulfillment_status": "needs_dispatching",
      "voucher_type": {
        "name": "Spa Day Gift Voucher"
      },
      "recipient": {
        "name": "Jane Doe",
        "email": "jane@example.com"
      },
      "delivery": {
        "method": "post",
        "option": {
          "name": "First class mail",
          "price": 5000,
          "revenue_centre": "spa"
        }
      },
      "order": {
        "order_ref": "TRY00",
        "item_cost": 5000
      },
      "redemptions": [
        {
          "amount": 2500
        }
      ],
      "created_at": "2025-02-04T12:00:00+01:00",
      "issued_at": "2026-01-02T09:00:00+00:00"
    }
  ]
}

Changes