Create Promotion Codes

Create one or more codes for a promotion

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

Status	Error	Description
404	Promotion not found	No promotion exists with the given ID
409	Code already exists	A code with this string already exists