Payments & Vouchers

Coupons

A Coupon represents a form of credit against a membership.

The Coupon object

Attributes

idobject-idrequired
The ID of the coupon
namestringrequired
The name of the coupon
descriptionstringrequired
A string to describe the coupon
offering_discountsobject[]required
An array of offering_discounts belonging to this coupon. Each offering_discount describes what offerings the coupon is valid for.
currencystringrequired
The currency of any amounts to be applied.
valid_weekdaysstring[]required
An array of weekdays which this coupon is available for use
invalid_date_set_idsstring[]required
An array of IDs of DateSets describing when this coupon is not valid. The DateSet must belong to the same organisation as the coupon.
default_validity_intervalstringrequired
The default duration this coupon is valid for, as an ISO8601 string. See https://en.wikipedia.org/wiki/ISO_8601#Durations
default_multi_usebooleanrequired
The default for whether a code created from this coupon may be used multiple times
for_lead_booker_onlybooleanrequired
If true, only the lead booker of an order will be able to use this coupon. If false, any guest on the order will be able to use the coupon, including non-members.
max_usesintegerrequirednullable
The maximum number of times this coupon can be used within the specified max uses period
max_uses_periodstringrequirednullable
The time period for usage limits when max_uses is set. The duration is specified as an ISO8601 duration string. See https://en.wikipedia.org/wiki/ISO_8601#Durations P1D = daily limit, P1W = weekly limit, P1M = monthly limit, P1Y = yearly limit
Possible values:P1DP1WP1MP1Y
redemption_typestringrequired
The redemption type of the coupon.
Possible values:manualprogrammatic
site_iduuidrequirednullable
The ID of the site this coupon belongs to.
created_atdate-timerequired
The time and date that the coupon was created.
updated_atdate-timerequired
The time and date that the coupon was last updated.
deleted_atdate-timerequirednullable
The time and date that the coupon was soft-deleted.

{
  "id": "64a9f3b2c3d8e1f4a5b6c7d8",
  "name": "Test coupon",
  "description": "This coupon is a test",
  "offering_discounts": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "offerings": [
        {
          "offering_type": "appointment",
          "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8",
          "offering_name": "Test offering"
        }
      ],
      "discount_type": "fixed_amount",
      "fixed_amount": 50,
      "percentage": 10
    }
  ],
  "currency": "gbp",
  "valid_weekdays": [
    "monday"
  ],
  "invalid_date_set_ids": [
    "64a9f3b2c3d8e1f4a5b6c7d8"
  ],
  "default_validity_interval": "P1Y",
  "default_multi_use": true,
  "for_lead_booker_only": true,
  "max_uses": 2,
  "max_uses_period": "P1D",
  "redemption_type": "manual",
  "site_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2020-02-24T12:00:00+01:00",
  "updated_at": "2020-02-24T12:00:00+01:00",
  "deleted_at": "2020-02-24T12:00:00+01:00"
}

get/shop/coupons

Creates a copy of an existing Coupon. Useful when seeding a similar coupon (e.g. a renewal of a seasonal promotion, or a sibling coupon scoped to a different segment). The copy inherits every field from the source; rename it via a subsequent PUT /shop/coupons/{couponId}.

Requires the copy permission on the source Coupon (see resourceAbilityMap on CouponController). No request body.

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.

Responses

201
The coupon was successfully created
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/coupons/abc123/copy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/coupons/abc123/copy', {
  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/coupons/abc123/copy",
    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/coupons/abc123/copy', [
    '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/coupons/abc123/copy", 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 coupon was successfully created

{
  "data": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "name": "Test coupon",
    "description": "This coupon is a test",
    "offering_discounts": [
      {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "offerings": [
          {
            "offering_type": "appointment",
            "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8",
            "offering_name": "Test offering"
          }
        ],
        "discount_type": "fixed_amount",
        "fixed_amount": 50,
        "percentage": 10
      }
    ],
    "currency": "gbp",
    "valid_weekdays": [
      "monday"
    ],
    "invalid_date_set_ids": [
      "64a9f3b2c3d8e1f4a5b6c7d8"
    ],
    "default_validity_interval": "P1Y",
    "default_multi_use": true,
    "for_lead_booker_only": true,
    "max_uses": 2,
    "max_uses_period": "P1D",
    "redemption_type": "manual",
    "site_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2020-02-24T12:00:00+01:00",
    "updated_at": "2020-02-24T12:00:00+01:00",
    "deleted_at": "2020-02-24T12:00:00+01:00"
  }
}

