Payments & Vouchers

Vouchers

A Voucher is the catalogue-level record for a third-party gift voucher (e.g. one imported from GiftPro) that has been synced into Trybe and made redeemable at a site. Vouchers are managed via these endpoints — import the latest catalogue, list the synced records, fetch a single voucher, tweak its redemption rules, look up a redemption code at point of sale, or add/remove individual offerings on the allowlist. Trybe-native voucher products that are sold through the basket use VoucherType instead.

The Voucher object

Attributes

idobject-idrequired
The Trybe ID of the voucher record.
namestringrequired
Customer- and cashier-facing name of the voucher, mirrored from the source system at import time.
descriptionstringrequirednullable
Long-form description of the voucher imported from the source system. Shown to cashiers when redeeming.
processor_voucher_idstringrequired
The voucher's primary key in the external processor's system (e.g. the GiftPro voucher ID). Used to reconcile the Trybe record with the source of truth.
priceintegerrequired
The face value of the voucher in the smallest unit of currency (e.g. pence for gbp). Mirrored from the source system and used as the redemption amount when the voucher is presented as payment.
currencystringrequired
The ISO-4217 currency code (lowercase) the voucher's price is expressed in.
processorstringrequired
Identifier of the integration that owns this voucher. Drives which redemption flow Trybe routes the voucher through at checkout.
processor_dataobjectrequired
Processor-specific metadata captured at import time. Shape varies by processor; treat as opaque unless you specifically target a known integration.
valid_offeringsobject[]required
Offerings the voucher may be redeemed against. When the endpoint is called with offering summaries enabled (the default for getVoucher and the mutation endpoints), each entry is enriched with the offering's display name. When empty, the voucher is redeemable against any offering subject to the site's normal rules.
valid_weekdaysstring[]required
Lowercase weekday names the voucher may be redeemed on. Empty means "any weekday".
invalid_date_set_idsstring[]required
IDs of date sets (e.g. bank holidays, peak-season blackouts) on which the voucher may not be redeemed. Each ID must reference a date set on the caller's organisation.
site_iduuidrequired
The ID of the site this voucher record belongs to.
organisation_iduuidrequired
The ID of the organisation that owns the voucher record.
processor_created_atdate-timerequirednullable
When the voucher was created in the source processor's system.
created_atdate-timerequired
When the voucher record was imported into Trybe.
updated_atdate-timerequired
When the voucher record was last updated in Trybe.

{
  "id": "65f0a1b2c3d4e5f6a7b8c9d0",
  "name": "Twilight Spa Day Gift Voucher",
  "description": "A 90-minute treatment, lunch, and full access to the spa facilities.",
  "processor_voucher_id": "gp_8421",
  "price": 12500,
  "currency": "gbp",
  "processor": "giftpro",
  "processor_data": {},
  "valid_offerings": [
    {
      "offering_id": "65f0a1b2c3d4e5f6a7b8c9d1",
      "offering_type": "AppointmentType",
      "offering_name": "60-minute Aromatherapy Massage",
      "offering_details": {
        "membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
        "membership_type_name": "Wellness Club Gold",
        "membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "membership_rate_name": "Annual rolling",
        "duration": "P1Y",
        "duration_friendly": "1 year"
      }
    }
  ],
  "valid_weekdays": [
    "monday",
    "tuesday",
    "wednesday",
    "thursday",
    "friday"
  ],
  "invalid_date_set_ids": [
    "65f0a1b2c3d4e5f6a7b8c9aa"
  ],
  "site_id": "1f3c0e2a-9b8d-4c5e-a6f7-1234567890ab",
  "organisation_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "processor_created_at": "2025-12-15T09:30:00+00:00",
  "created_at": "2026-01-04T11:00:00+00:00",
  "updated_at": "2026-04-22T14:18:00+00:00"
}

get/shop/vouchers

List Vouchers

listVouchers

Returns a paginated list of Vouchers imported into the site. The list reflects vouchers managed by an external processor (e.g. GiftPro) that have been synced into Trybe via a previous importVouchers run.

Requires the RESERVATIONS_VIEW permission on the target site.

Query parameters

site_idstringrequired
Filter results by the site they belong to
pageintegeroptional
The page to retrieve results from
per_pageintegeroptional
The number of results to return per page

Responses

200
A paginated list of imported Vouchers for the requested site.
401
The user is unauthenticated
403
The authenticated user does not have permission.

