Search promotions

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

Request and response example

Request:

curl --location 'https://app.ecwid.com/api/v3/1003/promotions' \
--header 'Authorization: Bearer secret_ab***cd'

Response:

{
    "total": 1,
    "count": 1,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            "id": 608502,
            "name": "10% off on cart total above €50,00",
            "enabled": true,
            "discountBase": "SUBTOTAL",
            "discountType": "PERCENT",
            "amount": 10,
            "triggers": {
                "subtotal": 50
            }
        }
    ]
}

Required access scopes

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

Path params

All path params are required.

Param	Type	Description
storeId	number	Ecwid store ID.

Query params

All query params are optional.

Name	Type	Description
responseFields	string	Specify the exact fields to receive in response JSON. If not specified, the response JSON will have all available fields for the entity. Example: ?responseFields=items(name,enabled)

Example of using responseFields param:

Request

curl --location 'https://app.ecwid.com/api/v3/1003/promotions?responseFields=items(name,enabled)' \
--header 'Authorization: Bearer secret_ab***cd'

Response

{
    "items": [
        {
            "name": "10% off on cart total above €50,00",
            "enabled": true
        }
    ]
}

Headers

The Authorization header is required.

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

Response JSON

A JSON object with the following fields:

Field	Type	Description
total	number	Total number of found items (might be more than the number of returned items).
count	number	Total number of items returned in the response.
offset	number	Offset from the beginning of the returned items list specified in the request.
limit	number	Maximum number of returned items specified in the request. Maximum and default value: 100.
items	array of objects items	Detailed information about returned promotions.

items

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.

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.

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.