Price Campaigns

General

Price campaigns include a defined range of products which are relatively discounted in a given time period for all customers. Discounts are already presented in the storefront on product listing and product detail pages, as well as in the basket.

Only one single price campaign can be active per shop. However, it is possible to bundle different product groups (such as women, men, and children) in one price campaign and to discount these product groups as part of one campaign.

The same price campaign can be started for one or more shop countries. It has a start and end date and can have a common discount which will be applied on all products except those which have a dedicated product variant reduction.

Campaign key

SCAYLE allows users to create multiple campaigns with the same campaign key in the same country. Every campaign gets a campaign key when it's created. If no campaign key is provided by the user, it is auto-generated.

Custom data

Custom data of campaigns can be used to store the devices that belongs to a particular campaign key e.g., deviceCategories: ['app', 'web'] The frontend fetches custom data via Storefront’s campaigns endpoint. Based on the custom data and the current device category it can decide if it needs to pass the campaign key to the Storefront API or not.

Admin API

Create a Campaign

Learn how to create a price campaign and discount all products or specific products and variants.

When setting up a new price campaign, you need to define name, respective countries, discount amount, and a time frame. Reductions are always given in fixed percent.

JavaScriptPHPcURLJava

Copy

await adminApi.apis.Campaigns.updateOrCreateVariantReductions({shopKey: shopKey, campaignId: campaignId}, {requestBody: reductions});

When creating a new campaign the following validation rules must pass:

• The startAt and endAt date must be in the future.
• The endAt date must be greater than startAt date.
• There is no already existing campaign within the same timeframe and for the provided countryCodes and campaignKey.

Examples

Create a Campaign

JavaScriptPHPcURLJava

Copy

let newCampaign = {
    name: "My Campaign",
    description: "My first campaign",
    countryCodes: [
        "DE"
    ],
    startAt: "2020-11-23T12:00:00+00:00",
    endAt: "2020-11-25T12:00:00+00:00"
};

let response = await adminApi.apis.Campaigns.createCampaign({shopKey: "ms"}, {requestBody: newCampaign});
let createdCampaign = response.body;

Complex Create

Create a campaign with overall reduction:

JavaScriptPHPcURLJava

Copy

let newCampaign = {
    name: "My Campaign",
    description: "My first campaign",
    countryCodes: [
        "DE"
    ],
    reduction: 10.0,
    startAt: "2020-11-23T12:00:00+00:00",
    endAt: "2020-11-25T12:00:00+00:00"
};

let response = await adminApi.apis.Campaigns.createCampaign({shopKey: "ms"}, {requestBody: newCampaign});
let createdCampaign = response.body;

Update a Campaign

In some cases, you might want to change the reduction percentage of a price campaign or extend the duration of the campaign. You can do so by replacing the campaign's existing parameters with new ones.

This method can be used to update/replace an existing campaign.

This method does not support partial updates.

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Campaigns.updateCampaign({shopKey: shopKey, campaignId: campaignId}, {requestBody: campaign});
let updatedCampaign = response.body;

When updating a campaign the following validation rules must pass:

• The startAt and endAt date must be in the future.
• The endAt date must be greater than startAt date.
• There is no already existing campaign within the same timeframe for the provided countryCodes and campaignKey

Examples

Simple Update

Update a campaign's overall reduction:

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Campaigns.getCampaign({shopKey: "ms", campaignId: 1});
let campaign = response.body;

campaign.reduction = 5.0;

let updateResponse = await adminApi.apis.Campaigns.updateCampaign({shopKey: "ms", campaignId: campaign.id}, {requestBody: campaign});
let updatedCampaign = updateResponse.body;

Extend an existing campaign

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Campaigns.getCampaign({shopKey: "ms", campaignId: 1});
let campaign = response.body;

campaign.endAt = "2022-11-27T12:00:00+00:00";

let updateResponse = await adminApi.apis.Campaigns.updateCampaign({shopKey: "ms", campaignId: campaign.id}, {requestBody: campaign});
let updatedCampaign = updateResponse.body;

Get a Campaign

When you set up a price campaign, SCAYLE will assign it a unique reference key, its campaign ID, making it easy to request a specific campaign.

