> ## 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

> Create a new promotional campaign

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

## Request body

<ParamField body="name" type="string" required>
  Name of the promotion
</ParamField>

<ParamField body="description" type="string">
  Description of the promotion
</ParamField>

<ParamField body="type" type="string" required>
  Type of discount: `percentage`, `fixed_amount`, `bogo`, `bundle`, `tiered`, `free_shipping`, `gift_with_purchase`
</ParamField>

<ParamField body="scope" type="string" default="all_products">
  What the promotion applies to: `all_products`, `specific_products`, `specific_categories`, `specific_collections`, `specific_departures`
</ParamField>

<ParamField body="value" type="string">
  Discount value (percentage or amount depending on type)
</ParamField>

<ParamField body="currency" type="string">
  3-letter ISO currency code for fixed amount discounts
</ParamField>

<ParamField body="status" type="string" default="draft">
  Initial status: `draft`, `scheduled`, `active`, `paused`
</ParamField>

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

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

<ParamField body="min_order_value_minor" type="integer">
  Minimum order value in minor units (cents) to qualify
</ParamField>

<ParamField body="max_discount_value_minor" type="integer">
  Maximum discount amount in minor units (caps percentage discounts)
</ParamField>

<ParamField body="max_total_uses" type="integer">
  Maximum number of times promotion can be redeemed
</ParamField>

<ParamField body="applicable_product_ids" type="array">
  Product IDs this promotion applies to (when scope is `specific_products`)
</ParamField>

<ParamField body="applicable_category_ids" type="array">
  Category IDs this promotion applies to (when scope is `specific_categories`)
</ParamField>

<ParamField body="applicable_collection_ids" type="array">
  Collection IDs this promotion applies to (when scope is `specific_collections`)
</ParamField>

<ParamField body="excluded_product_ids" type="array">
  Product IDs excluded from this promotion
</ParamField>

<ParamField body="excluded_category_ids" type="array">
  Category IDs excluded from this promotion
</ParamField>

<ParamField body="stackable" type="boolean" default="false">
  Whether this promotion can be combined with others
</ParamField>

<ParamField body="priority" type="integer" default="0">
  Priority order when multiple promotions apply (higher = first)
</ParamField>

<ParamField body="rules" type="object">
  Custom rules configuration
</ParamField>

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

## Response

Returns the created promotion object.

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

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