curl "https://api.playground.try.be/shop/vouchers?site_id=site_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/vouchers?site_id=site_abc123', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    Accept: 'application/json',
  },
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.get(
    "https://api.playground.try.be/shop/vouchers?site_id=site_abc123",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.playground.try.be/shop/vouchers?site_id=site_abc123', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.playground.try.be/shop/vouchers?site_id=site_abc123", nil)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

A paginated list of imported `Voucher`s for the requested site.

{
  "data": [
    {
      "id": "65f0a1b2c3d4e5f6a7b8c9d0",
      "name": "Twilight Spa Day Gift Voucher",
      "description": "A 90-minute treatment, lunch, and full access to the spa facilities.",
      "processor_voucher_id": "gp_8421",
      "price": 12500,
      "currency": "gbp",
      "processor": "giftpro",
      "processor_data": {},
      "valid_offerings": [
        {
          "offering_id": "65f0a1b2c3d4e5f6a7b8c9d1",
          "offering_type": "AppointmentType",
          "offering_name": "60-minute Aromatherapy Massage",
          "offering_details": {
            "membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
            "membership_type_name": "Wellness Club Gold",
            "membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
            "membership_rate_name": "Annual rolling",
            "duration": "P1Y",
            "duration_friendly": "1 year"
          }
        }
      ],
      "valid_weekdays": [
        "monday",
        "tuesday",
        "wednesday",
        "thursday",
        "friday"
      ],
      "invalid_date_set_ids": [
        "65f0a1b2c3d4e5f6a7b8c9aa"
      ],
      "site_id": "1f3c0e2a-9b8d-4c5e-a6f7-1234567890ab",
      "organisation_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
      "processor_created_at": "2025-12-15T09:30:00+00:00",
      "created_at": "2026-01-04T11:00:00+00:00",
      "updated_at": "2026-04-22T14:18:00+00:00"
    }
  ],
  "meta": {
    "from": 1,
    "to": 2,
    "total": 2,
    "current_page": 1,
    "last_page": 2,
    "per_page": 15,
    "path": "http://example.com/api"
  },
  "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"
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

get/shop/vouchers/import

Import vouchers from the site's voucher processor

queueImportVouchers

Kicks off an asynchronous import that pulls the latest catalogue of vouchers from the site's configured voucher processor (e.g. GiftPro) and reconciles them with Trybe's local Voucher records. Vouchers present in the source system but missing in Trybe are created; existing records are updated to reflect any changes to name, price, currency, or redemption rules.

The endpoint returns a QueuedJob immediately — poll the queued job's status to track completion. The import does not block the request, so newly synced vouchers may not appear in listVouchers for a few seconds after the job completes.

Requires the SETTINGS_MANAGE permission on the target site.

Query parameters

site_idstringrequired
Filter results by the site they belong to

Responses

200
The job was successfully queued
401
The user is unauthenticated
403
The authenticated user does not have permission.

curl "https://api.playground.try.be/shop/vouchers/import?site_id=site_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/vouchers/import?site_id=site_abc123', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    Accept: 'application/json',
  },
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.get(
    "https://api.playground.try.be/shop/vouchers/import?site_id=site_abc123",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.playground.try.be/shop/vouchers/import?site_id=site_abc123', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.playground.try.be/shop/vouchers/import?site_id=site_abc123", nil)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

The job was successfully queued

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "status": "pending",
    "output": {},
    "created_at": "2023-11-07T00:00:00+00:00",
    "updated_at": "2023-11-07T01:00:00+00:00"
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

get/shop/vouchers/codes/{code}

Look up a voucher by its redemption code

actionCheckVoucherCode

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:

Trybe-native VoucherCodes 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.
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.

Path parameters

codestringrequired
The redemption code, exactly as quoted by the customer. Codes are case-sensitive and may contain letters, digits, and dashes (e.g. SUMMER2026-X9K2).

Query parameters

site_idstringrequired
Filter results by the site they belong to

Responses

200
Details of the looked-up voucher code, including its redeemable balance, expiry, and the offerings it may be applied to.
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

curl "https://api.playground.try.be/shop/vouchers/codes/SUMMER2026-X9K2?site_id=site_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/vouchers/codes/SUMMER2026-X9K2?site_id=site_abc123', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    Accept: 'application/json',
  },
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.get(
    "https://api.playground.try.be/shop/vouchers/codes/SUMMER2026-X9K2?site_id=site_abc123",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.playground.try.be/shop/vouchers/codes/SUMMER2026-X9K2?site_id=site_abc123', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.playground.try.be/shop/vouchers/codes/SUMMER2026-X9K2?site_id=site_abc123", nil)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

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

{
  "data": {
    "id": "65f0a1b2c3d4e5f6a7b8c9d2",
    "code": "SUMMER2026-X9K2",
    "payment_processor": "voucher",
    "processor_voucher_id": "gp_8421",
    "processor": "giftpro",
    "valid_from_date": "2026-01-01T00:00:00+00:00",
    "valid_to_date": "2027-01-01T00:00:00+00:00",
    "amount_type": "cash",
    "total": 5000,
    "balance": 2500,
    "currency": "gbp",
    "partially_redeemable": true,
    "voucher_name": "£50 Gift Voucher",
    "customer_id": "65f0a1b2c3d4e5f6a7b8c9d3",
    "fulfillment_status": "dispatched",
    "value": 5000,
    "valid_offerings": [
      {
        "offering_type": "appointment",
        "offering_id": "65f0a1b2c3d4e5f6a7b8c9d4",
        "offering_name": "60-minute Aromatherapy Massage",
        "display_name": "60-minute Aromatherapy Massage",
        "offering_config": {
          "duration": "P1Y"
        }
      }
    ]
  }
}

{
  "message": "This voucher has already been redeemed."
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

{
  "message": "The requested resource could not be found"
}

get/shop/vouchers/{voucherId}

Retrieve a Voucher

getVoucher

Returns a single imported Voucher, enriched with the display names of every offering in its valid_offerings allowlist.

Requires the view ability on the Voucher — granted by holding RESERVATIONS_VIEW on the voucher's site.

Path parameters

voucherIdobject-idrequired
The ID of the Voucher to operate on.

Responses

200
A single Voucher.
401
The user is unauthenticated
403
The authenticated user does not have permission.
404
The resource couldn't be found

curl "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    Accept: 'application/json',
  },
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.get(
    "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0", nil)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

A single `Voucher`.

{
  "data": {
    "id": "65f0a1b2c3d4e5f6a7b8c9d0",
    "name": "Twilight Spa Day Gift Voucher",
    "description": "A 90-minute treatment, lunch, and full access to the spa facilities.",
    "processor_voucher_id": "gp_8421",
    "price": 12500,
    "currency": "gbp",
    "processor": "giftpro",
    "processor_data": {},
    "valid_offerings": [
      {
        "offering_id": "65f0a1b2c3d4e5f6a7b8c9d1",
        "offering_type": "AppointmentType",
        "offering_name": "60-minute Aromatherapy Massage",
        "offering_details": {
          "membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
          "membership_type_name": "Wellness Club Gold",
          "membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "membership_rate_name": "Annual rolling",
          "duration": "P1Y",
          "duration_friendly": "1 year"
        }
      }
    ],
    "valid_weekdays": [
      "monday",
      "tuesday",
      "wednesday",
      "thursday",
      "friday"
    ],
    "invalid_date_set_ids": [
      "65f0a1b2c3d4e5f6a7b8c9aa"
    ],
    "site_id": "1f3c0e2a-9b8d-4c5e-a6f7-1234567890ab",
    "organisation_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "processor_created_at": "2025-12-15T09:30:00+00:00",
    "created_at": "2026-01-04T11:00:00+00:00",
    "updated_at": "2026-04-22T14:18:00+00:00"
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

{
  "message": "The requested resource could not be found"
}

put/shop/vouchers/{voucherId}

Update a Voucher

updateVoucher

Updates the redemption rules attached to an imported Voucher. Currently three fields are mutable — valid_offerings, valid_weekdays, and invalid_date_set_ids. Other catalogue fields (name, price, currency, processor metadata) are sourced from the upstream processor and refresh on the next importVouchers run.

Requires the update ability on the Voucher — typically granted by holding SETTINGS_MANAGE on the voucher's site.

Path parameters

voucherIdobject-idrequired
The ID of the Voucher to operate on.

Request body

valid_offeringsobject[]optional
Replacement allowlist of offerings the voucher may be redeemed against. Pass an empty array to clear the allowlist (making the voucher redeemable against any offering).
valid_weekdaysstring[]optional
Lowercase weekday names the voucher may be redeemed on. Empty (or omitted) means "any weekday".
invalid_date_set_idsstring[]optional
IDs of date sets on which the voucher may not be redeemed. Each ID must reference a date set on the caller's organisation.

Responses

200
A single Voucher.
401
The user is unauthenticated
403
The authenticated user does not have permission.
404
The resource couldn't be found
422
The request didn't pass validation

curl -X PUT "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "valid_offerings": [
    {
      "offering_id": "65f0a1b2c3d4e5f6a7b8c9d4",
      "offering_type": "appointment",
      "offering_details": {
        "membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
        "membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "duration": "P1Y"
      }
    }
  ],
  "valid_weekdays": [
    "monday",
    "tuesday",
    "wednesday",
    "thursday",
    "friday"
  ],
  "invalid_date_set_ids": [
    "65f0a1b2c3d4e5f6a7b8c9aa"
  ]
}'

const response = await fetch('https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    "valid_offerings": [
      {
        "offering_id": "65f0a1b2c3d4e5f6a7b8c9d4",
        "offering_type": "appointment",
        "offering_details": {
          "membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
          "membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "duration": "P1Y"
        }
      }
    ],
    "valid_weekdays": [
      "monday",
      "tuesday",
      "wednesday",
      "thursday",
      "friday"
    ],
    "invalid_date_set_ids": [
      "65f0a1b2c3d4e5f6a7b8c9aa"
    ]
  }),
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.put(
    "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "valid_offerings": [
            {
                "offering_id": "65f0a1b2c3d4e5f6a7b8c9d4",
                "offering_type": "appointment",
                "offering_details": {
                    "membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
                    "membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                    "duration": "P1Y"
                }
            }
        ],
        "valid_weekdays": [
            "monday",
            "tuesday",
            "wednesday",
            "thursday",
            "friday"
        ],
        "invalid_date_set_ids": [
            "65f0a1b2c3d4e5f6a7b8c9aa"
        ]
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
            'valid_offerings' => [
                [
                    'offering_id' => '65f0a1b2c3d4e5f6a7b8c9d4',
                    'offering_type' => 'appointment',
                    'offering_details' => [
                        'membership_type_id' => '9c8b7a6d-5e4f-3210-9876-543210fedcba',
                        'membership_rate_id' => 'a1b2c3d4-e5f6-7890-1234-567890abcdef',
                        'duration' => 'P1Y'
                    ]
                ]
            ],
            'valid_weekdays' => [
                'monday',
                'tuesday',
                'wednesday',
                'thursday',
                'friday'
            ],
            'invalid_date_set_ids' => [
                '65f0a1b2c3d4e5f6a7b8c9aa'
            ]
        ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"valid_offerings": []interface{}{
			map[string]interface{}{
				"offering_id": "65f0a1b2c3d4e5f6a7b8c9d4",
				"offering_type": "appointment",
				"offering_details": map[string]interface{}{
					"membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
					"membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
					"duration": "P1Y",
				},
			},
		},
		"valid_weekdays": []interface{}{
			"monday",
			"tuesday",
			"wednesday",
			"thursday",
			"friday",
		},
		"invalid_date_set_ids": []interface{}{
			"65f0a1b2c3d4e5f6a7b8c9aa",
		},
	})
	req, _ := http.NewRequest("PUT", "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0", bytes.NewBuffer(payload))
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