{
  "message": "Unauthenticated"
}

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

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

post/shop/coupons/{couponId}/restore

Restore a deleted coupon

restoreCoupon

Un-deletes a previously soft-deleted Coupon. The coupon returns to its pre-deletion state, including code, value, validity window, and offering discounts. Past orders that redeemed the coupon remain unaffected.

Requires the restore permission on the Coupon. No request body.

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.

Responses

200
The coupon was successfully created
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/coupons/abc123/restore" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/coupons/abc123/restore', {
  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/coupons/abc123/restore",
    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/coupons/abc123/restore', [
    '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/coupons/abc123/restore", 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 coupon was successfully created

{
  "data": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "name": "Test coupon",
    "description": "This coupon is a test",
    "offering_discounts": [
      {
        "id": "64a9f3b2c3d8e1f4a5b6c7d8",
        "offerings": [
          {
            "offering_type": "appointment",
            "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8",
            "offering_name": "Test offering"
          }
        ],
        "discount_type": "fixed_amount",
        "fixed_amount": 50,
        "percentage": 10
      }
    ],
    "currency": "gbp",
    "valid_weekdays": [
      "monday"
    ],
    "invalid_date_set_ids": [
      "64a9f3b2c3d8e1f4a5b6c7d8"
    ],
    "default_validity_interval": "P1Y",
    "default_multi_use": true,
    "for_lead_booker_only": true,
    "max_uses": 2,
    "max_uses_period": "P1D",
    "redemption_type": "manual",
    "site_id": "00000000-0000-0000-0000-000000000000",
    "created_at": "2020-02-24T12:00:00+01:00",
    "updated_at": "2020-02-24T12:00:00+01:00",
    "deleted_at": "2020-02-24T12:00:00+01:00"
  }
}

{
  "message": "Unauthenticated"
}

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

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

post/shop/coupons/{couponId}/offering-discounts

Add an offering discount to a coupon

createOfferingDiscount

This endpoint adds an offering discount to a coupon.

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

offeringsobject[]required
An array of offerings which this discount applies to
discount_typestringrequired
The type of discount to be applied
Possible values:fixed_amountpercentage
fixed_amountintegeroptional
The amount of discount to apply as an integer of the smallest unit of currency.
percentageintegeroptional
The percentage of discount to apply

Responses

201
The offering discount was successfully retrieved
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/offering-discounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "offerings": [
    {
      "offering_type": "appointment",
      "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8"
    }
  ],
  "discount_type": "fixed_amount",
  "fixed_amount": 50,
  "percentage": 10
}'

const response = await fetch('https://api.playground.try.be/shop/coupons/abc123/offering-discounts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    "offerings": [
      {
        "offering_type": "appointment",
        "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8"
      }
    ],
    "discount_type": "fixed_amount",
    "fixed_amount": 50,
    "percentage": 10
  }),
})

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/offering-discounts",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "offerings": [
            {
                "offering_type": "appointment",
                "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8"
            }
        ],
        "discount_type": "fixed_amount",
        "fixed_amount": 50,
        "percentage": 10
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.playground.try.be/shop/coupons/abc123/offering-discounts', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
            'offerings' => [
                [
                    'offering_type' => 'appointment',
                    'offering_id' => '64a9f3b2c3d8e1f4a5b6c7d8'
                ]
            ],
            'discount_type' => 'fixed_amount',
            'fixed_amount' => 50,
            'percentage' => 10
        ],
]);

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

