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

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

​
Authentication

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

​
Request Body

​
name
string
required
Internal name for the promotion
​
code
string
Promotion code for customers to enter (leave empty for automatic promotions)
​
description
string
Customer-facing description of the promotion
​
type
string
required
Promotion type: “percentage”, “fixed_amount”, “bogo”, “tiered”, “bundle”, “free_shipping”
​
value
object
required
Discount value configuration
​
conditions
object
Conditions for promotion eligibility
​
validity
object
required
Promotion validity period
​
stacking
object
Rules for combining with other promotions
​
display
object
Display configuration
​
status
string
Promotion status: “active”, “scheduled”, “paused”, “expired”
​
metadata
object
Additional custom fields

​
Response

Returns the created promotion object. 
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"
}'

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