---
title: "List VoucherCodes"
method: GET
path: "/shop/voucher-codes"
tags: ["VoucherCodes"]
---

# List VoucherCodes

`GET /shop/voucher-codes`

Returns a paginated list of `VoucherCode`s. 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`.

## Query parameters

- `page` integer
- `per_page` integer
- `site_id` string, uuid
- `code` string
- `status` string[]
- `amount` string
- `balance` string
- `created_since` string, date-time
- `voucher_type_id` string[]
- `expired_range_from` string, date
- `expired_range_to` string, date
- `fulfillment_status` string

## Response `200`

Successfully retrieved `VoucherCode`s.

- ListVoucherCodesResponse — Paginated envelope mixin. `allOf` this into any list response that wraps its `data` array with `meta` + `links`; the concrete schema keeps its own title so the SDK surface is unchanged, while the `meta` / `links` shape is sourced from a single definition.
  - `links` PaginationLinks, required — Hypermedia navigation links for paging through a list response. Each property is a fully-qualified URL that preserves the original query string (filters, sort, page size) and only swaps the `page` parameter. `next` and `prev` are `null` at the ends of the result set; `first` and `last` are always present.
    - `first` string, required — The url of the first page for the paginated results set
    - `next` string, nullable, required — The url of the next page for the paginated results set
    - `prev` string, nullable, required — The url of the previous page for the paginated results set
    - `last` string, required — The url of the last page for the paginated results set
  - `meta` PaginationMeta, required — Counts and positional information for the current page of a list response. Use `current_page` and `last_page` to drive pagination UI, `total` for result counts, and `per_page` to confirm the page size the server actually applied (which may differ from the requested value when capped).
    - `from` integer, required — The item number from which this results set starts from
    - `to` integer, required — The item number from which this results set ends at
    - `total` integer, required — The total number of results
    - `current_page` integer, required — The current page number
    - `last_page` integer, required — The page number of the last result set
    - `per_page` integer, required — The number of results per page
    - `path` string, required — The path of this api request
  - `data` VoucherCode[], required
    - `id` string, object-id, required — The ID of the voucher code.
    - `code` string, required — The redemption code itself. Display this to the customer or recipient — they will quote it back to redeem against an order.
    - `status` 'unredeemed' | 'partially_redeemed' | 'redeemed' | 'revoked' | 'expired', required — The lifecycle state of the voucher. `unredeemed` is the starting state; vouchers transition to `partially_redeemed`, `redeemed`, `expired`, or `revoked` over their life.
    - `valid_from_date` string, date-time, required — The first date on which the voucher can be redeemed.
    - `valid_to_date` string, date-time, nullable, required — The last date on which the voucher can be redeemed. Updating this date past today on an `expired` voucher will move it back to `unredeemed` (or `partially_redeemed` if it has prior redemptions).
    - `amount_type` 'cash' | 'discount_to_zero', required — Whether the voucher represents a fixed `cash` value or discounts the order it is redeemed against to zero (`discount_to_zero`).
    - `amount` integer, required — The face value of the voucher, in the smallest unit of the voucher's currency (e.g. pence for GBP).
    - `balance` integer, required — The remaining balance of the voucher, in the smallest unit of the voucher's currency. `discount_to_zero` vouchers report their balance as zero once redeemed.
    - `currency` string, required — The ISO-4217 currency code.
    - `value` integer, required — Alias of `amount`, retained for backwards compatibility with older clients.
    - `partially_redeemable` boolean, required — Whether the voucher can be redeemed across multiple transactions. `discount_to_zero` vouchers are never partially redeemable.
    - `uses_total` integer, nullable, required — For multi-use `discount_to_zero` codes only: the total number of redemptions the code allows. `null` when the parent `VoucherType` has `quantity` of `null` or `1`, and for all `cash` vouchers.
    - `uses_remaining` integer, nullable, required — For multi-use `discount_to_zero` codes only: how many redemptions are still available. Decrements by 1 each time the code is successfully redeemed; restored by 1 if a redemption is refunded. `null` when the parent `VoucherType` has `quantity` of `null` or `1`, and for all `cash` vouchers.
    - `imported` boolean, required — Whether this voucher was imported from a previous system rather than issued through Trybe.
    - `fulfillment_status` string, nullable, required — Tracks physical fulfilment for vouchers that need posting. Common values are `needs_dispatching`, `dispatched`, and `not_required` for digital deliveries.
    - `voucher_type` VoucherCodeVoucherTypeRef, required
      - `id` string, object-id, required — The ID of the `VoucherType` the voucher was issued against.
      - `name` string, required — The customer-facing name of the `VoucherType`.
    - `recipient` VoucherCodeRecipient, required — Recipient details captured at purchase time for gift vouchers. All fields are nullable — for self-purchase or digital vouchers the block may be entirely empty.
      - `name` string, nullable, required
      - `email` string, nullable, required
      - `custom_message` string, nullable, required — A free-form message the purchaser left for the recipient.
      - `address_line1` string, nullable, required
      - `address_line2` string, nullable, required
      - `city` string, nullable, required
      - `county` string, nullable, required
      - `country` string, nullable, required
      - `postcode` string, nullable, required
    - `delivery` VoucherCodeDelivery, required — How and when the voucher should be delivered to the recipient.
      - `method` string, nullable, required — The delivery channel — typically `email`, `post`, or the special value `print_at_home` for self-service downloads.
      - `option` VoucherDeliveryOption
        - `id` string, uuid, required — The unique identifier for the voucher delivery option
        - `name` string, required — A name to identify this voucher delivery option
        - `description` string, nullable, required — A description of this voucher delivery option
        - `site_id` string, uuid, required — The site ID that this voucher delivery option belongs to
        - `archived` boolean, required — When 'true', only archived voucher delivery options will be returned
        - `price` number, required — The price of the voucher delivery option as an integer of the smallest unit eg pence.
        - `revenue_centre` string, nullable, required — Contains the revenue centre ID if this line is for revenue.
      - `date` string, date-time, nullable, required — The date the voucher should be delivered on.
    - `order` VoucherCodeOrderRef, required — The order the voucher was purchased on.
      - `id` string, object-id, nullable, required — The ID of the parent order.
      - `customer_id` string, object-id, nullable, required — The ID of the purchasing customer.
      - `order_ref` string, nullable, required — The human-readable reference of the parent order.
      - `item_cost` integer, nullable, required — The amount paid for the voucher itself (which may differ from the voucher's face value for promotional pricing) in the smallest unit of the order currency.
      - `submitted_at` string, date-time, nullable, required — When the parent order was submitted.
    - `redemptions` VoucherCodeRedemption[] — Per-redemption breakdown — present on the `getVoucherCode` response, omitted from list responses for performance.
      - `payment_id` string, object-id, required — The ID of the `Payment` that records this redemption.
      - `amount` integer, required — The amount redeemed against the voucher in this transaction, in the smallest unit of the voucher's currency.
      - `refunded_amount` integer, required — Of `amount`, the portion that was later refunded back to the voucher (restoring its balance).
      - `paid_at` string, date-time, nullable, required — When the redemption was applied.
      - `payable_id` string, object-id, required — The ID of the object the redemption was applied to.
      - `order_ref` string — If the redemption was against an order, the human-readable order reference.
    - `created_at` string, date-time, required — When then resource was created.
    - `issued_at` string, date-time, nullable, required — When the voucher was issued to the customer. Vouchers that have been purchased but not yet issued (e.g. scheduled for a future delivery date) will have `issued_at` set to `null`.

## Other responses

- `401` — The user is unauthenticated
- `403` — The authenticated user does not have permission.

---

[API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)