Payments & Vouchers

Coupon Codes

Endpoints for retrieving coupon code information and statistics.

get/shop/coupons/{couponId}/codes

List codes for a coupon

listCouponCodes

Returns a paginated list of CouponCodes belonging to the given Coupon. Use this to inspect which codes have been generated, their validity windows, and whether they've been pre-allocated to specific customers.

Requires the RESERVATIONS_VIEW permission on the coupon's site.

Path parameters

couponIdobject-idrequired
Identifier of the coupon record. Returned from listCoupons and createCoupon; used to update the coupon, manage its offering discounts, or issue redemption codes.

Query parameters

pageintegeroptional
The page to retrieve results from
per_pageintegeroptional
The number of results to return per page

Responses

200
A paginated list of CouponCodes for the parent coupon.
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/coupons/abc123/codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/coupons/abc123/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/coupons/abc123/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/coupons/abc123/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/coupons/abc123/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)
}

A paginated list of `CouponCode`s for the parent coupon.

{
  "data": [
    {
      "id": "5f1234567890abcdef123456",
      "code": "SUMMER2026",
      "coupon_id": "5f1234567890abcdef123456",
      "valid_from_date": "2026-06-01T00:00:00Z",
      "valid_to_date": "2026-08-31T23:59:59Z",
      "multi_use": false,
      "customer_credit_id": "5f1234567890abcdef123456",
      "customer_id": "11111111-1111-1111-1111-111111111111",
      "revenue": 5000
    }
  ]
}

{
  "message": "Unauthenticated"
}

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

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

post/shop/coupons/{couponId}/codes

Create a coupon code

createCouponCode

Generates a new CouponCode under the parent Coupon. All body fields are optional — pass code to set a specific string, omit to auto-generate. Set valid_from_date/valid_to_date to time-limit the code, multi_use to allow multiple redemptions, and customer_credit_id + customer_id to pre-allocate it.

Requires the SETTINGS_MANAGE permission on the coupon's site. Returns 422 if code collides with another code under the same coupon (codes are unique per coupon, not globally).

Path parameters

couponIdobject-idrequired
Identifier of the coupon record. Returned from listCoupons and createCoupon; used to update the coupon, manage its offering discounts, or issue redemption codes.

Request body

codestringoptionalnullable
The redemption code customers type. Omitted = auto-generated. Must be unique within the coupon.
valid_from_datedate-timeoptionalnullable
ISO 8601 timestamp from which the code is redeemable. Null = valid immediately.
valid_to_datedate-timeoptionalnullable
ISO 8601 timestamp after which the code expires. Must be after valid_from_date if both are set.
multi_usebooleanoptionalnullable
When true, the code can be redeemed multiple times (once per customer). When false / omitted, the code is single-use.
customer_credit_idstringoptionalnullable
If set, pre-allocates the code to a specific CustomerCredit. Requires customer_id.
customer_iduuidoptionalnullable
ID of the customer this code is pre-allocated to. Required when customer_credit_id is set.
revenueintegeroptionalnullable
Override revenue in the smallest currency unit. Null = use the coupon's default.

Responses

201
A single CouponCode.
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/coupons/abc123/codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "SUMMER2026",
  "valid_from_date": "2026-06-01T00:00:00Z",
  "valid_to_date": "2026-08-31T23:59:59Z",
  "multi_use": false,
  "customer_credit_id": "5f1234567890abcdef123456",
  "customer_id": "11111111-1111-1111-1111-111111111111",
  "revenue": 5000
}'

