Booking Flow

Voucher Codes

A VoucherCode is a single issued instance of a VoucherType — the redeemable code, its monetary balance, validity dates, recipient, and delivery metadata. VoucherCodes are produced by the basket pipeline when a voucher is purchased and consumed when the code is presented as payment against a future order.

get/shop/voucher-codes

List VoucherCodes

listVoucherCodes

Returns a paginated list of VoucherCodes. 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

pageintegeroptional
The page to retrieve results from
per_pageintegeroptional
The number of results to return per page
site_iduuidoptional
Filter the list of voucher codes to a single site.
codestringoptional
Partial, case-insensitive substring match on the voucher redemption code.
statusstring[]optional
Filter by voucher code status. Pass multiple statuses as a comma-separated list.
amountstringoptional
Filter by voucher amount. Supports comparison operators (>1000, <5000, >=2500, <=2500, =1000) — values are in the smallest unit of the voucher's currency.
balancestringoptional
Filter by remaining voucher balance. Supports the same comparison operators as amount.
created_sincedate-timeoptional
Filter for voucher codes created on or after this date-time.
voucher_type_idstring[]optional
Filter to voucher codes whose voucher_type_id matches one of the given IDs.
expired_range_fromdateoptional
Filter to voucher codes whose valid_to_date is on or after this date.
expired_range_todateoptional
Filter to voucher codes whose valid_to_date is before this date.
fulfillment_statusstringoptional
Filter by fulfilment status — needs_dispatching for vouchers awaiting physical delivery, dispatched once sent, not_required for digital deliveries.

Responses

200
Successfully retrieved VoucherCodes.
401
The user is unauthenticated
403
The authenticated user does not have permission.

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

const response = await fetch('https://api.playground.try.be/shop/voucher-codes', {
  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-codes",
    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-codes', [
    '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-codes", 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)
}

Successfully retrieved `VoucherCode`s.

{
  "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"
  },
  "meta": {
    "from": 1,
    "to": 2,
    "total": 2,
    "current_page": 1,
    "last_page": 2,
    "per_page": 15,
    "path": "http://example.com/api"
  },
  "data": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "code": "ABC123XYZ",
      "status": "unredeemed",
      "valid_from_date": "2026-01-01T00:00:00+00:00",
      "valid_to_date": "2027-01-01T00:00:00+00:00",
      "amount_type": "cash",
      "amount": 5000,
      "balance": 2500,
      "currency": "gbp",
      "value": 5000,
      "partially_redeemable": true,
      "imported": false,
      "fulfillment_status": "needs_dispatching",
      "voucher_type": {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "name": "Spa Day Gift Voucher"
      },
      "recipient": {
        "name": "Jane Doe",
        "email": "jane@example.com",
        "custom_message": "string",
        "address_line1": "1 Example Street",
        "address_line2": "1 Example Street",
        "city": "London",
        "county": "string",
        "country": "GB",
        "postcode": "SW1A 1AA"
      },
      "delivery": {
        "method": "post",
        "option": {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "First class mail",
          "description": "Free-form text from the resource.",
          "site_id": "00000000-0000-0000-0000-000000000000",
          "archived": false,
          "price": 5000,
          "revenue_centre": "spa"
        },
        "date": "2026-01-15T09:30:00+00:00"
      },
      "order": {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "customer_id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "order_ref": "TRY00",
        "item_cost": 5000,
        "submitted_at": "2026-01-15T09:30:00+00:00"
      },
      "redemptions": [
        {
          "payment_id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "amount": 2500,
          "refunded_amount": 0,
          "paid_at": "2026-01-15T09:30:00+00:00",
          "payable_id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "order_ref": "EXT-12345"
        }
      ],
      "created_at": "2025-02-04T12:00:00+01:00",
      "issued_at": "2026-01-02T09:00:00+00:00"
    }
  ]
}

{
  "message": "Unauthenticated"
}

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

get/shop/voucher-codes/{voucherCodeId}

Retrieve a VoucherCode

getVoucherCode

Retrieves a single VoucherCode by ID, including every redemption recorded against it. Use this when you have a voucher ID from a webhook payload, the listVoucherCodes response, or a customer-service search, and need the canonical record plus full redemption history.

Trashed (soft-deleted) voucher codes are returned by this endpoint with status of revoked, so customer-service flows can inspect revoked codes without a separate lookup.

Path parameters

voucherCodeIdobject-idrequired
The unique identifier of the VoucherCode. Each issued voucher has its own VoucherCode record holding the redemption code, balance, validity window, and fulfilment state.

Responses