A single `Voucher`.

{
  "data": {
    "id": "65f0a1b2c3d4e5f6a7b8c9d0",
    "name": "Twilight Spa Day Gift Voucher",
    "description": "A 90-minute treatment, lunch, and full access to the spa facilities.",
    "processor_voucher_id": "gp_8421",
    "price": 12500,
    "currency": "gbp",
    "processor": "giftpro",
    "processor_data": {},
    "valid_offerings": [
      {
        "offering_id": "65f0a1b2c3d4e5f6a7b8c9d1",
        "offering_type": "AppointmentType",
        "offering_name": "60-minute Aromatherapy Massage",
        "offering_details": {
          "membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
          "membership_type_name": "Wellness Club Gold",
          "membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "membership_rate_name": "Annual rolling",
          "duration": "P1Y",
          "duration_friendly": "1 year"
        }
      }
    ],
    "valid_weekdays": [
      "monday",
      "tuesday",
      "wednesday",
      "thursday",
      "friday"
    ],
    "invalid_date_set_ids": [
      "65f0a1b2c3d4e5f6a7b8c9aa"
    ],
    "site_id": "1f3c0e2a-9b8d-4c5e-a6f7-1234567890ab",
    "organisation_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "processor_created_at": "2025-12-15T09:30:00+00:00",
    "created_at": "2026-01-04T11:00:00+00:00",
    "updated_at": "2026-04-22T14:18:00+00:00"
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

{
  "message": "The requested resource could not be found"
}

{
  "errors": {},
  "message": "The request didn't pass validation"
}

post/shop/vouchers/{voucherId}/offerings

Add an offering to a voucher's valid-offerings allowlist

createVoucherValidOffering

Appends a single offering to the voucher's valid_offerings list. No-op if the offering is already present (idempotent on offering_id).

Use the bulk updateVoucher endpoint when replacing the entire allowlist in one call.

Requires the update ability on the Voucher — typically granted by holding SETTINGS_MANAGE on the voucher's site.

Path parameters

voucherIdobject-idrequired
The ID of the Voucher to operate on.

Request body

offering_typestringrequired
Snake-case type of the offering being added (e.g. appointment, session, package).
Possible values:appointmentarea_bookingcoursehotel_room_reservationpackageproductsessiontable_reservation
offering_idstringrequired
Identifier of the offering to add to this voucher's valid-offerings list. Paired with offering_type to disambiguate which collection the ID belongs to.

Responses

200
A single Voucher.
401
The user is unauthenticated
403
The authenticated user does not have permission.
404
The resource couldn't be found
422
The request didn't pass validation

curl -X POST "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "offering_type": "session",
  "offering_id": "65f0a1b2c3d4e5f6a7b8c9d4"
}'

const response = await fetch('https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    "offering_type": "session",
    "offering_id": "65f0a1b2c3d4e5f6a7b8c9d4"
  }),
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.post(
    "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "offering_type": "session",
        "offering_id": "65f0a1b2c3d4e5f6a7b8c9d4"
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
            'offering_type' => 'session',
            'offering_id' => '65f0a1b2c3d4e5f6a7b8c9d4'
        ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"offering_type": "session",
		"offering_id": "65f0a1b2c3d4e5f6a7b8c9d4",
	})
	req, _ := http.NewRequest("POST", "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings", bytes.NewBuffer(payload))
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

