Create Promotion

Create a new promotion with flexible discount rules and targeting

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

Show Value properties

amount · number

Discount amount (percentage for percentage type, cents for fixed_amount)

tiers · array

Tier configuration for tiered discounts

Show Tier properties

min_amount · integer

Minimum order amount in cents

discount · number

Discount for this tier

buy_quantity · integer

Buy quantity for BOGO

get_quantity · integer

Get quantity for BOGO

max_discount · integer

Maximum discount amount in cents (for percentage discounts)

conditions · object

Conditions for promotion eligibility

Show Condition properties

min_purchase_amount · integer

Minimum order amount in cents

max_uses_total · integer

Maximum total uses across all customers

max_uses_per_customer · integer

Maximum uses per customer

customer_segments · array

Eligible customer segment IDs

product_ids · array

Applicable product IDs

category_ids · array

Applicable category IDs

exclude_product_ids · array

Excluded product IDs

exclude_sale_items · boolean

Whether to exclude items already on sale

shipping_methods · array

Required shipping methods

payment_methods · array

Required payment methods

validity · object · required

Promotion validity period

Show Validity properties

start_date · string · required

Start date and time (ISO 8601)

end_date · string

End date and time (ISO 8601)

timezone · string

Timezone for date calculations (default: UTC)

schedule · object

Recurring schedule

Show Schedule properties

days_of_week · array

Days promotion is active (0-6, Sunday is 0)

hours · object

Active hours

Show Hour properties

start · string

Start time (HH:MM)

end · string

End time (HH:MM)

stacking · object

Rules for combining with other promotions

Show Stacking properties

allowed · boolean

Whether this promotion can be combined with others

priority · integer

Application priority (lower numbers apply first)

exclusive_with · array

Promotion IDs that cannot be combined with this one

display · object

Display configuration

Show Display properties

show_in_catalog · boolean

Show promotion badge on products

show_in_cart · boolean

Show in cart/checkout

badge_text · string

Custom badge text

banner_text · string

Promotional banner text

status · string

Promotion status: “active”, “scheduled”, “paused”, “expired”

metadata · object

Additional custom fields

Response

Returns the created promotion object.

cURL

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

Response

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