Look up a gift voucher code

GET/v2/retail-vouchers/{code}

Requires your API key in the X-API-Key header.

Resolves a gift voucher code: the voucher product, how many uses it grants and has left (uses held by unconfirmed orders already count), whether a redemption may include an add-on, the experiences it can be redeemed against, and the redemptions already made (experience, date and status only). Use it to check a code before redeeming it on an order. Only a paid voucher resolves: an unknown, cancelled or refunded code returns 404 (VOUCHER_INVALID). The 10-character retailCode of the purchase is a reference, not a voucher code.

Requestbash
curl "https://api.turneo.co/v2/retail-vouchers/7WF4MRY2KC8N" \
  -H "X-API-Key: <your-api-key>"

Path parameters

  • codestringrequired

    The gift voucher code (12 characters), as emailed to the voucher's holder.

    Example:
    7WF4MRY2KC8N

Responses

200object

What the voucher covers right now.

  • voucherCodestring

    The code that was looked up.

    Example:
    7WF4MRY2KC8N
  • voucherNamemap of string

    Name of the voucher product, as a per-language object (not resolved by language).

  • voucherSourceLanguagestringnullable

    Language the product's content was written in, when known.

    Example:
    en
  • allowedUsesinteger

    Total uses the voucher grants.

    Example:
    5
  • remainingUsesinteger

    Uses left. Uses held by unconfirmed orders count as used.

    Example:
    3
  • includesAddonboolean

    Whether a redeemed booking may include one add-on of its option.

    Example:
    false
  • scopeExperiencesobject[]

    The experiences the voucher can be redeemed against right now.

    Child fields
    • idstring (uuid)

      Experience UUID.

      Example:
      0d4dbb2e-8a51-4a4b-9d3e-6f2b7c1a9e55
    • namemap of string

      Experience name, as a per-language object.

    • sourceLanguagestringnullable

      Language the experience's content was written in, when known.

      Example:
      en
  • redemptionsobject[]

    Uses already spent, newest first. No booking or traveler details are included.

    Child fields
    • experienceNamemap of string

      Name of the redeemed experience, as a per-language object.

    • sourceLanguagestringnullable

      Language the experience's content was written in, when known.

      Example:
      en
    • datestring (date-time)nullable

      When the redeemed booking takes place.

      Example:
      2026-08-02T10:00:00Z
    • statusstring

      Status of the redeemed booking.

      Example:
      ACCEPTED
Response 200json
{
  "voucherCode": "7WF4MRY2KC8N",
  "voucherName": {
    "en": "Spa day gift voucher"
  },
  "voucherSourceLanguage": "en",
  "allowedUses": 5,
  "remainingUses": 3,
  "includesAddon": false,
  "scopeExperiences": [
    {
      "id": "0d4dbb2e-8a51-4a4b-9d3e-6f2b7c1a9e55",
      "name": {
        "en": "Sunset Kayak Tour"
      },
      "sourceLanguage": "en"
    }
  ],
  "redemptions": [
    {
      "experienceName": {
        "en": "Sunset Kayak Tour"
      },
      "sourceLanguage": "en",
      "date": "2026-08-02T10:00:00Z",
      "status": "ACCEPTED"
    }
  ]
}

Errors

401

Missing or invalid X-API-Key header.

404

The resource does not exist or belongs to another partner (existence is not leaked across partners).

Error body
  • typestring

    Error class.

    Allowed values:
    validation_errorclient_errorserver_error
    Example:
    validation_error
  • errorsobject[]
    Child fields
    • codestring

      Machine-readable error code.

      Example:
      required
    • fieldstringnullable

      Offending field, or null/'general' for non-field errors.

      Example:
      startTime
    • messagestring

      Human-readable message.

      Example:
      This field is required.
Response 401json
{
  "type": "validation_error",
  "errors": [
    {
      "code": "required",
      "field": "startTime",
      "message": "This field is required."
    }
  ]
}