Skip to main content
​
Authorization
string
required
Bearer token with marketing:write scope

​
Request body

​
name
string
required
Name of the promotion
​
description
string
Description of the promotion
​
type
string
required
Type of discount: percentage, fixed_amount, bogo, bundle, tiered, free_shipping, gift_with_purchase
​
scope
string
default:"all_products"
What the promotion applies to: all_products, specific_products, specific_categories, specific_collections, specific_departures
​
value
string
Discount value (percentage or amount depending on type)
​
currency
string
3-letter ISO currency code for fixed amount discounts
​
status
string
default:"draft"
Initial status: draft, scheduled, active, paused
​
valid_from
string
ISO 8601 datetime when promotion becomes valid
​
valid_to
string
ISO 8601 datetime when promotion expires
​
min_order_value_minor
integer
Minimum order value in minor units (cents) to qualify
​
max_discount_value_minor
integer
Maximum discount amount in minor units (caps percentage discounts)
​
max_total_uses
integer
Maximum number of times promotion can be redeemed
​
applicable_product_ids
array
Product IDs this promotion applies to (when scope is specific_products)
​
applicable_category_ids
array
Category IDs this promotion applies to (when scope is specific_categories)
​
applicable_collection_ids
array
Collection IDs this promotion applies to (when scope is specific_collections)
​
excluded_product_ids
array
Product IDs excluded from this promotion
​
excluded_category_ids
array
Category IDs excluded from this promotion
​
stackable
boolean
default:"false"
Whether this promotion can be combined with others
​
priority
integer
default:"0"
Priority order when multiple promotions apply (higher = first)
​
rules
object
Custom rules configuration
​
metadata
object
Custom metadata

​
Response

Returns the created promotion object.
Request
curl -X POST "https://api.voyantcloud.com/v1/promotions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Sale 2024",
    "description": "20% off all summer departures",
    "type": "percentage",
    "scope": "all_products",
    "value": "20",
    "status": "active",
    "currency": "EUR",
    "valid_from": "2024-06-01T00:00:00Z",
    "valid_to": "2024-08-31T23:59:59Z",
    "max_total_uses": 1000,
    "max_discount_value_minor": 50000
  }'
Response
{
  "data": {
    "id": "promo_abc123",
    "workspaceId": "ws_xyz",
    "name": "Summer Sale 2024",
    "description": "20% off all summer departures",
    "type": "percentage",
    "scope": "all_products",
    "value": "20",
    "status": "active",
    "currency": "EUR",
    "validFrom": "2024-06-01T00:00:00Z",
    "validTo": "2024-08-31T23:59:59Z",
    "maxTotalUses": 1000,
    "maxDiscountValueMinor": 50000,
    "currentTotalUses": 0,
    "stackable": false,
    "priority": 0,
    "createdAt": "2024-05-15T10:30:00Z",
    "updatedAt": "2024-05-15T10:30:00Z"
  }
}