POST
/
v1
/
promotions
/
validate
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"
    }
}'

{
  "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
  }
}
This endpoint validates whether a promotion code can be applied to a given cart, checking all conditions and returning applicable discounts.

​
Authentication

This endpoint requires a valid API key with promotions:read permissions. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
code
string
required
Promotion code to validate
​
customer_id
string
Customer ID for personalized validation
​
cart
object
required
Cart details for validation
​
applied_promotions
array
Already applied promotion IDs for stacking validation

​
Response

Returns validation result with applicable discount details. 
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"
    }
}'

{
  "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
  }
}