> ## 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.

# Validate Voucher

> Validate a voucher for a specific transaction amount

This endpoint validates a voucher and calculates how much it can cover of a given order amount.

<ParamField header="Authorization" type="string" required>
  Bearer token with `marketing:read` scope
</ParamField>

## Request body

<ParamField body="code" type="string" required>
  The voucher code to validate
</ParamField>

<ParamField body="amount_minor" type="integer" required>
  The order amount in minor units (cents)
</ParamField>

<ParamField body="currency" type="string">
  3-letter ISO currency code (for currency matching)
</ParamField>

<ParamField body="customer_id" type="string">
  Customer ID (for non-transferable voucher ownership check)
</ParamField>

## Response

<ResponseField name="valid" type="boolean">
  Whether the voucher is valid for this transaction
</ResponseField>

<ResponseField name="error" type="string">
  Error code if invalid
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable error message if invalid
</ResponseField>

<ResponseField name="voucher" type="object">
  Voucher details if valid
</ResponseField>

<ResponseField name="calculation" type="object">
  Calculation breakdown showing coverage
</ResponseField>

## Error codes

| Error                      | Description                          |
| -------------------------- | ------------------------------------ |
| `voucher_not_found`        | No voucher with this code exists     |
| `voucher_inactive`         | Voucher is not active                |
| `voucher_expired`          | Voucher has expired                  |
| `voucher_depleted`         | Voucher has no remaining balance     |
| `voucher_not_transferable` | Voucher belongs to another customer  |
| `currency_mismatch`        | Voucher currency doesn't match order |

```bash Request theme={null}
curl -X POST "https://api.voyantcloud.com/v1/vouchers/validate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "GC1A2B3C4D",
    "amount_minor": 10000,
    "currency": "EUR",
    "customer_id": "cust_456"
  }'
```

```json Response (Valid - Partial Coverage) theme={null}
{
  "valid": true,
  "voucher": {
    "id": "voucher_abc123",
    "code": "GC1A2B3C4D",
    "type": "gift_card",
    "current_balance_minor": 7500,
    "currency": "EUR"
  },
  "calculation": {
    "requested_amount_minor": 10000,
    "applicable_amount_minor": 7500,
    "remaining_voucher_balance_minor": 0,
    "remaining_order_amount_minor": 2500,
    "covers_full_amount": false
  }
}
```

```json Response (Valid - Full Coverage) theme={null}
{
  "valid": true,
  "voucher": {
    "id": "voucher_abc123",
    "code": "GC1A2B3C4D",
    "type": "gift_card",
    "current_balance_minor": 15000,
    "currency": "EUR"
  },
  "calculation": {
    "requested_amount_minor": 10000,
    "applicable_amount_minor": 10000,
    "remaining_voucher_balance_minor": 5000,
    "remaining_order_amount_minor": 0,
    "covers_full_amount": true
  }
}
```

```json Response (Invalid) theme={null}
{
  "valid": false,
  "error": "currency_mismatch",
  "message": "Voucher is in EUR, but transaction is in USD"
}
```