Creating your first free gift promotion

Free gift promotions in eCommerce serve as powerful marketing tools. They attract new customers, retain existing ones, and encourage larger orders. These promotions differentiate your brand, create excitement, and can even go viral, effectively enhancing your business's sales and overall reputation.

In the following sections, you will learn how to run a typical free gift promotion during Christmas.

Creating the promotion

We will create the promotion using the advanced view of the SCAYLE Panel.

Select the Shop where you want to create your promotion and navigate to Discounts & Offers > Promotions.
Click the + New Advanced Promotion Button on top right corner of the overview table.

Now, we will fill out the promotion fields like so:

Field	Value	Description
Name	Christmas gift	We want to run a Christmas promotion, so “Christmas gift” is a suitable name. This name will be exposed via the Storefront API, in case you also want it to be visible in your store's UI.
Promotion Type	Buy x get y	We want to give out a free gift, so the type has to be buy x get y.
Start Date	01.12.23 00:00	We're running the promotion during the entire month of December.
End Date	31.12.23 23:59	We 're running the promotion during the entire month of December.
Priority	1	For this tutorial, we'll only be running one promotion, so the priority is not relevant for us. We'll just put in 1.
Combinable	None	For this tutorial, we'll only be running one promotion, so we don't have to configure Combinability.
Countries	Germany	Specify the country in which the promotion is valid. For this tutorial, we 're only running it in Germany.
Audiences	None	This promotion is available for all audiences, so we don't need to configure this option.
Max Count	1	We'll set our maximum to 1, because we want to only give away one free gift per basket/order.
VariantId	240	We're setting it to 240 in our case, because this is the variantId of the variant we want to give out for free, when the conditions are fulfilled.
Global conditions and key	key: mov condition: payload.totals.withTax > 12000	The key is freely configurable (it has no direct impact on customers) but it is exposed via the Storefront API . This means it can be used as a translation string, for example. The condition is set to “payload.totals.withTax > 12000”, which checks whether the basket total is greater than 120€ without having a voucher or promotion discount applied. Note that the regular price of an item that is assigned to a buy x get promotion is not counted towards the withTax sum.
Item conditions	None	For this tutorial, we don't need any item conditions. The buy x get y effect will only be applicable to the variantId 240.

Click Save to finish.

Communicating the promotion

We want to communicate the promotion to customers during its runtime. In order to achieve this, we can request the endpoint GET /promotions using the Storefront API, which will give us any currently running and active promotions. (For more details, refer to the Storefront API Fetch Promotions documentation).

Additionally, we need to include the following parameters in our request:

shopId: Represents the identifier of the shop-country
activeAt: Represents the current time

If a request is made before our configured start and end date (in this case, 01.12.23 00:00 - 31.12.23 23:59) it would return no results.

Let’s say we are requesting the endpoint within the valid timeframe. We would get the following response back:

{
    "pagination": {
        "current": 1,
        "total": 1,
        "perPage": 100,
        "page": 1,
        "first": 1,
        "prev": 1,
        "next": 1,
        "last": 1
    },
    "entities": [
        {
            "id": "65438f563a404c7e45779f17",
            "name": "Christmas gift",
            "schedule": {
                "from": "2023-11-30T23:00:00Z",
                "to": "2023-12-31T22:59:59Z"
            },
            "isActive": true,
            "effect": {
                "type": "buy_x_get_y",
                "additionalData": {
                    "maxCount": 1,
                    "variantIds": [
                        240
                    ]
                }
            },
            "conditions": [
                {
                    "level": "global",
                    "key": "mov",
                    "condition": "payload.totals.withTaxWithoutVoucher > 12000"
                }
            ],
            "customData": {}
        }
    ]
}

We can now use the returned information (such as the name of the promotion) in the Storefront. For example, to display a campaign banner and then enrich it with additional data from a CMS, if needed.

For instance, this is how it’s communicated in SCAYLE’s Storefront boilerplate:

Adding the free gift automatically

If a customer has a basket total greater than 120€, the free gift is not automatically added. It has to be added manually using the POST /baskets/:id/items endpoint of the Storefront API. (For more details, refer to the Storefront API Baskets documentation.)

But how do you know in the first place whether the promotion is valid, and the customer is eligible for the free gift?

You can request the customer's basket by using the endpoint GET /baskets/:id/items of the Storefront API including the parameter ?with=applicablePromotions, which will tell you whether a promotion is applicable.

If the customer's basket total is less than 120€, the basket will not return any applicable promotions. Note that the regular price of items assigned to a buy x get y promotion do not count towards the basket total.

If the customer's basket total is greater than 120€, the response will include the applicable promotion within the applicablePromotions array in the response body, like so:

{
    "key": "yourBasketKey",
    "items": [
    ..
    ],
    "packages": [
    ..
    ],
    "cost": {
    ..
    },
    "applicablePromotions": [
        {
            "promotion": {    
              "id": "65438f563a404c7e45779f17",
              "name": "Christmas gift",
              "schedule": {
                "from": "2023-11-30T23:00:00Z",
                "to": "2023-12-31T22:59:59Z"
              },
                "isActive": true,
                "effect": {
                    "type": "buy_x_get_y",
                    "additionalData": {
                        "maxCount": 1,
                        "variantIds": [
                            240
                        ]
                    }
                },
                "conditions": [
                    {
                        "level": "global",
                        "key": "mov",
                        "condition": "payload.totals.withTax > 12000"
                    }
                ],
                "customData": {}
            },
            "itemId": null
        }
    ]
}

You can now add the free gift using the mentioned POST /baskets/:id/items endpoint of the Storefront API and include the promotionId of the respective promotion to the request body. This would give us a request body like so:

{
  "variantId": 240,
  "quantity": 1,
  "promotionId": "65438f563a404c7e45779f17"
}

Well done, you have successfully evaluated whether the basket qualifies for a free gift and added it manually using the Storefront API.

Summary

Here are the key facts you should remember from this tutorial:

Free gift promotions can be created via the SCAYLE Panel using the effect buy x get y.
Promotions can be fetched via the Storefront API in order to communicate them.
You can use the Storefront API basket endpoints in combination with the parameter ?with=applicablePromotions to find out, whether a basket qualifies for a free gift.
Free gifts have to be added actively via Storefront API.
Regular prices of items assigned to a buy x get y promotion are not counted towards the basket total condition (even if the conditions are satisfied and the item is actually free).
Discounts based on automatic discount promotions do not count towards the basket total condition.
Discounts of vouchers do not count towards the minimum basket total.