Search advanced discounts

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
            }
        }
    ]
}

Access scopes

Requires the following access scope: read_promotion

Path params

Param	Type	Description
storeId	number	Ecwid store ID.

Query params

All query params are optional.

Param	Type	Description
responseFields	string	Limit JSON response by specific fields. If specified, all missing fields will be removed from the response body. Example: `?responseFields=items(name,enabled)`

Example of using responseFields param:

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

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

Headers

The Authorization header with a secret access token is required.

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

Response

A JSON array with the following fields:

Field	Type	Description
name	string	Name of the discount displayed at the checkout. Max length: 1024 symbols.
discountBase	string	Base from which discount is calculated on the checkout. Supported values: `"ITEM"` – discount is applied only for products/categories specified in the `targets` array. `"SUBTOTAL"` – discount will be applied to all products added to the cart. `"SHIPPING"` – discount will be applied to all products added to the cart.
enabled	boolean	`true` if discount is enabled, `false` otherwise
discountType	string	Describes if the discount is calculated as a percent or an absolute value. Supports only two values: `"PERCENT"` or `"ABSOLUTE"`.
amount	number	Discount amount. Value is applied as an absolute sum or a percent depending on the `"discountType"` field.
triggers	Array triggers	Triggers that define when the discount is applied. Supports restricting by date, customer group and subtotal in any combination.
targets	Array targets	Limit the discount by categories, specific products, combinations and even attributes customer group and subtotal in any combination.

triggers

Set up triggers when the discount from promotion should be applied on the checkout:

Field	Type	Description
startDate	string	Date and time to start the promotion
endDate	string	Date and time to end the promotion
customerGroups	Array of numbers	Customer group IDs for the promotion, e.g. `[0, 12345, 23456]`. Maximum number of IDs: 200.
subtotal	number	Minimum cost of products added to the cart for the promotion to be applied

targets

Restrict promotion by specific products, categories, product variations (combinations), and attributes:

Field	Type	Description
categories	Array of numbers	Restrict promotion by a list of category IDs of products added to the cart. Maximum number of IDs: 200.
products	Array of numbers	Restrict promotion by a list of product IDs added to the cart. Maximum number of IDs: 200.
attributes	Array attributes	Restrict promotion by a list of attribute values of products added to the cart.
combinations	Array combinations	Restrict promotion by a list of product combinations added to the cart.
shippingMethods	Array of strings	Restrict promotion by a list of shipping method IDs one of which must selected on the checkout, e.g. `[6589-1709547151586"]`. Requires `"discountBase": "SHIPPING"`. Maximum number of IDs: 100.
all	boolean	Internal value (read-only).

attributes

Restrict the promotion of products with specific attribute values:

Field	Type	Description
attributeId	number	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: 30.

combinations

Restrict promotion by specific product combinations:

Field	Type	Description
productId	string	Product ID.
combinationIds	Array of strings	Product variation IDs for which the promotion should be applied. Total maximum number of product variation IDs across all products: 100.