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

# Update Promotion

> Update an existing promotion

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

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

## Request body

All fields are optional. Only provided fields will be updated.

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

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

<ParamField body="type" type="string">
  Type of discount
</ParamField>

<ParamField body="scope" type="string">
  What the promotion applies to
</ParamField>

<ParamField body="value" type="string">
  Discount value
</ParamField>

<ParamField body="currency" type="string">
  3-letter ISO currency code
</ParamField>

<ParamField body="status" type="string">
  Promotion status: `draft`, `scheduled`, `active`, `paused`, `expired`, `archived`
</ParamField>

<ParamField body="valid_from" type="string">
  ISO 8601 datetime (or null to remove)
</ParamField>

<ParamField body="valid_to" type="string">
  ISO 8601 datetime (or null to remove)
</ParamField>

<ParamField body="min_order_value_minor" type="integer">
  Minimum order value in minor units (or null to remove)
</ParamField>

<ParamField body="max_discount_value_minor" type="integer">
  Maximum discount in minor units (or null to remove)
</ParamField>

<ParamField body="max_total_uses" type="integer">
  Maximum redemptions (or null for unlimited)
</ParamField>

<ParamField body="applicable_product_ids" type="array">
  Product IDs (or null to remove restriction)
</ParamField>

<ParamField body="applicable_category_ids" type="array">
  Category IDs (or null to remove restriction)
</ParamField>

<ParamField body="applicable_collection_ids" type="array">
  Collection IDs (or null to remove restriction)
</ParamField>

<ParamField body="excluded_product_ids" type="array">
  Excluded product IDs (or null to remove)
</ParamField>

<ParamField body="excluded_category_ids" type="array">
  Excluded category IDs (or null to remove)
</ParamField>

<ParamField body="stackable" type="boolean">
  Whether promotion can be combined
</ParamField>

<ParamField body="priority" type="integer">
  Priority order
</ParamField>

<ParamField body="rules" type="object">
  Custom rules (or null to remove)
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata (or null to remove)
</ParamField>

## Response

Returns the updated promotion object.

```bash Request theme={null}
curl -X PATCH "https://api.voyantcloud.com/v1/promotions/promo_abc123" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused",
    "max_total_uses": 500
  }'
```

```json Response theme={null}
{
  "data": {
    "id": "promo_abc123",
    "name": "Summer Sale 2024",
    "status": "paused",
    "maxTotalUses": 500,
    "updatedAt": "2024-07-25T09:00:00Z"
  }
}
```

## Errors

| Status | Error               | Description                           |
| ------ | ------------------- | ------------------------------------- |
| 400    | No fields to update | Request body is empty                 |
| 404    | Promotion not found | No promotion exists with the given ID |