---
title: "Look up a voucher by its redemption code"
method: GET
path: "/shop/vouchers/codes/{code}"
tags: ["Vouchers"]
---

# Look up a voucher by its redemption code

`GET /shop/vouchers/codes/{code}`

Resolves a redemption code to a usable voucher and reports its
current redeemable balance, expiry window, and the offerings it
may be applied to. Use this endpoint at the point of sale to
validate a code presented by a customer before applying it as
payment.

The lookup follows a two-tier search:

1. Trybe-native `VoucherCode`s issued through the basket are checked
   first; if found, the voucher's usability is asserted (it must be
   within its validity window and have balance remaining) and the
   canonical record is returned.
2. If the site has an active voucher integration (e.g. GiftPro),
   the code is then looked up in the external processor. External
   vouchers are returned in the same response shape with
   `payment_processor=external_voucher`.

Returns `400 Bad Request` if the code is found but is already
fully redeemed or expired, and `404 Not Found` if the code does
not exist in either store.

## Query parameters

- `site_id` string, required

## Response `200`

Details of the looked-up voucher code, including its redeemable
balance, expiry, and the offerings it may be applied to.

- object
  - `data` VoucherCodeLookup, required — The runtime view of a voucher code returned by `checkVoucherCode`. Carries the redeemable balance, validity window, owning voucher type or external voucher, and the list of offerings the code may be redeemed against. The payload shape varies slightly depending on whether the code is a Trybe-native `VoucherCode` or an integration-issued external voucher (e.g. GiftPro) — see the `payment_processor` discriminator.
    - `id` string, object-id — The ID of the Trybe `VoucherCode`. Omitted for external vouchers — use `processor_voucher_id` instead.
    - `code` string, required — The redemption code itself, as quoted by the customer.
    - `payment_processor` 'voucher' | 'external_voucher', required — Discriminator identifying which redemption flow applies. `voucher` is a Trybe-native code, `external_voucher` is an integration-issued code that will be reconciled with the external processor at redemption time.
    - `processor_voucher_id` string, nullable — For external vouchers, the voucher's primary key in the source processor's system. Omitted for Trybe-native codes.
    - `processor` string, nullable — For external vouchers, the integration that issued the code (e.g. `giftpro`). Omitted for Trybe-native codes.
    - `valid_from_date` string, date-time, nullable, required — The earliest date the code may be redeemed.
    - `valid_to_date` string, date-time, nullable, required — The latest date the code may be redeemed. `null` indicates the code does not expire.
    - `amount_type` 'cash' | 'discount_to_zero', required — Whether the code carries a fixed cash value (`cash`) or discounts the order it is redeemed against to zero (`discount_to_zero`). External vouchers are always reported as `cash`.
    - `total` integer, required — The original face value of the code, in the smallest unit of `currency`.
    - `balance` integer, required — The remaining redeemable balance, in the smallest unit of `currency`. For `discount_to_zero` vouchers, reports `0` once the voucher has been redeemed.
    - `currency` string, required — The ISO-4217 currency code (lowercase).
    - `partially_redeemable` boolean, required — Whether the remaining balance can be split across multiple redemptions. `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. `null` when the parent `VoucherType` has `quantity` of `null` or `1`, and for all `cash` vouchers.
    - `voucher_name` string, nullable, required — The display name of the parent `VoucherType` (for Trybe-native codes) or `Voucher` (for external codes). May be `null` for external codes that could not be matched back to a Trybe `Voucher` record.
    - `customer_id` string, object-id, nullable — The ID of the customer the code was issued to, if known. Omitted for external vouchers.
    - `fulfillment_status` string, nullable — Fulfilment status of the voucher (e.g. `needs_dispatching`, `dispatched`, `not_required`). Omitted for external vouchers.
    - `value` integer — Alias of `total`, retained for backwards compatibility with older clients. Omitted for external vouchers.
    - `valid_offerings` VoucherCodeLookupOffering[], required — The offerings the code may be redeemed against. Includes offering display names and offering-type-specific configuration (e.g. for membership vouchers, the duration of the granted membership).
      - `offering_type` string, required — Snake-case type discriminator (e.g. `appointment`, `session`, `package`, `membership`).
      - `offering_id` string, required — The ID of the offering.
      - `offering_name` string, required — The plain display name of the offering, resolved from the offering's `name` if necessary.
      - `display_name` string, required — A pre-formatted display name for the offering — identical to `offering_name` for non-membership offerings, augmented with the granted duration for `membership` offerings (e.g. `Wellness Club Gold (1 year)`).
      - `offering_config` object — Offering-type-specific configuration. Present only when the offering needs extra metadata at redemption time — currently only `membership` offerings, where the block carries the granted duration.

## Other responses

- `400` — The voucher code is recognised but cannot be redeemed — typically because it has already been redeemed or has expired.
- `401` — The user is unauthenticated
- `403` — The authenticated user does not have permission.
- `404` — The resource couldn't be found

---

[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)