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

# Update Promotion

> Update an existing promotion

<Note>
  This endpoint updates an existing promotion. You can modify conditions, validity periods, and display settings. Some fields cannot be updated after a promotion has been used.
</Note>

## Authentication

This endpoint requires a valid API key with `promotions:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the promotion to update
</ParamField>

## Request Body

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

<ParamField body="name" type="string">
  Internal name for the promotion
</ParamField>

<ParamField body="description" type="string">
  Customer-facing description
</ParamField>

<ParamField body="conditions" type="object">
  Update promotion conditions

  <Expandable title="Condition properties">
    <ParamField body="max_uses_total" type="integer">
      Maximum total uses
    </ParamField>

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

    <ParamField body="customer_segments" type="array">
      Eligible customer segments
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="validity" type="object">
  Update validity period

  <Expandable title="Validity properties">
    <ParamField body="end_date" type="string">
      New end date (ISO 8601)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="status" type="string">
  Update status: "active", "paused", "expired"
</ParamField>

### Response

Returns the updated promotion object.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request PUT 'https://api.stateset.com/v1/promotions/promo_0901f083-aa1c-43c5-af5c-0a9d2fc64e30' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "validity": {
          "end_date": "2024-09-30T23:59:59Z"
      },
      "conditions": {
          "max_uses_total": 1500
      },
      "status": "active"
  }'
  ```

  ```javascript Node.js theme={null}
  const promotion = await stateset.promotions.update(
    'promo_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    {
      validity: {
        end_date: "2024-09-30T23:59:59Z"
      },
      conditions: {
        max_uses_total: 1500
      },
      status: "active"
    }
  );
  ```

  ```python Python theme={null}
  promotion = stateset.promotions.update(
    'promo_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    validity={
      "end_date": "2024-09-30T23:59:59Z"
    },
    conditions={
      "max_uses_total": 1500
    },
    status="active"
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "promo_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "object": "promotion",
    "name": "Summer Sale 2024",
    "code": "SUMMER20",
    "description": "Get 20% off on all summer collection items",
    "type": "percentage",
    "value": {
      "amount": 20,
      "max_discount": 10000
    },
    "conditions": {
      "min_purchase_amount": 5000,
      "max_uses_total": 1500,
      "max_uses_per_customer": 1,
      "used_count": 245,
      "category_ids": ["cat_summer_2024"],
      "exclude_sale_items": true
    },
    "validity": {
      "start_date": "2024-06-01T00:00:00Z",
      "end_date": "2024-09-30T23:59:59Z",
      "timezone": "America/Los_Angeles",
      "is_active": true,
      "days_remaining": 102
    },
    "status": "active",
    "updated_at": "2024-06-20T15:00:00Z",
    "updated_by": "user_456"
  }
  ```
</ResponseExample>