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:

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:

json

Copy

{
    "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:

json

Copy

{
    "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:

json

Copy

{
  "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.