---
title: "Look up voucher details by code"
method: GET
path: "/shop/voucher-lookup/{voucherCode}"
tags: ["Vouchers"]
---

# Look up voucher details by code

`GET /shop/voucher-lookup/{voucherCode}`

Public endpoint for resolving a voucher code into the runtime
`VoucherCodeLookup` shape — its remaining balance, validity
window, owning voucher type or external voucher, and the list of
offerings the code may be redeemed against. Used by the customer-
facing storefront to validate a code at checkout before the basket
is committed.

Supports both Trybe-native `VoucherCode`s and integration-issued
external vouchers (e.g. GiftPro) — see the `payment_processor`
discriminator on the response.

## Response `200`

The voucher details were successfully retrieved.

- 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

- `401` — The user is unauthenticated
- `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)