Validate Promotion Code

Validate a promotion code and calculate the discount

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

Error	Description
invalid_code	Code not found
inactive_code	Code is not active
not_yet_valid	Code validity period hasn’t started
expired_code	Code has expired
max_uses_reached	Code has reached maximum uses
promotion_not_found	Parent promotion not found
promotion_inactive	Promotion is not active
promotion_not_yet_valid	Promotion validity period hasn’t started
promotion_expired	Promotion has expired
promotion_max_uses_reached	Promotion has reached maximum uses
below_minimum_order	Order doesn’t meet minimum value
currency_mismatch	Order currency doesn’t match promotion
product_excluded	Products in order are excluded
category_excluded	Categories in order are excluded
product_not_applicable	Products not eligible for this promotion
category_not_applicable	Categories not eligible for this promotion
customer_max_uses_reached	Customer 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
}