> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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