Skip to main content
POST
/
api
/
public
/
v1
/
promotions
/
create
curl --request POST \
  --url https://app.localhost:3000/api/public/v1/promotions/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "storeId": "store_123",
  "name": "Summer Sale 20% Off",
  "code": "SUMMER20",
  "automatic": false,
  "enabled": true,
  "usageLimit": 100,
  "startDate": "2025-06-01T00:00:00.000Z",
  "endDate": "2025-08-31T23:59:59.000Z",
  "ruleOperator": "AND",
  "combinesWithOrderLevelDiscounts": false,
  "combinesWithLineItemDiscounts": false,
  "combinesWithShippingDiscounts": false,
  "forceCombine": false,
  "rules": [],
  "actions": [
    {
      "type": "OrderAdjustment",
      "adjustmentType": "percentage",
      "adjustmentPercentage": 20
    }
  ]
}
'
{
  "id": "promo_123",
  "name": "Summer Sale 20% Off",
  "code": "SUMMER20",
  "enabled": true
}

Authorizations

​
Authorization
string
header
required

Enter your API key as: Bearer your-api-key

Body

application/json
​
storeId
string
required

The store ID to create the promotion for

Minimum string length: 1
​
name
string
required

Name of the promotion

Minimum string length: 1
​
code
string | null

Coupon code for the promotion (null for automatic promotions)

​
automatic
boolean
default:false

Whether the promotion applies automatically without a code

​
enabled
boolean
default:true

Whether the promotion is active

​
usageLimit
number | null

Maximum number of times the promotion can be used (null for unlimited)

​
startDate
string<date-time> | null

Start date of the promotion

​
endDate
string<date-time> | null

End date of the promotion

​
ruleOperator
enum<string>
default:OR

Logical operator applied between rules

Available options:
AND,
OR
​
combinesWithOrderLevelDiscounts
boolean
default:false

Whether this promotion can combine with order-level discounts

​
combinesWithLineItemDiscounts
boolean
default:false

Whether this promotion can combine with line-item discounts

​
combinesWithShippingDiscounts
boolean
default:false

Whether this promotion can combine with shipping discounts

​
forceCombine
boolean
default:false

Force combination with other promotions regardless of settings

​
rules
(ContainsProduct · object | OrderAmountMinimum · object | OrderMinQuantity · object)[]

Conditions that must be met for the promotion to apply

​
actions
(LineItemPercentageAdjustment · object | LineItemAmountAdjustment · object | OrderPercentageAdjustment · object | OrderAmountAdjustment · object | ShippingAdjustment · object | CreateLineItem · object | SubscriptionLineItemFreeTrial · object)[]

Effects applied when the promotion conditions are met

Response

Successful response

​
id
string
​
storeId
string
​
name
string
​
code
string | null
​
enabled
boolean
​
automatic
boolean
​
usageLimit
number | null
​
usageCount
number
​
startDate
string<date-time> | null
​
endDate
string<date-time> | null
​
ruleOperator
enum<string>
Available options:
AND,
OR
​
createdAt
string<date-time>
​
updatedAt
string<date-time>