Promotions

Fundamentals of a promotion

1. Promotions can be assigned to specific shops and are then only valid in these shops. Promotions can also be valid in several shops at the same time.
2. Within one shop, a promotion can be configured to be valid in specific countries. Promotions can also be valid in multiple countries at the same time.
3. Audiences are finely tuned customer segments that enable precise customer outreach. You can define for which audiences a promotion is valid. This is optional, a promotion can also be valid for all audiences.
4. Each promotion has a set of basic configurations.

Promotion configuration

Promotion conditions

To each promotion, conditions can be assigned. Conditions are special rules that must be satisfied in order for the promotion to be applied. A distinction is made between two types of conditions:

Global conditions

Global conditions are checked against general customer- or basket/order data. The promotion is only considered valid if the global condition is met. If the global condition isn't met, the entire promotion is invalid, regardless of whether the item conditions are met. Typical examples for global conditions are:

• Minimum order value is greater or equal than €100
• Customer is in group “VIP”
• Basket/order contains more than 3 items of a specific brand

Item Conditions

Item conditions are checked against the item you are trying to apply the promotion to. This is useful, when you want to limit the set of items, which can benefit from a promotion, for instance

• 15% off of jeans
• 10% off of all items with attribute group “deal”
• Conditions can be connected by “and” or “or” operators as well.

By mix and matching global and item conditions, you can create specific promotions that serve your individual promotion cases.

The conditions are defined using the Google Common Expression Language.

The implementation is based on Go, you can find the language definition here. Cel-go has multiple extensions, currently we support the Math extension, which supports two additional functions: math.greatest() and math.least()

Condition examples

go

Copy

payload.items.filter(it, it.price == math.greatest(payload.items.map(i, i.price)))[0].price == item.price

go

Copy

payload.items.filter(it, it.price == math.least(payload.items.map(i, i.price)))[0].price == item.price

Admin API

The Admin API offers several endpoints for managing promotions.

• Create promotion
• Get promotions
• Update promotion
• Delete promotion

Create promotion

SCAYLE allows you to create promotions.

Method Signature

JavaScriptPHPcURLJava

Copy

let response = await client.apis.Promotions.createPromotion({}, {requestBody: promotion});
let createdPromotion = response.body;

Options

The createPromotion method can be used with an optional query parameter:

Request Body

Property	Description
name*	String Defines the name of the promotion.
status*	String Defines the status of the promotion. Valid values are: archived Promotion cannot be changed or applied. inactive Promotion is disabled and cannot be applied. active Promotion is enabled and can be changed and applied.
schedule*	Object Defines the time range when a promotion is active. See Schedule
companyIds*	Integer[] A list of company ids where the promotion takes place.
shopCountryIds*	Object Defines the shop countries in which the promotion will be available. See ShopCountryIds
effect*	Object The effect that will be applied if all conditions are satisfied. See Effects
activationType*	String Defines the activation type of the promotion. Valid values are: automatic This promotion type does not require a customer to enter a code. code This promotion type requires a customer to enter a code to apply the promotion (similar to a voucher).
level*	String Defines the level on which the promotion is applied. Valid values are: item The promotion is applied on the basket item level. basket The promotion is applied on the basket level (e.g. discount for the whole basket)
conditions*	Object[] Defines a list of conditions that must be satisfied for applying a promotion to the customers basket. See Conditions
displayName	Object Localization of the name to be displayed. Example Copy { "de_DE": "Weihnachtsaktion", "en_GB": "Christmas promotion" }
priority	Integer Defines the priority of the promotion.
siblingPromotions	See Sibling Promotions
audiences	Object See Audiences
customData	Object A list of key-value pairs that are individually defined. Example Copy { "legalText": "Supported neglected met she therefore unwilling discovery remainder. Way sentiments two indulgence uncommonly own." }
tiers	Object[] Defines a list of tiers that allow configuring different effect values depending on the minimum order value. See Tiers
usageLimit	Object Usage limit configuration See Usage Limit

Schedule

ShopCountryIds

Effects

Effect - Additional Data - Buy X Get Y

When the promotion conditions are satisfied, the customer will receive n items for free. (The list of which items will be given for free and how many can be defined during promotion creation).

Effect - Additional Data - Automatic Discount

When the promotion conditions are satisfied, the customer will receive a discount on specific items or the whole basket.

Conditions

Conditions are special rules that must be satisfied in order for the promotion to be applied. These rules must follow the Google Common Expression Language syntax.

