> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Promotion Codes

> Create one or more codes for a promotion

<ParamField header="Authorization" type="string" required>
  Bearer token with `marketing:write` scope
</ParamField>

<ParamField path="id" type="string" required>
  The promotion ID
</ParamField>

## Single code creation

<ParamField body="code" type="string">
  The code string (auto-generated if not provided, always uppercased)
</ParamField>

<ParamField body="status" type="string" default="active">
  Initial status: `active`, `inactive`, `expired`
</ParamField>

<ParamField body="max_uses" type="integer">
  Maximum number of times this code can be used
</ParamField>

<ParamField body="max_uses_per_customer" type="integer">
  Maximum uses per customer
</ParamField>

<ParamField body="valid_from" type="string">
  ISO 8601 datetime when code becomes valid
</ParamField>

<ParamField body="valid_to" type="string">
  ISO 8601 datetime when code expires
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata
</ParamField>

## Bulk code creation

Set `bulk: true` to generate multiple codes at once.

<ParamField body="bulk" type="boolean" required>
  Set to `true` for bulk creation
</ParamField>

<ParamField body="count" type="integer" required>
  Number of codes to generate (max 1000)
</ParamField>

<ParamField body="prefix" type="string" default="PROMO">
  Prefix for generated codes (max 10 characters)
</ParamField>

<ParamField body="status" type="string" default="active">
  Initial status for all codes
</ParamField>

<ParamField body="max_uses" type="integer">
  Maximum uses per code
</ParamField>

<ParamField body="max_uses_per_customer" type="integer">
  Maximum uses per customer per code
</ParamField>

<ParamField body="valid_from" type="string">
  Validity start for all codes
</ParamField>

<ParamField body="valid_to" type="string">
  Validity end for all codes
</ParamField>

## Response

Returns the created code(s).

```bash Request (Single) theme={null}
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"
  }'
```

```json Response (Single) theme={null}
{
  "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"
  }
}
```

```bash Request (Bulk) theme={null}
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"
  }'
```

```json Response (Bulk) theme={null}
{
  "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 |