200
The VoucherCode was successfully retrieved.
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/voucher-codes/5e932c0901d210625e3a8766" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/voucher-codes/5e932c0901d210625e3a8766', {
  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-codes/5e932c0901d210625e3a8766",
    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-codes/5e932c0901d210625e3a8766', [
    '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-codes/5e932c0901d210625e3a8766", 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 `VoucherCode` was successfully retrieved.

{
  "data": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "code": "ABC123XYZ",
    "status": "unredeemed",
    "valid_from_date": "2026-01-01T00:00:00+00:00",
    "valid_to_date": "2027-01-01T00:00:00+00:00",
    "amount_type": "cash",
    "amount": 5000,
    "balance": 2500,
    "currency": "gbp",
    "value": 5000,
    "partially_redeemable": true,
    "imported": false,
    "fulfillment_status": "needs_dispatching",
    "voucher_type": {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "name": "Spa Day Gift Voucher"
    },
    "recipient": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "custom_message": "string",
      "address_line1": "1 Example Street",
      "address_line2": "1 Example Street",
      "city": "London",
      "county": "string",
      "country": "GB",
      "postcode": "SW1A 1AA"
    },
    "delivery": {
      "method": "post",
      "option": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "First class mail",
        "description": "Free-form text from the resource.",
        "site_id": "00000000-0000-0000-0000-000000000000",
        "archived": false,
        "price": 5000,
        "revenue_centre": "spa"
      },
      "date": "2026-01-15T09:30:00+00:00"
    },
    "order": {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "customer_id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "order_ref": "TRY00",
      "item_cost": 5000,
      "submitted_at": "2026-01-15T09:30:00+00:00"
    },
    "redemptions": [
      {
        "payment_id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "amount": 2500,
        "refunded_amount": 0,
        "paid_at": "2026-01-15T09:30:00+00:00",
        "payable_id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "order_ref": "EXT-12345"
      }
    ],
    "created_at": "2025-02-04T12:00:00+01:00",
    "issued_at": "2026-01-02T09:00:00+00:00"
  }
}

{
  "message": "Unauthenticated"
}

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

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

put/shop/voucher-codes/{voucherCodeId}

Update a VoucherCode

updateVoucherCode

Updates a VoucherCode in place. The two fields most commonly changed are valid_to_date (to extend or shorten the voucher's expiry window) and fulfillment_status (to record physical dispatch).

The voucher's status is recalculated automatically when valid_to_date is changed: pushing the date past today on an expired voucher will move it back to unredeemed (or partially_redeemed if there have been redemptions); setting the date before today on a non-revoked voucher will move it to expired. revoked vouchers are never reactivated by a valid_to_date change.

Path parameters

voucherCodeIdobject-idrequired
The unique identifier of the VoucherCode. Each issued voucher has its own VoucherCode record holding the redemption code, balance, validity window, and fulfilment state.

Request body

valid_to_datedate-timeoptional
Extend or shorten the voucher's expiry. Setting a date in the past on an active voucher will move it to expired; setting a future date on an expired voucher will move it back to unredeemed (or partially_redeemed if there are prior redemptions). Must be an RFC 3339 timestamp.
fulfillment_statusstringoptional
Override the fulfilment status — typically used to mark a physical voucher as dispatched after posting.

Responses

200
The VoucherCode was successfully updated.
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/voucher-codes/5e932c0901d210625e3a8766" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "valid_to_date": "2027-01-01T23:59:59+00:00",
  "fulfillment_status": "dispatched"
}'

const response = await fetch('https://api.playground.try.be/shop/voucher-codes/5e932c0901d210625e3a8766', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    "valid_to_date": "2027-01-01T23:59:59+00:00",
    "fulfillment_status": "dispatched"
  }),
})

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/voucher-codes/5e932c0901d210625e3a8766",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "valid_to_date": "2027-01-01T23:59:59+00:00",
        "fulfillment_status": "dispatched"
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.playground.try.be/shop/voucher-codes/5e932c0901d210625e3a8766', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
            'valid_to_date' => '2027-01-01T23:59:59+00:00',
            'fulfillment_status' => 'dispatched'
        ],
]);

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

package main

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

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"valid_to_date": "2027-01-01T23:59:59+00:00",
		"fulfillment_status": "dispatched",
	})
	req, _ := http.NewRequest("PUT", "https://api.playground.try.be/shop/voucher-codes/5e932c0901d210625e3a8766", 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)
}

The `VoucherCode` was successfully updated.

