Skip to main content
This endpoint validates a voucher and calculates how much it can cover of a given order amount.
​
Authorization
string
required
Bearer token with marketing:read scope

​
Request body

​
code
string
required
The voucher code to validate
​
amount_minor
integer
required
The order amount in minor units (cents)
​
currency
string
3-letter ISO currency code (for currency matching)
​
customer_id
string
Customer ID (for non-transferable voucher ownership check)

​
Response

​
valid
boolean
Whether the voucher is valid for this transaction
​
error
string
Error code if invalid
​
message
string
Human-readable error message if invalid
​
voucher
object
Voucher details if valid
​
calculation
object
Calculation breakdown showing coverage

​
Error codes

ErrorDescription
voucher_not_foundNo voucher with this code exists
voucher_inactiveVoucher is not active
voucher_expiredVoucher has expired
voucher_depletedVoucher has no remaining balance
voucher_not_transferableVoucher belongs to another customer
currency_mismatchVoucher currency doesn’t match order
Request
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"
  }'
Response (Valid - Partial Coverage)
{
  "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
  }
}
Response (Valid - Full Coverage)
{
  "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
  }
}
Response (Invalid)
{
  "valid": false,
  "error": "currency_mismatch",
  "message": "Voucher is in EUR, but transaction is in USD"
}