Conditions can be applied on two different levels, global and item. Global conditions are applied only once per payload / basket, while item conditions are checked for each item in the basket. Anything other than item related conditions should be put into conditions on level global.

• When only item level conditions are satisfied, effects are applied for each item.
• When only global level conditions are satisfied, effects are applied on basket level.
• When both, global and item level conditions, are satisfied, they are applied accordingly.

Sibling Promotions

Sibling promotions allow to create a new promotion combined with other promotions defined in siblingPromotions.

Audiences

Allows promotion engine users to tailor promotions to particular group of customers. An audience is a collection of customers grouped to be used effectively in/for a promotion.

Example

Black Friday Influencers , VIP_Members , High Value Customers, Trend Lovers

Tiers

Promotion tiers allow configuring different effect values depending on the MOV (Minimum Order Value). effect.additional_data can have different values for each individual tier.

Basically, current tier effect values are merged with promotion.effect. That means, it is not necessary to include all effect.additional_data values in the tier.effect, it is enough to add only values that are changed.

Example

• when MOV reaches 100 EUR, customer gets 10% discount
• when MOV reaches 150 EUR, customer gets 15% discount

Tier Effect

Usage Limit

Usage Limit Promotion

Usage Limit Promotion Codes

Example

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Promotions.createPromotion({
    with: "customData"
}, {
    requestBody: {
        "name": "Christmas Promotion",
        "status": "active",
        "shopCountryIds": {
            "allowList": [139, 554]
        },
        "companyIds": [100],
        "schedule": {
            "from": "2023-05-10T10:00:00+01:00",
            "to": "2024-05-10T10:00:00+01:00"
        },
        "effect": {
            "type": "buy_x_get_y",
            "additionalData": {
                "variantIds": [12389244, 23985437],
                "maxCount": 2,
                "maxCountType": "per_eligible_items_quantity",
                "eligibleItemsQuantity": 1
            }
        },
        "activationType": "automatic",
        "level": "basket",
        "priority": 10,
        "displayName": {
            "de_DE": "Weihnachtsaktion",
            "en_US": "Christmas Promotion"
        },
        "customData": {
            "anything": "you want to provide"
        },
        "audiences": {
            "allowList": ["645e0c241a93369ff53f26e0"]
        },
        "siblingPromotions": {
            "enabled": true,
            "blockList": ["646235bf496f8f56171c3762"],
            "level": "basket"
        },
        "usageLimit": {
            "promotion": {
                "count": 10
            },
            "promotionCodes": {
                "count": 10,
                "type": "order"
            }
        },
        "conditions": [
            {
                "level": "global",
                "key": "mov_100",
                "condition": "payload.items.exists(i. 11003 in i.variant.id)"
            },
            {
                "level": "item",
                "key": "mov_100",
                "condition": "item.color == 'yellow'"
            }
        ]
    }
});

let createdPromotion = response.body;

console.log(createdPromotion.id);

Update promotion

Updating an existing promotion follows the same schema as for creating new promotions. Therefore, you can simply refer to the request body and schema above.

Method signature

JavaScriptPHPcURLJava

Copy

let response = await client.apis.Promotions.updatePromotion(
    {promotionId: "promotionId"},
    {requestBody: promotion}
);
let updatedPromotion = response.body;

Request Body

Please refer to the create promotion request body.

Example

JavaScriptPHPcURLJava

Copy

let promotion = {
    "name": "Christmas Promotion",
    "status": "active",
    "shopCountryIds": {
        "blockList": [ 139, 554 ]
    },
    "activationType": "code",
    "level": "basket",
    "companyIds": [ 100 ],
    "schedule": {
        "from": "2023-05-10T10:00:00+01:00",
        "to": "2024-05-10T10:00:00+01:00"
    },
    "effect": {
        "type": "buy_x_get_y",
        "additionalData": {
            "variantIds": [12389244, 23985437],
            "maxCount": 2,
            "maxCountType": "per_eligible_items_quantity",
            "eligibleItemsQuantity": 1
        }
    }
}

let response = await client.apis.Promotions.updatePromotion(
    {promotionId: "645e0c241a93369ff53f26e0", with: "customData"},
    {requestBody: promotion}
);
let updatedPromotion = response.body;

console.log(updatedPromotion.id);

List promotions

You can also request several promotions. We suggest to fine-tune your search, e.g. by combining filters and using pagination. As search results are paginated, you can set the amount of promotions displayed per page.

Method signature

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Promotions.getPromotions(options);
let promotions = response.body.entities;

Options

The getPromotions endpoint can be used with the following optional query parameters:

