Create promotion
POST https://app.ecwid.com/api/v3/{storeId}/promotions
Required access scopes
Your app must have the following access scopes to make this request: create_promotion
Path params
All path params are required.
storeId
number
Ecwid store ID.
Headers
The Authorization header is required.
Authorization
Bearer secret_ab***cd
Access token of the application.
Request JSON
A JSON object with the following fields:
name
string
Name of the discount visible at the checkout.
Max length: 1024 symbols.
discountBase
string
Base for calculating the discount at the checkout.
One of:
ITEM – Discount is only applied to products matching conditions from targets array.
SUBTOTAL – Discount is applied to the cart subtotal cost, ignoring product limitations from targets array.
SHIPPING – Discount is only applied to shipping costs matching conditions from targets array.
enabled
boolean
Defines if the promotion is enabled (true) or disabled (false).
DIsabled promotions can't be used at the checkout.
discountType
string
Describes if the discount is calculated as a percent or an absolute value.
One of:
PERCENT - Price modifier applies as a percent from the product price.
ABSOLUTE - Price modifier applies as a flat value.
amount
number
Discount amount.
Value is applied as an absolute sum or a percent depending on the "discountType" field.
triggers
Trigger conditions for the promotion to apply at the checkout. Promotion is automatically applied when all specified conditions are met.
targets
Target limitations: limit promotion's application by specific categories, products, combinations, and more. Promotion is automatically applied to products in the cart if they match all specified target limitations.
triggers
startDate
string
Datetime when the promotion becomes available at the checkout.
For example, 2025-03-06 00:00:00 +0000
endDate
string
Datetime when the promotion stops being available at the checkout.
For example, 2025-03-30 12:00:00 +0000
customerGroups
array of numbers
Customer group IDs for the promotion, e.g. [0, 12345, 23456].
Maximum number of IDs: 200.
subtotal
number
Minimum cart subtotal (cost of products) for the promotion to be applied.
minProductQuantityInCart
number
Minimum quantity of products in the cart for the promotion to apply at the checkout.
maxProductQuantityInCart
number
Maximum quantity of products in the cart for the promotion to apply at the checkout.
categories
array of numbers
List of category IDs for promotion trigger. All products in the cart must be from specified category IDs to trigger the promotion.
excludedCategories
array of numbers
Exclude specific category IDs from promotion triggers. If any products added to the cart belong to the specified category IDs, the promotion will not apply to the cart.
products
array of numbers
List of product IDs for promotion trigger. All products in the cart must be from this list to trigger the promotion.
excludedProducts
array of numbers
Exclude specific product IDs from promotion triggers. If any products added to the cart match the specified IDs, the promotion will not apply to the cart.
combinations
array of numbers
List of product variation IDs for promotion trigger. All product variations added to the cart must be from this list to trigger the promotion.
excludedCombinations
array of numbers
Exclude specific product variation IDs from promotion triggers. If any of the specified product variation IDs is added to the cart, the promotion will not apply to it.
recurring
boolean
Defines if the promotion has recurrence settings. Recurrent promotions automatically become active on specified days.
If true, requires recurrenceSettings > activeDays array to list at least one day of the week inside.
recurrenceSettings
Recurrence settings for the promotion. Requires "recurring": true to work.
targets
categories
array of numbers
List of category IDs. If specified, promotion only applies to products from specified category IDs.
excludedCategories
array of numbers
Exclude specific category IDs from promotion targets. Promotion will not apply to products from specified categories.
products
array of numbers
List of product IDs. If specified, promotion only applies to specified product IDs.
excludedProducts
array of numbers
Exclude specific product IDs from promotion targets. Promotion will not apply to products from the list.
combinations
List of product variations promotion works with. If specified, promotion won't work with any product variations that are not specified here.
excludedCombinations
Exclude specific product variation IDs from promotion targets. Promotion will not apply to product variations from the list.
attributes
List of product attribute values. If specified, promotion won't work with any products that don't have product attributes and values specified here.
minDiscountedProductQuantity
number
Minimum quantity of products in the cart that can be discounted by the promotion.
maxDiscountedProductQuantity
number
Maximum quantity of products in the cart that can be discounted by the promotion.
shippingMethods
array of strings
List of shipping method IDs promotion works with. If specified, promotion won't work with any shipping method that is not specified here. For example. ["6589-1709547151586"].
Requires "discountBase": "SHIPPING".
Maximum number of IDs: 100.
all
boolean
Internal value (read-only).
attributes
attributeId
number
Internal attribute ID.
attributeValues
array of strings
List of matching attribute values in products, for which the promotion should apply. Total maximum number of attribute values across all attributes is 30.
combinations
productId
number
Internal attribute ID.
combinationIds
array of strings
List of matching product variations IDs (in string format). Total maximum number of product variation IDs across all products is 100.
recurrenceSettings
activeDays
array of strings
List of days when the promotion becomes active automatically. If specified and the "recurring" is true , then the promotion is only available on listed days of the week.
Format of days: "MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN".
For example, the "weekend sale" promotion will have "activeDays": ["SAT", "SUN"].
activeDayStartTime
string
Time when the promotion activates on the listed days. If not specified, the promotion starts at 00:00.
Format: 24h, hh:mm:ss.
For example, "activeDayStartTime": "09:30:00".
activeDayEndTime
string
Time when the promotion deactivates on the listed days. If not specified, the promotion ends at 24:00.
Format: 24h, hh:mm:ss.
For example, "activeDaEndTime": "22:00:00".
Response JSON
A JSON object with the following fields:
id
number
Internal ID of the created promotion.
Last updated
Was this helpful?