Update promotion

PUT https://app.ecwid.com/api/v3/{storeId}/promotions/{promotionId}

Request and response example

Request:

PUT /api/v3/1003/promotions/608502 HTTP/1.1
Authorization: Bearer secret_token
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

{
  "name": "5% off on cart total above €100,00",
  "amount": 5,
  "triggers": {
    "subtotal": 100
  }
}

Response:

{
  "updateCount": 1
}

Required access scopes

Your app must have the following access scopes to make this request: update_promotion

Path params

All path params are required.

Param	Type	Description
storeId	number	Ecwid store ID.
promotionId	number	Internal promotion ID.

Headers

The Authorization header is required.

Header	Format	Description
Authorization	Bearer secret_ab***cd	Access token of the application.

Request JSON

A JSON object with the following fields:

Field	Type	Description
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	object triggers	Trigger conditions for the promotion to apply at the checkout. Promotion is automatically applied when all specified conditions are met.
targets	object 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.
externalReferenceId	string	External ID for syncing promotions with different services. This ID is unique for each pomotion in one store.

triggers

Field	Type	Description
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	Enable recurrence settings for the promotion. 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	object recurrenceSettings	Set recurrence settings for the promotion. Requires "recurring": true to work.

targets

Field	Type	Description
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	array of objects combinations	List of product variations promotion works with. If specified, promotion won't work with any product variations that are not specified here.
excludedCombinations	array of objects combinations	Exclude specific product variation IDs from promotion targets. Promotion will not apply to product variations from the list.
attributes	array of objects 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

Field	Type	Description
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

Field	Type	Description
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

Field	Type	Description
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:

Field	Type	Description
updateCount	number	The number of updated items that defines if the request was successful. One of: 1 if the item was updated, 0 if the item was not updated.