Promotions Tools
Manage promo codes and gift vouchers. List, view details, validate, and create new promotions.
Required scope: promotions:read for read tools, promotions:write for write tools
Tools Overview
| Tool | Description | Read-only? |
|---|---|---|
list_promo_codes | List promo codes | Yes |
get_promo_code | Get promo code details and usage stats | Yes |
validate_promo_code | Check if a promo code is valid | Yes |
create_promo_code | Create a new promo code | No |
list_vouchers | List gift cards, and gift card sales for a period | Yes |
get_voucher | Get voucher details and usage stats | Yes |
validate_voucher | Check if a voucher is valid and has balance | Yes |
create_voucher | Create a new gift voucher | No |
list_promo_codes
List promo codes with optional search.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Search by code or name |
limit | integer | No | Number of results (default 10) |
get_promo_code
Get promo code details and usage statistics.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
promo_code_id | integer | No | The promo code ID |
code | string | No | The promo code string (alternative to ID) |
Provide either promo_code_id or code.
validate_promo_code
Check if a promo code is valid (without applying it to a booking).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The promo code to validate |
create_promo_code
Create a new promo code.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The promo code (will be uppercased) |
type | string | Yes | Discount type: percentage or fixed |
value | number | Yes | Discount value (percentage or fixed amount) |
max_uses | integer | No | Maximum number of uses (null for unlimited) |
valid_from | string | No | Start date for validity |
valid_until | string | No | End date for validity |
user_confirmed | boolean | Yes | Must be true to create |
list_vouchers
List gift cards with the day each was issued (shop time), how it was issued and what was paid for it. Pass from and to to get period_sales: the cards sold in that period and the money taken, split by how they were sold. Refund credits, imported cards and staff cards with no payment recorded are not counted as sales.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Search by code, purchaser name, or recipient name |
status | string | No | Filter by status: active, fully_redeemed, cancelled, expired_display |
from | string | No | Only cards issued on or after this day, YYYY-MM-DD in the shop's time zone |
to | string | No | Only cards issued on or before this day, YYYY-MM-DD in the shop's time zone |
limit | integer | No | Number of results (default 10) |
get_voucher
Get voucher details and usage statistics.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
voucher_id | integer | No | The voucher ID |
code | string | No | The voucher code (alternative to ID) |
Provide either voucher_id or code.
validate_voucher
Check if a voucher code is valid and has remaining balance. Does not apply the voucher. Use apply_voucher (in Payments tools) to redeem against a booking.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The voucher code to validate |
create_voucher
Create a new gift voucher.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
original_value | number | Yes | Voucher value amount |
purchaser_name | string | No | Name of the purchaser |
purchaser_email | string | No | Email of the purchaser |
recipient_name | string | No | Name of the voucher recipient |
recipient_email | string | No | Email of the recipient |
valid_until | string | No | Expiry date |
personal_message | string | No | Personal message for the gift card |
user_confirmed | boolean | Yes | Must be true to create |
Related
- Promotions REST API - REST API endpoints for promotions
- Payments Tools - Apply promo codes and vouchers to bookings