const response = await fetch('https://api.playground.try.be/shop/coupons/abc123/codes', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    "code": "SUMMER2026",
    "valid_from_date": "2026-06-01T00:00:00Z",
    "valid_to_date": "2026-08-31T23:59:59Z",
    "multi_use": false,
    "customer_credit_id": "5f1234567890abcdef123456",
    "customer_id": "11111111-1111-1111-1111-111111111111",
    "revenue": 5000
  }),
})

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/coupons/abc123/codes",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "code": "SUMMER2026",
        "valid_from_date": "2026-06-01T00:00:00Z",
        "valid_to_date": "2026-08-31T23:59:59Z",
        "multi_use": False,
        "customer_credit_id": "5f1234567890abcdef123456",
        "customer_id": "11111111-1111-1111-1111-111111111111",
        "revenue": 5000
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.playground.try.be/shop/coupons/abc123/codes', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
            'code' => 'SUMMER2026',
            'valid_from_date' => '2026-06-01T00:00:00Z',
            'valid_to_date' => '2026-08-31T23:59:59Z',
            'multi_use' => false,
            'customer_credit_id' => '5f1234567890abcdef123456',
            'customer_id' => '11111111-1111-1111-1111-111111111111',
            'revenue' => 5000
        ],
]);

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

package main

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

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"code": "SUMMER2026",
		"valid_from_date": "2026-06-01T00:00:00Z",
		"valid_to_date": "2026-08-31T23:59:59Z",
		"multi_use": false,
		"customer_credit_id": "5f1234567890abcdef123456",
		"customer_id": "11111111-1111-1111-1111-111111111111",
		"revenue": 5000,
	})
	req, _ := http.NewRequest("POST", "https://api.playground.try.be/shop/coupons/abc123/codes", 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 `CouponCode`.

{
  "data": {
    "id": "5f1234567890abcdef123456",
    "code": "SUMMER2026",
    "coupon_id": "5f1234567890abcdef123456",
    "valid_from_date": "2026-06-01T00:00:00Z",
    "valid_to_date": "2026-08-31T23:59:59Z",
    "multi_use": false,
    "customer_credit_id": "5f1234567890abcdef123456",
    "customer_id": "11111111-1111-1111-1111-111111111111",
    "revenue": 5000
  }
}

{
  "message": "Unauthenticated"
}

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

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

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

get/shop/coupons/{couponId}/codes/{couponCodeId}

Retrieve a coupon code

getCouponCode

Returns a single CouponCode by ID, scoped to its parent Coupon. Use this to inspect a specific code's validity window or pre-allocation.

Requires the RESERVATIONS_VIEW permission on the coupon's site.

Path parameters

couponIdobject-idrequired
Identifier of the coupon record. Returned from listCoupons and createCoupon; used to update the coupon, manage its offering discounts, or issue redemption codes.
couponCodeIdobject-idrequired
The unique identifier of the CouponCode.

Responses

200
A single CouponCode.
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/coupons/abc123/codes/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/coupons/abc123/codes/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/coupons/abc123/codes/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/coupons/abc123/codes/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/coupons/abc123/codes/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 single `CouponCode`.

{
  "data": {
    "id": "5f1234567890abcdef123456",
    "code": "SUMMER2026",
    "coupon_id": "5f1234567890abcdef123456",
    "valid_from_date": "2026-06-01T00:00:00Z",
    "valid_to_date": "2026-08-31T23:59:59Z",
    "multi_use": false,
    "customer_credit_id": "5f1234567890abcdef123456",
    "customer_id": "11111111-1111-1111-1111-111111111111",
    "revenue": 5000
  }
}

{
  "message": "Unauthenticated"
}

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

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

delete/shop/coupons/{couponId}/codes/{couponCodeId}

Delete a coupon code

deleteCouponCode

Removes a CouponCode. Past redemptions are unaffected — the customer credit issued at redemption time persists. Future attempts to use the code fail with a 422.

Requires the SETTINGS_MANAGE permission on the coupon's site.

Path parameters

couponIdobject-idrequired
Identifier of the coupon record. Returned from listCoupons and createCoupon; used to update the coupon, manage its offering discounts, or issue redemption codes.
couponCodeIdobject-idrequired
The unique identifier of the CouponCode.

Responses

204
Coupon code deleted successfully.
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/coupons/abc123/codes/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

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

Coupon code deleted successfully.

// empty response

{
  "message": "Unauthenticated"
}

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

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

get/shop/coupon-codes/{code}/usage-stats

Get coupon code usage statistics

getCouponCodeUsageStats

Gets the usage statistics for a coupon code at a specific booking date. Returns null data if the coupon has no usage limits configured.

Path parameters

codestringrequired
The coupon code

Query parameters

booking_datestringrequired
The booking date to calculate usage stats for (YYYY-MM-DD or ISO8601 datetime)
site_idstringrequired
Filter results by the site they belong to
offering_idstringoptional
When provided, returns null data if the coupon does not apply to this offering

Responses

200
Usage statistics retrieved successfully
401
The user is unauthenticated
404
The resource couldn't be found
422
The request didn't pass validation

curl "https://api.playground.try.be/shop/coupon-codes/value/usage-stats?booking_date=value&site_id=site_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/coupon-codes/value/usage-stats?booking_date=value&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/coupon-codes/value/usage-stats?booking_date=value&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/coupon-codes/value/usage-stats?booking_date=value&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/coupon-codes/value/usage-stats?booking_date=value&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)
}