A single `Voucher`.

{
  "data": {
    "id": "65f0a1b2c3d4e5f6a7b8c9d0",
    "name": "Twilight Spa Day Gift Voucher",
    "description": "A 90-minute treatment, lunch, and full access to the spa facilities.",
    "processor_voucher_id": "gp_8421",
    "price": 12500,
    "currency": "gbp",
    "processor": "giftpro",
    "processor_data": {},
    "valid_offerings": [
      {
        "offering_id": "65f0a1b2c3d4e5f6a7b8c9d1",
        "offering_type": "AppointmentType",
        "offering_name": "60-minute Aromatherapy Massage",
        "offering_details": {
          "membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
          "membership_type_name": "Wellness Club Gold",
          "membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "membership_rate_name": "Annual rolling",
          "duration": "P1Y",
          "duration_friendly": "1 year"
        }
      }
    ],
    "valid_weekdays": [
      "monday",
      "tuesday",
      "wednesday",
      "thursday",
      "friday"
    ],
    "invalid_date_set_ids": [
      "65f0a1b2c3d4e5f6a7b8c9aa"
    ],
    "site_id": "1f3c0e2a-9b8d-4c5e-a6f7-1234567890ab",
    "organisation_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "processor_created_at": "2025-12-15T09:30:00+00:00",
    "created_at": "2026-01-04T11:00:00+00:00",
    "updated_at": "2026-04-22T14:18:00+00:00"
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

{
  "message": "The requested resource could not be found"
}

{
  "errors": {},
  "message": "The request didn't pass validation"
}

delete/shop/vouchers/{voucherId}/offerings/{offeringId}

Remove an offering from a voucher's valid-offerings allowlist

deleteVoucherValidOffering

Removes the offering identified by offeringId from the voucher's valid_offerings list. No-op if the offering is not present. Returns the updated Voucher with offering display names included.

Requires the update ability on the Voucher — typically granted by holding SETTINGS_MANAGE on the voucher's site.

Path parameters

voucherIdobject-idrequired
The ID of the Voucher to operate on.
offeringIdstringrequired
The ID of the offering to remove from the voucher's valid_offerings allowlist. For membership offerings, this is the composite ID exposed by the getVoucher response (of the form {membership_type_id}_{membership_rate_id}_{duration}).

Responses

200
A single Voucher.
401
The user is unauthenticated
403
The authenticated user does not have permission.
404
The resource couldn't be found

curl -X DELETE "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings/65f0a1b2c3d4e5f6a7b8c9d4" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings/65f0a1b2c3d4e5f6a7b8c9d4', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    Accept: 'application/json',
  },
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.delete(
    "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings/65f0a1b2c3d4e5f6a7b8c9d4",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings/65f0a1b2c3d4e5f6a7b8c9d4', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.playground.try.be/shop/vouchers/65f0a1b2c3d4e5f6a7b8c9d0/offerings/65f0a1b2c3d4e5f6a7b8c9d4", nil)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

A single `Voucher`.

{
  "data": {
    "id": "65f0a1b2c3d4e5f6a7b8c9d0",
    "name": "Twilight Spa Day Gift Voucher",
    "description": "A 90-minute treatment, lunch, and full access to the spa facilities.",
    "processor_voucher_id": "gp_8421",
    "price": 12500,
    "currency": "gbp",
    "processor": "giftpro",
    "processor_data": {},
    "valid_offerings": [
      {
        "offering_id": "65f0a1b2c3d4e5f6a7b8c9d1",
        "offering_type": "AppointmentType",
        "offering_name": "60-minute Aromatherapy Massage",
        "offering_details": {
          "membership_type_id": "9c8b7a6d-5e4f-3210-9876-543210fedcba",
          "membership_type_name": "Wellness Club Gold",
          "membership_rate_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "membership_rate_name": "Annual rolling",
          "duration": "P1Y",
          "duration_friendly": "1 year"
        }
      }
    ],
    "valid_weekdays": [
      "monday",
      "tuesday",
      "wednesday",
      "thursday",
      "friday"
    ],
    "invalid_date_set_ids": [
      "65f0a1b2c3d4e5f6a7b8c9aa"
    ],
    "site_id": "1f3c0e2a-9b8d-4c5e-a6f7-1234567890ab",
    "organisation_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "processor_created_at": "2025-12-15T09:30:00+00:00",
    "created_at": "2026-01-04T11:00:00+00:00",
    "updated_at": "2026-04-22T14:18:00+00:00"
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

{
  "message": "The requested resource could not be found"
}

get/shop/voucher-lookup/{voucherCode}

Look up voucher details by code

getVoucherLookup

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 VoucherCodes and integration-issued external vouchers (e.g. GiftPro) — see the payment_processor discriminator on the response.

Path parameters

voucherCodestringrequired
The voucher code to look up.

Query parameters

site_idstringrequired
Filter results by the site they belong to

Responses

200
The voucher details were successfully retrieved.
401
The user is unauthenticated
404
The resource couldn't be found

curl "https://api.playground.try.be/shop/voucher-lookup/ABC123XYZ?site_id=site_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/voucher-lookup/ABC123XYZ?site_id=site_abc123', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    Accept: 'application/json',
  },
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.get(
    "https://api.playground.try.be/shop/voucher-lookup/ABC123XYZ?site_id=site_abc123",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.playground.try.be/shop/voucher-lookup/ABC123XYZ?site_id=site_abc123', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.playground.try.be/shop/voucher-lookup/ABC123XYZ?site_id=site_abc123", nil)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

The voucher details were successfully retrieved.

{
  "data": {
    "id": "65f0a1b2c3d4e5f6a7b8c9d2",
    "code": "SUMMER2026-X9K2",
    "payment_processor": "voucher",
    "processor_voucher_id": "gp_8421",
    "processor": "giftpro",
    "valid_from_date": "2026-01-01T00:00:00+00:00",
    "valid_to_date": "2027-01-01T00:00:00+00:00",
    "amount_type": "cash",
    "total": 5000,
    "balance": 2500,
    "currency": "gbp",
    "partially_redeemable": true,
    "voucher_name": "£50 Gift Voucher",
    "customer_id": "65f0a1b2c3d4e5f6a7b8c9d3",
    "fulfillment_status": "dispatched",
    "value": 5000,
    "valid_offerings": [
      {
        "offering_type": "appointment",
        "offering_id": "65f0a1b2c3d4e5f6a7b8c9d4",
        "offering_name": "60-minute Aromatherapy Massage",
        "display_name": "60-minute Aromatherapy Massage",
        "offering_config": {
          "duration": "P1Y"
        }
      }
    ]
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "The requested resource could not be found"
}