curl --location --request POST 'https://api.stateset.com/api/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"
}'
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"
});
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"
)
{
"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
}
}
Create Promotion
Create a new promotion with flexible discount rules and targeting
POST
/
api
/
v1
/
promotions
curl --location --request POST 'https://api.stateset.com/api/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"
}'
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"
});
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"
)
{
"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 withpromotions:write permissions.
Authorization: Bearer YOUR_API_KEY
Request Body
string
required
Internal name for the promotion
string
Promotion code for customers to enter (leave empty for automatic promotions)
string
Customer-facing description of the promotion
string
required
Promotion type: “percentage”, “fixed_amount”, “bogo”, “tiered”, “bundle”, “free_shipping”
object
required
Discount value configuration
Show Value properties
Show Value properties
number
Discount amount (percentage for percentage type, cents for fixed_amount)
array
integer
Buy quantity for BOGO
integer
Get quantity for BOGO
integer
Maximum discount amount in cents (for percentage discounts)
object
Conditions for promotion eligibility
Show Condition properties
Show Condition properties
integer
Minimum order amount in cents
integer
Maximum total uses across all customers
integer
Maximum uses per customer
array
Eligible customer segment IDs
array
Applicable product IDs
array
Applicable category IDs
array
Excluded product IDs
boolean
Whether to exclude items already on sale
array
Required shipping methods
array
Required payment methods
object
required
Promotion validity period
Show Validity properties
Show Validity properties
string
required
Start date and time (ISO 8601)
string
End date and time (ISO 8601)
string
Timezone for date calculations (default: UTC)
object
object
string
Promotion status: “active”, “scheduled”, “paused”, “expired”
object
Additional custom fields
Response
Returns the created promotion object.curl --location --request POST 'https://api.stateset.com/api/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"
}'
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"
});
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"
)
{
"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
}
}
⌘I