package main

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

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"offerings": []interface{}{
			map[string]interface{}{
				"offering_type": "appointment",
				"offering_id": "64a9f3b2c3d8e1f4a5b6c7d8",
			},
		},
		"discount_type": "fixed_amount",
		"fixed_amount": 50,
		"percentage": 10,
	})
	req, _ := http.NewRequest("POST", "https://api.playground.try.be/shop/coupons/abc123/offering-discounts", 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 offering discount was successfully retrieved

{
  "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"
}

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

put/shop/coupons/{couponId}/offering-discounts/{offeringDiscountId}

Update an offering discount for a coupon

updateOfferingDiscount

This endpoint updates an offering discount for a coupon.

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.
offeringDiscountIdobject-idrequired
Identifier of the offering-discount rule attached to a coupon. Offering discounts link a coupon to a specific offering and define the discount amount/percentage to apply when the coupon is redeemed against that offering.

Request body

offeringsobject[]optional
An array of offerings which this discount applies to
discount_typestringoptional
The type of discount to be applied
Possible values:fixed_amountpercentage
fixed_amountintegeroptional
The amount of discount to apply as an integer of the smallest unit of currency.
percentageintegeroptional
The percentage of discount to apply

Responses

200
The offering discount was successfully retrieved
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/coupons/abc123/offering-discounts/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "offerings": [
    {
      "offering_type": "appointment",
      "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8"
    }
  ],
  "discount_type": "fixed_amount",
  "fixed_amount": 50,
  "percentage": 10
}'

const response = await fetch('https://api.playground.try.be/shop/coupons/abc123/offering-discounts/abc123', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    "offerings": [
      {
        "offering_type": "appointment",
        "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8"
      }
    ],
    "discount_type": "fixed_amount",
    "fixed_amount": 50,
    "percentage": 10
  }),
})

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/coupons/abc123/offering-discounts/abc123",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "offerings": [
            {
                "offering_type": "appointment",
                "offering_id": "64a9f3b2c3d8e1f4a5b6c7d8"
            }
        ],
        "discount_type": "fixed_amount",
        "fixed_amount": 50,
        "percentage": 10
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.playground.try.be/shop/coupons/abc123/offering-discounts/abc123', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
            'offerings' => [
                [
                    'offering_type' => 'appointment',
                    'offering_id' => '64a9f3b2c3d8e1f4a5b6c7d8'
                ]
            ],
            'discount_type' => 'fixed_amount',
            'fixed_amount' => 50,
            'percentage' => 10
        ],
]);

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

package main

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

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"offerings": []interface{}{
			map[string]interface{}{
				"offering_type": "appointment",
				"offering_id": "64a9f3b2c3d8e1f4a5b6c7d8",
			},
		},
		"discount_type": "fixed_amount",
		"fixed_amount": 50,
		"percentage": 10,
	})
	req, _ := http.NewRequest("PUT", "https://api.playground.try.be/shop/coupons/abc123/offering-discounts/abc123", 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 offering discount was successfully retrieved

{
  "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"
}

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

delete/shop/coupons/{couponId}/offering-discounts/{offeringDiscountId}

Delete an offering discount from a coupon

deleteCouponOfferingDiscount

Removes an offering-discount association from a Coupon. The coupon itself is unaffected — only the discount on the specified offering is removed. 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.
offeringDiscountIdobject-idrequired
Identifier of the offering-discount rule attached to a coupon. Offering discounts link a coupon to a specific offering and define the discount amount/percentage to apply when the coupon is redeemed against that offering.

Responses

204
Offering discount removed 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/offering-discounts/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

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

Offering discount removed successfully.

// empty response

{
  "message": "Unauthenticated"
}

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

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

Coupons

The Coupon object

Attributes

List coupons

Query parameters

Responses

Create a coupon

Request body

Responses

Get a single coupon

Path parameters

Responses

Update a coupon

Path parameters

Request body

Responses

Soft-delete a coupon

Path parameters

Responses

Duplicate a coupon

Path parameters

Responses

Restore a deleted coupon

Path parameters

Responses

Add an offering discount to a coupon

Path parameters

Request body

Responses

Update an offering discount for a coupon

Path parameters

Request body

Responses

Delete an offering discount from a coupon

Path parameters

Responses