Skip to main content
​
Authorization
string
required
Bearer token with marketing:write scope
​
id
string
required
The promotion ID

​
Single code creation

​
code
string
The code string (auto-generated if not provided, always uppercased)
​
status
string
default:"active"
Initial status: active, inactive, expired
​
max_uses
integer
Maximum number of times this code can be used
​
max_uses_per_customer
integer
Maximum uses per customer
​
valid_from
string
ISO 8601 datetime when code becomes valid
​
valid_to
string
ISO 8601 datetime when code expires
​
metadata
object
Custom metadata

​
Bulk code creation

Set bulk: true to generate multiple codes at once.
​
bulk
boolean
required
Set to true for bulk creation
​
count
integer
required
Number of codes to generate (max 1000)
​
prefix
string
default:"PROMO"
Prefix for generated codes (max 10 characters)
​
status
string
default:"active"
Initial status for all codes
​
max_uses
integer
Maximum uses per code
​
max_uses_per_customer
integer
Maximum uses per customer per code
​
valid_from
string
Validity start for all codes
​
valid_to
string
Validity end for all codes

​
Response

Returns the created code(s).
Request (Single)
curl -X POST "https://api.voyantcloud.com/v1/promotions/promo_abc123/codes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER20",
    "max_uses": 1000,
    "max_uses_per_customer": 1,
    "valid_from": "2024-06-01T00:00:00Z",
    "valid_to": "2024-08-31T23:59:59Z"
  }'
Response (Single)
{
  "data": {
    "id": "code_xyz",
    "promotionId": "promo_abc123",
    "code": "SUMMER20",
    "status": "active",
    "maxUses": 1000,
    "currentUses": 0,
    "maxUsesPerCustomer": 1,
    "validFrom": "2024-06-01T00:00:00Z",
    "validTo": "2024-08-31T23:59:59Z",
    "createdAt": "2024-05-15T10:35:00Z"
  }
}
Request (Bulk)
curl -X POST "https://api.voyantcloud.com/v1/promotions/promo_abc123/codes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bulk": true,
    "count": 100,
    "prefix": "VIP",
    "max_uses": 1,
    "valid_to": "2024-12-31T23:59:59Z"
  }'
Response (Bulk)
{
  "data": {
    "count": 100,
    "codes": [
      {
        "id": "code_001",
        "code": "VIPA1B2C3",
        "status": "active",
        "maxUses": 1
      },
      {
        "id": "code_002",
        "code": "VIPD4E5F6",
        "status": "active",
        "maxUses": 1
      }
    ]
  }
}

​
Errors

StatusErrorDescription
404Promotion not foundNo promotion exists with the given ID
409Code already existsA code with this string already exists