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

# Create Promotion

> Create a new promotion with flexible discount rules and targeting

<Note>
  This endpoint creates a new promotion that can be applied to orders, products, or customer segments. Promotions support various discount types and complex rule conditions.
</Note>

## Authentication

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

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

## Request Body

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

<ParamField body="code" type="string">
  Promotion code for customers to enter (leave empty for automatic promotions)
</ParamField>

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

<ParamField body="type" type="string" required>
  Promotion type: "percentage", "fixed\_amount", "bogo", "tiered", "bundle", "free\_shipping"
</ParamField>

<ParamField body="value" type="object" required>
  Discount value configuration

  <Expandable title="Value properties">
    <ParamField body="amount" type="number">
      Discount amount (percentage for percentage type, cents for fixed\_amount)
    </ParamField>

    <ParamField body="tiers" type="array">
      Tier configuration for tiered discounts

      <Expandable title="Tier properties">
        <ParamField body="min_amount" type="integer">
          Minimum order amount in cents
        </ParamField>

        <ParamField body="discount" type="number">
          Discount for this tier
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="buy_quantity" type="integer">
      Buy quantity for BOGO
    </ParamField>

    <ParamField body="get_quantity" type="integer">
      Get quantity for BOGO
    </ParamField>

    <ParamField body="max_discount" type="integer">
      Maximum discount amount in cents (for percentage discounts)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="conditions" type="object">
  Conditions for promotion eligibility

  <Expandable title="Condition properties">
    <ParamField body="min_purchase_amount" type="integer">
      Minimum order amount in cents
    </ParamField>

    <ParamField body="max_uses_total" type="integer">
      Maximum total uses across all customers
    </ParamField>

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

    <ParamField body="customer_segments" type="array">
      Eligible customer segment IDs
    </ParamField>

    <ParamField body="product_ids" type="array">
      Applicable product IDs
    </ParamField>

    <ParamField body="category_ids" type="array">
      Applicable category IDs
    </ParamField>

    <ParamField body="exclude_product_ids" type="array">
      Excluded product IDs
    </ParamField>

    <ParamField body="exclude_sale_items" type="boolean">
      Whether to exclude items already on sale
    </ParamField>

    <ParamField body="shipping_methods" type="array">
      Required shipping methods
    </ParamField>

    <ParamField body="payment_methods" type="array">
      Required payment methods
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="validity" type="object" required>
  Promotion validity period

  <Expandable title="Validity properties">
    <ParamField body="start_date" type="string" required>
      Start date and time (ISO 8601)
    </ParamField>

    <ParamField body="end_date" type="string">
      End date and time (ISO 8601)
    </ParamField>

    <ParamField body="timezone" type="string">
      Timezone for date calculations (default: UTC)
    </ParamField>

    <ParamField body="schedule" type="object">
      Recurring schedule

      <Expandable title="Schedule properties">
        <ParamField body="days_of_week" type="array">
          Days promotion is active (0-6, Sunday is 0)
        </ParamField>

        <ParamField body="hours" type="object">
          Active hours

          <Expandable title="Hour properties">
            <ParamField body="start" type="string">
              Start time (HH:MM)
            </ParamField>

            <ParamField body="end" type="string">
              End time (HH:MM)
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="stacking" type="object">
  Rules for combining with other promotions

  <Expandable title="Stacking properties">
    <ParamField body="allowed" type="boolean">
      Whether this promotion can be combined with others
    </ParamField>

    <ParamField body="priority" type="integer">
      Application priority (lower numbers apply first)
    </ParamField>

    <ParamField body="exclusive_with" type="array">
      Promotion IDs that cannot be combined with this one
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="display" type="object">
  Display configuration

  <Expandable title="Display properties">
    <ParamField body="show_in_catalog" type="boolean">
      Show promotion badge on products
    </ParamField>

    <ParamField body="show_in_cart" type="boolean">
      Show in cart/checkout
    </ParamField>

    <ParamField body="badge_text" type="string">
      Custom badge text
    </ParamField>

    <ParamField body="banner_text" type="string">
      Promotional banner text
    </ParamField>
  </Expandable>
</ParamField>

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

<ParamField body="metadata" type="object">
  Additional custom fields
</ParamField>

### Response

Returns the created promotion object.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/promotions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "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": 1000,
          "max_uses_per_customer": 1,
          "category_ids": ["cat_summer_2024"],
          "exclude_sale_items": true
      },
      "validity": {
          "start_date": "2024-06-01T00:00:00Z",
          "end_date": "2024-08-31T23:59:59Z",
          "timezone": "America/Los_Angeles"
      },
      "stacking": {
          "allowed": false,
          "priority": 1
      },
      "display": {
          "show_in_catalog": true,
          "show_in_cart": true,
          "badge_text": "SUMMER SALE"
      },
      "status": "scheduled"
  }'
  ```

  ```javascript Node.js theme={null}
  const promotion = await stateset.promotions.create({
    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: 1000,
      max_uses_per_customer: 1,
      category_ids: ["cat_summer_2024"],
      exclude_sale_items: true
    },
    validity: {
      start_date: "2024-06-01T00:00:00Z",
      end_date: "2024-08-31T23:59:59Z",
      timezone: "America/Los_Angeles"
    },
    stacking: {
      allowed: false,
      priority: 1
    },
    display: {
      show_in_catalog: true,
      show_in_cart: true,
      badge_text: "SUMMER SALE"
    },
    status: "scheduled"
  });
  ```

  ```python Python theme={null}
  promotion = stateset.promotions.create(
    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": 1000,
      "max_uses_per_customer": 1,
      "category_ids": ["cat_summer_2024"],
      "exclude_sale_items": True
    },
    validity={
      "start_date": "2024-06-01T00:00:00Z",
      "end_date": "2024-08-31T23:59:59Z",
      "timezone": "America/Los_Angeles"
    },
    stacking={
      "allowed": False,
      "priority": 1
    },
    display={
      "show_in_catalog": True,
      "show_in_cart": True,
      "badge_text": "SUMMER SALE"
    },
    status="scheduled"
  )
  ```
</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": 1000,
      "max_uses_per_customer": 1,
      "used_count": 0,
      "category_ids": ["cat_summer_2024"],
      "exclude_sale_items": true
    },
    "validity": {
      "start_date": "2024-06-01T00:00:00Z",
      "end_date": "2024-08-31T23:59:59Z",
      "timezone": "America/Los_Angeles",
      "is_active": false,
      "days_remaining": 134
    },
    "stacking": {
      "allowed": false,
      "priority": 1
    },
    "display": {
      "show_in_catalog": true,
      "show_in_cart": true,
      "badge_text": "SUMMER SALE"
    },
    "status": "scheduled",
    "created_at": "2024-01-20T10:00:00Z",
    "updated_at": "2024-01-20T10:00:00Z",
    "created_by": "user_123",
    "performance": {
      "total_orders": 0,
      "total_revenue": 0,
      "total_discount_given": 0,
      "conversion_rate": 0
    }
  }
  ```
</ResponseExample>