Parameter	Details
filters[id]	String Comma-separated list of IDs of entities that should be used for filtering. Example Copy filters[id]=645e0c241a93369ff53f26e0,f0c07b9967fa64f3ab0bdec0
filters[name]	String Entity name value. Example Copy filters[name]=Christmas%20Promotion
filters[companyId]	String Comma-separated list of company IDs that should be used for filtering. Example Copy filters[companyId]=139,200
filters[activeAt]	String When provided, only promotions that are active during the specified time will be returned. Example Copy filters[activeAt]=2021-01-23T11%3A30%3A58%2B00%3A00
filters[shopCountryId]	String Comma-separated list of shop country IDS that should be used for filtering. Example Copy filters[shopCountryId]=1,2,3
filters[status]	String Comma-separated list of statuses to filter for. Valid values are: archived inactive active Example Copy filters[status]=active,inactive,archived
filters[effect]	String Filter for a specific effect of promotions. Valid values are: buy_x_get_y automatic_discount Example Copy filters[effect]=automatic_discount
filters[audienceId]	String Comma-separated list of audience IDs (strings) that should be used for filtering Example Copy filters[audienceId]=48f75314ba216a213d32868e,02bc1c8cb9b7bcd39247ebd0
filters[activationType]	String Filter for a specific activation type. Valid values are: automatic code Example Copy filters[activationType]=code
filters[promotionCodes]	String Comma-separated list of promotion codes that should be used for filtering Example Copy filters[promotionCodes]=d27d75a754bf13d014296633,9a22a66d2f1101cdb5b54502
with	String The parameter allows you to include the following nested resources in the response: customData Example Copy with=customData
limit	Integer Maximum number of entities in the result. When fetching entities with children, the limit always applies to the amount of parent entities (max. 1000).
cursor	String A valid cursor that can be used for pagination, base64-encoded. Example Copy cursor=Mgo%3D

Example

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Promotions.getPromotions({
    "filters[id]": ["645e0c241a93369ff53f26e0", "f0c07b9967fa64f3ab0bdec0"],
    "filters[name]": "Christmas Promotion",
    "filters[activeAt]": "2024-04-09T10:00:00+01:00",
    "filters[shopCountryId]": [1, 2, 3],
    "filters[companyId]": [100, 200],
    "filters[status]": ["active", "inactive", "archived"],
    "filters[effect]": "automatic_discount",
    "filters[audienceId]": ["48f75314ba216a213d32868e", "02bc1c8cb9b7bcd39247ebd0"],
    "filters[activationType]": "code",
    "filters[promotionCodes]": ["d27d75a754bf13d014296633", "9a22a66d2f1101cdb5b54502"],
    "cursor": "Mgo=",
    "limit": 100,
    "with": "customData"
});

let promotions = response.body.entities;

promotions.forEach(
    promotion => console.log(promotion.id)
);

Get promotion

SCAYLE allows you to retrieve a promotion by its ID.

Method signature

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Promotions.getPromotion(options);
let promotions = response.body;

Options

The createPromotion endpoint can be used with an optional query parameter:

Parameter	Details
with	String The parameter allows you to include the following nested resources in the response: customData Example Copy with=customData

Example

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Promotions.getPromotion({
    promotionId: "645e0c241a93369ff53f26e0",
    with: "customData"
});

let promotions = response.body;

console.log(promotion.id);

Delete promotion

SCAYLE allows you to delete a promotion by its ID. The request returns a 204 No Content on success.

Method signature

JavaScriptPHPcURLJava

Copy

adminApi.apis.Promotions.deletePromotion({
    promotionId: "promotionId"
});

Example

JavaScriptPHPcURLJava

Copy

adminApi.apis.Promotions.deletePromotion({
    promotionId: "645e0c241a93369ff53f26e0"
});

Deprecated (will be removed in near future)

Use Admin API:

• Create Promotions
• Update Promotions

Required parameters

Optional parameters

Storefront API

Use the Storefront API to:

• fetch a list or specific promotions (also upcoming promotions)

In the SCAYLE Panel

You can manage Promotions in the SCAYLE Panel.
Use it to create, update and delete promotions.

SCAYLE Panel allows you to manage following Promotion types:

• Advanced
• Automatic discount
• Item Discount
• Buy X get Y
• Flash Sales

Additionally, you can manage:

• Price Campaigns
• Tiered Discounts
• Vouchers

Advanced promotions

Use one of our templates to create a promotion. By using the supported_effect parameter, you can quickly create:

• Buy X get Y
• Automatic Discount