Usage statistics retrieved successfully

{
  "data": {
    "max_uses": 4,
    "current_uses": 2,
    "remaining_uses": 2,
    "period": "P1W",
    "period_label": "weekly",
    "period_start": "2025-11-10",
    "period_end": "2025-11-16",
    "would_exceed_limit": false
  }
}

{
  "message": "Unauthenticated"
}

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

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

get/shop/coupon-codes

List coupon codes across organisations

listCrossOrganisationCouponCodes

Returns a paginated list of every CouponCode visible to the calling user across every organisation they belong to. Use the code query filter to look up a single redemption code without knowing which coupon it belongs to — handy when a customer presents a code at point of sale and the staff member needs to navigate to the owning coupon.

Each entry includes the organisation_id of the owning coupon so consumers can route follow-up calls to the correct /shop/organisations/{organisationId}/... resource.

Requires the RESERVATIONS_VIEW permission on at least one site.

Query parameters

codestringoptional
Exact-match filter on the redemption code. Pair with pagination if you expect more than one match.
pageintegeroptional
The page to retrieve results from
per_pageintegeroptional
The number of results to return per page

Responses

200
A paginated list of coupon codes visible to the calling user across every organisation they are scoped to.
401
The user is unauthenticated
403
The authenticated user does not have permission.

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

const response = await fetch('https://api.playground.try.be/shop/coupon-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/coupon-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/coupon-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/coupon-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)
}

A paginated list of coupon codes visible to the calling user across every organisation they are scoped to.

{
  "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": "5f1234567890abcdef123456",
      "coupon_id": "5f1234567890abcdef123456",
      "code": "SUMMER2026",
      "valid_from_date": "2026-06-01T00:00:00+00:00",
      "valid_to_date": "2026-08-31T23:59:59+00:00",
      "multi_use": false,
      "organisation_id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

{
  "message": "Unauthenticated"
}

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

get/shop/coupon-codes/{code}/offering-discounts

Get the offering discount for a coupon code

getCouponCodeOfferingDiscounts

Returns the primary OfferingDiscount configured on the coupon behind the given redemption code. Useful at point of sale when you want to preview the offerings a coupon code applies to before asking the customer to commit it to a basket.

The lookup is scoped to the organisation derived from the caller's site context: if the code exists in another organisation the endpoint returns 404.

Requires the CUSTOMERS_VIEW permission.

Path parameters

codestringrequired
The coupon code

Responses

200
The first OfferingDiscount configured on the coupon backing the given code. Returned as a singleton (not an array) because the endpoint surfaces the primary discount eligibility for point-of-sale UIs.
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/coupon-codes/value/offering-discounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/coupon-codes/value/offering-discounts', {
  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/coupon-codes/value/offering-discounts",
    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/coupon-codes/value/offering-discounts', [
    '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/coupon-codes/value/offering-discounts", 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 first `OfferingDiscount` configured on the coupon backing the given code. Returned as a singleton (not an array) because the endpoint surfaces the primary discount eligibility for point-of-sale UIs.

{
  "data": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "offerings": [
      {
        "offering_type": "appointment",
        "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "offering_name": "Test offering"
      }
    ],
    "discount_type": "fixed_amount",
    "fixed_amount": 50,
    "percentage": 10
  }
}

{
  "message": "Unauthenticated"
}

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

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