This method can be used to get an existing campaign by using SCAYLE's internal campaign ID.

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Campaigns.getCampaign({shopKey: shopKey, campaignId: campaignId});
let campaign = response.body;

Options

The operation can be used with optional parameters - called options:

Parameters

Examples

Get a Campaign by ID

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Campaigns.getCampaign({shopKey: "ms", campaignId: 1});
let campaign = response.body;

Get a Collection of Campaigns

When retrieving multiple price campaigns, you can paginate results and apply other parameters to narrow down your query.

This method can be used to get a collection of existing campaigns. It is possible to refine the search by applying filters in the options.

This method will only return active and planned campaigns.

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Campaigns.getCampaigns({shopKey: shopKey});
let campaigns = response.body.entities;

Options

The operation can be used with optional parameters - called options:

Parameter

Examples

JavaScriptPHPcURLJava

Copy

let response = await adminApi.apis.Campaigns.getCampaigns({shopKey: "ms"});
let campaigns = response.body.entities;

campaigns.forEach(
    campaign => console.log(campaign.name)
);

Delete a Campaign

You can delete a price campaign simply by using its ID.

This method can be used to delete an existing campaign along with all its product and variant reductions.

JavaScriptPHPcURLJava

Copy

adminApi.apis.Campaigns.deleteCampaign({shopKey: shopKey, campaignId: campaignId});

Example

JavaScriptPHPcURLJava

Copy

adminApi.apis.Campaigns.deleteCampaign({shopKey: "ms", campaignId: 1});

Storefront API

Campaigns allow to discount products for a limited amount of time. By using the /campaigns endpoint you can retrieve all campaigns or a specific campaign by ID.

After retrieving a campaign, you can use the provided key to query other methods, such as the Get Products method, to retrieve products with prices discounted according to the specified campaignKey. Before you start retrieving campaigns, you need to manually add one or more price campaigns via the SCAYLE Panel.

Get a Single Campaign

By passing a campaign ID to the /campaigns endpoint we can fetch a specific campaign.

Parameters

Example

Get a Specific Campaign by ID

JavaScriptPHPcURL

Copy

// Fetch a campaign with id 12
const response = await client.campaigns.getById(12);
console.log(response.key);
// promo_test_20

Response

json

Copy

{
  "id": 12,
  "name": "20% Promo Test",
  "key": "promo_test_20",
  "description": "",
  "reduction": 20,
  "start_at": "2023-07-23T11:00:00+00:00",
  "end_at": "2023-07-30T11:00:00+00:00",
  "customData": {}
}

Get All Campaigns

You can retrieve a list of all price campaigns by using this method.

After retrieving campaigns, you can then use the provided key to query other methods, such as the Get Products method, to retrieve products with prices discounted according to the specified campaignKey.

Parameters

Example

We can fetch all existing campaigns by using get/getAll. Also we want the results to be sorted by amount of reduction.

JavaScriptPHPcURL

Copy

// Fetch all campaigns
const response = await client.campaigns.get(
  sort: {
  by: "reduction",
    direction: "desc"
},
);
console.log(response.entities[0].key);
// promo_test_20

Response

json

Copy

{
  "pagination": {
    "current": 1,
    "total": 1,
    "perPage": 100,
    "page": 1,
    "first": 1,
    "prev": 1,
    "next": 1,
    "last": 1
  },
  "entities": [
    {
      "id": 12,
      "name": "20% Promo Test",
      "key": "promo_test_20",
      "description": "",
      "reduction": 20,
      "start_at": "2023-07-23T11:00:00+00:00",
      "end_at": "2023-07-30T11:00:00+00:00",
      "customData": {}
    }
  ]
}

In the SCAYLE Panel

The SCAYLE Panel allows you to set up price campaigns to discount products for a limited amount of time within a campaign.

Manage price campaigns in the SCAYLE Panel

1. Go to Shops > Shop > Discounts & Offers > Price Campaigns.

The overview page lists information for each price campaign, such as ID, name, type, start and end date, shops included, and status.

The price campaign status indicates whether a campaign is Active or Inactive. Expired or not yet started price campaigns are automatically assigned the status Inactive.