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

# Validate Promotion

> Validate a promotion code and check eligibility for a specific cart

<Note>
  This endpoint validates whether a promotion code can be applied to a given cart, checking all conditions and returning applicable discounts.
</Note>

## Authentication

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

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

## Request Body

<ParamField body="code" type="string" required>
  Promotion code to validate
</ParamField>

<ParamField body="customer_id" type="string">
  Customer ID for personalized validation
</ParamField>

<ParamField body="cart" type="object" required>
  Cart details for validation

  <Expandable title="Cart properties">
    <ParamField body="items" type="array" required>
      Cart items

      <Expandable title="Item properties">
        <ParamField body="product_id" type="string" required>
          Product ID
        </ParamField>

        <ParamField body="variant_id" type="string">
          Product variant ID
        </ParamField>

        <ParamField body="quantity" type="integer" required>
          Item quantity
        </ParamField>

        <ParamField body="price" type="integer" required>
          Unit price in cents
        </ParamField>

        <ParamField body="category_id" type="string">
          Product category ID
        </ParamField>

        <ParamField body="is_on_sale" type="boolean">
          Whether item is already on sale
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="subtotal" type="integer" required>
      Cart subtotal in cents
    </ParamField>

    <ParamField body="shipping_method" type="string">
      Selected shipping method
    </ParamField>

    <ParamField body="payment_method" type="string">
      Selected payment method
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="applied_promotions" type="array">
  Already applied promotion IDs for stacking validation
</ParamField>

### Response

Returns validation result with applicable discount details.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/promotions/validate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "code": "SUMMER20",
      "customer_id": "cust_abc123",
      "cart": {
          "items": [
              {
                  "product_id": "prod_123",
                  "quantity": 2,
                  "price": 2999,
                  "category_id": "cat_summer_2024"
              },
              {
                  "product_id": "prod_456",
                  "quantity": 1,
                  "price": 4999,
                  "category_id": "cat_accessories"
              }
          ],
          "subtotal": 10997,
          "shipping_method": "standard"
      }
  }'
  ```

  ```javascript Node.js theme={null}
  const validation = await stateset.promotions.validate({
    code: "SUMMER20",
    customer_id: "cust_abc123",
    cart: {
      items: [
        {
          product_id: "prod_123",
          quantity: 2,
          price: 2999,
          category_id: "cat_summer_2024"
        },
        {
          product_id: "prod_456",
          quantity: 1,
          price: 4999,
          category_id: "cat_accessories"
        }
      ],
      subtotal: 10997,
      shipping_method: "standard"
    }
  });
  ```

  ```python Python theme={null}
  validation = stateset.promotions.validate(
    code="SUMMER20",
    customer_id="cust_abc123",
    cart={
      "items": [
        {
          "product_id": "prod_123",
          "quantity": 2,
          "price": 2999,
          "category_id": "cat_summer_2024"
        },
        {
          "product_id": "prod_456",
          "quantity": 1,
          "price": 4999,
          "category_id": "cat_accessories"
        }
      ],
      "subtotal": 10997,
      "shipping_method": "standard"
    }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "valid": true,
    "promotion": {
      "id": "promo_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
      "code": "SUMMER20",
      "name": "Summer Sale 2024",
      "type": "percentage",
      "description": "Get 20% off on all summer collection items"
    },
    "eligibility": {
      "is_eligible": true,
      "customer_eligible": true,
      "cart_eligible": true,
      "within_usage_limits": true,
      "within_date_range": true,
      "meets_minimum_purchase": true
    },
    "discount_calculation": {
      "applicable_items": [
        {
          "product_id": "prod_123",
          "quantity": 2,
          "original_amount": 5998,
          "discount_amount": 1200,
          "final_amount": 4798
        }
      ],
      "excluded_items": [
        {
          "product_id": "prod_456",
          "reason": "category_not_eligible"
        }
      ],
      "discount_amount": 1200,
      "final_subtotal": 9797
    },
    "warnings": [],
    "metadata": {
      "customer_usage_count": 0,
      "total_usage_count": 245,
      "days_until_expiry": 134
    }
  }
  ```
</ResponseExample>