Create Promotion

Create a new promotional campaign

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"
  }
}