Vouchers Overview

Create and manage gift cards, store credit, and reward vouchers

The Vouchers API allows you to create and manage stored-value vouchers including gift cards, store credit, loyalty rewards, and compensation credits.

Key concepts

Vouchers

A voucher is a stored-value instrument with a balance that can be redeemed during checkout:

• Type: The purpose of the voucher (gift card, store credit, loyalty reward, compensation, referral)
• Balance: Current remaining value in minor units (cents)
• Currency: The currency of the voucher balance
• Transferability: Whether the voucher can be used by different customers

Voucher transactions

Every balance change is recorded as a transaction:

• Redemption: Deducts balance when used during checkout
• Refund: Adds balance back (e.g., when a booking is cancelled)
• Adjustment: Manual balance adjustments

Scopes required

Endpoint	Scope
List, get, lookup, validate	marketing:read
Create, update, redeem, refund	marketing:write

Voucher types

Type	Description
gift_card	Prepaid gift card purchased by a customer
store_credit	Credit issued for returns or cancelled bookings
loyalty_reward	Reward earned through loyalty program
compensation	Credit issued for service issues or complaints
referral	Credit earned through referral program

Voucher statuses

Status	Description
pending	Voucher created but not yet activated
active	Voucher is ready to use
depleted	Balance has been fully used
expired	Voucher has passed its expiry date
cancelled	Voucher has been cancelled
suspended	Voucher has been temporarily suspended

Validation flow

When validating a voucher:

1. Lookup: Find the voucher by code
2. Status check: Verify voucher is active
3. Expiry check: Ensure voucher hasn’t expired
4. Balance check: Confirm remaining balance
5. Currency match: Verify currency matches the order
6. Ownership check: For non-transferable vouchers, verify customer ownership
7. Calculate coverage: Return how much of the order the voucher can cover

Partial redemptions

Vouchers support partial redemptions:

• If the order total is less than the voucher balance, only the order amount is deducted
• If the order total exceeds the voucher balance, the full voucher balance is applied
• The remaining balance (if any) can be used on future orders