{
  "data": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "code": "ABC123XYZ",
    "status": "unredeemed",
    "valid_from_date": "2026-01-01T00:00:00+00:00",
    "valid_to_date": "2027-01-01T00:00:00+00:00",
    "amount_type": "cash",
    "amount": 5000,
    "balance": 2500,
    "currency": "gbp",
    "value": 5000,
    "partially_redeemable": true,
    "imported": false,
    "fulfillment_status": "needs_dispatching",
    "voucher_type": {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "name": "Spa Day Gift Voucher"
    },
    "recipient": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "custom_message": "string",
      "address_line1": "1 Example Street",
      "address_line2": "1 Example Street",
      "city": "London",
      "county": "string",
      "country": "GB",
      "postcode": "SW1A 1AA"
    },
    "delivery": {
      "method": "post",
      "option": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "First class mail",
        "description": "Free-form text from the resource.",
        "site_id": "00000000-0000-0000-0000-000000000000",
        "archived": false,
        "price": 5000,
        "revenue_centre": "spa"
      },
      "date": "2026-01-15T09:30:00+00:00"
    },
    "order": {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "customer_id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "order_ref": "TRY00",
      "item_cost": 5000,
      "submitted_at": "2026-01-15T09:30:00+00:00"
    },
    "redemptions": [
      {
        "payment_id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "amount": 2500,
        "refunded_amount": 0,
        "paid_at": "2026-01-15T09:30:00+00:00",
        "payable_id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "order_ref": "EXT-12345"
      }
    ],
    "created_at": "2025-02-04T12:00:00+01:00",
    "issued_at": "2026-01-02T09:00: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/voucher-codes/{voucherCodeId}/revoke

Revoke a VoucherCode

actionRevokeVoucherCode

Revokes a VoucherCode, moving it to status revoked and preventing any further redemptions. Existing redemptions remain on the code's history. Used by customer-service teams when a voucher needs to be cancelled (for example after a chargeback on the purchasing order, or in response to a fraud report).

Revoking a code is permanent — there is no unrevoke. To restore spending power to a customer after a mistaken revoke, issue a fresh voucher.

Path parameters

voucherCodeIdobject-idrequired
The unique identifier of the VoucherCode. Each issued voucher has its own VoucherCode record holding the redemption code, balance, validity window, and fulfilment state.

Responses

200
The voucher code was successfully revoked.
401
The user is unauthenticated
403
The authenticated user does not have permission.
404
The resource couldn't be found

curl -X POST "https://api.playground.try.be/shop/voucher-codes/5e932c0901d210625e3a8766/revoke" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/voucher-codes/5e932c0901d210625e3a8766/revoke', {
  method: 'POST',
  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.post(
    "https://api.playground.try.be/shop/voucher-codes/5e932c0901d210625e3a8766/revoke",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.playground.try.be/shop/voucher-codes/5e932c0901d210625e3a8766/revoke', [
    '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("POST", "https://api.playground.try.be/shop/voucher-codes/5e932c0901d210625e3a8766/revoke", 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 code was successfully revoked.

{
  "data": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "code": "ABC123XYZ",
    "status": "unredeemed",
    "valid_from_date": "2026-01-01T00:00:00+00:00",
    "valid_to_date": "2027-01-01T00:00:00+00:00",
    "amount_type": "cash",
    "amount": 5000,
    "balance": 2500,
    "currency": "gbp",
    "value": 5000,
    "partially_redeemable": true,
    "imported": false,
    "fulfillment_status": "needs_dispatching",
    "voucher_type": {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "name": "Spa Day Gift Voucher"
    },
    "recipient": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "custom_message": "string",
      "address_line1": "1 Example Street",
      "address_line2": "1 Example Street",
      "city": "London",
      "county": "string",
      "country": "GB",
      "postcode": "SW1A 1AA"
    },
    "delivery": {
      "method": "post",
      "option": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "First class mail",
        "description": "Free-form text from the resource.",
        "site_id": "00000000-0000-0000-0000-000000000000",
        "archived": false,
        "price": 5000,
        "revenue_centre": "spa"
      },
      "date": "2026-01-15T09:30:00+00:00"
    },
    "order": {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "customer_id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "order_ref": "TRY00",
      "item_cost": 5000,
      "submitted_at": "2026-01-15T09:30:00+00:00"
    },
    "redemptions": [
      {
        "payment_id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "amount": 2500,
        "refunded_amount": 0,
        "paid_at": "2026-01-15T09:30:00+00:00",
        "payable_id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "order_ref": "EXT-12345"
      }
    ],
    "created_at": "2025-02-04T12:00:00+01:00",
    "issued_at": "2026-01-02T09:00:00+00:00"
  }
}

{
  "message": "Unauthenticated"
}

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

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