Validate Promotion

Validate a promotion code and check eligibility for a specific cart

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

Show Cart properties

items · array · required

Cart items

Show Item properties

product_id · string · required

Product ID

variant_id · string

Product variant ID

quantity · integer · required

Item quantity

price · integer · required

Unit price in cents

category_id · string

Product category ID

is_on_sale · boolean

Whether item is already on sale

subtotal · integer · required

Cart subtotal in cents

shipping_method · string

Selected shipping method

payment_method · string

Selected payment method

applied_promotions · array

Already applied promotion IDs for stacking validation

Response

Returns validation result with applicable discount details.

cURL

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

Response

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