Skip to main content
This is the main endpoint for booking engines to validate promotion codes during checkout.
​
Authorization
string
required
Bearer token with marketing:read scope

​
Request body

​
code
string
required
The promotion code to validate
​
customer_id
string
Customer ID to check per-customer usage limits
​
product_ids
array
Array of product IDs in the order (for product-specific promotions)
​
category_ids
array
Array of category IDs in the order (for category-specific promotions)
​
order_total_minor
integer
Order total in minor units (cents) to calculate discount
​
currency
string
3-letter ISO currency code

​
Response

​
valid
boolean
Whether the code is valid
​
error
string
Error code if invalid (see table below)
​
message
string
Human-readable error message if invalid
​
promotion
object
Promotion details if valid
​
code
object
Code details if valid
​
discount_amount_minor
integer
Calculated discount in minor units (if order_total_minor provided)
​
currency
string
Currency of the discount

​
Error codes

ErrorDescription
invalid_codeCode not found
inactive_codeCode is not active
not_yet_validCode validity period hasn’t started
expired_codeCode has expired
max_uses_reachedCode has reached maximum uses
promotion_not_foundParent promotion not found
promotion_inactivePromotion is not active
promotion_not_yet_validPromotion validity period hasn’t started
promotion_expiredPromotion has expired
promotion_max_uses_reachedPromotion has reached maximum uses
below_minimum_orderOrder doesn’t meet minimum value
currency_mismatchOrder currency doesn’t match promotion
product_excludedProducts in order are excluded
category_excludedCategories in order are excluded
product_not_applicableProducts not eligible for this promotion
category_not_applicableCategories not eligible for this promotion
customer_max_uses_reachedCustomer has used this code maximum times
Request
curl -X POST "https://api.voyantcloud.com/v1/promotions/validate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER20",
    "customer_id": "cust_123",
    "order_total_minor": 150000,
    "currency": "EUR"
  }'
Response (Valid)
{
  "valid": true,
  "promotion": {
    "id": "promo_abc123",
    "name": "Summer Sale 2024",
    "type": "percentage",
    "value": "20",
    "scope": "all_products",
    "stackable": false,
    "max_discount_minor": 50000
  },
  "code": {
    "id": "code_xyz",
    "code": "SUMMER20",
    "uses_remaining": 850
  },
  "discount_amount_minor": 30000,
  "currency": "EUR"
}
Response (Invalid)
{
  "valid": false,
  "error": "below_minimum_order",
  "message": "Minimum order value is 100.00 EUR",
  "minimum_order_minor": 10000
}