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:- Lookup: Find the voucher by code
- Status check: Verify voucher is active
- Expiry check: Ensure voucher hasn’t expired
- Balance check: Confirm remaining balance
- Currency match: Verify currency matches the order
- Ownership check: For non-transferable vouchers, verify customer ownership
- 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