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.

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.

Parameter	Details
id	Integer READ-ONLY The ID of the campaign created by SCAYLE.
name	String Name of the campaign.
description	String Optional description of the campaign.
countryCodes	String List of country codes the campaign is valid for.
reduction	Double The reduction percentage applied to all variants, which do not have a specific reduction set.
startAt	String Start time of campaign in ISO 8601 format.
endAt	String End time of campaign in ISO 8601 format.
campaignKey	String A specific key to identify the campaign. If not provided, it will be generated by SCAYLE.
customData	CustomData

Examples

Create a Campaign

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:

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.

campaignKey is read-only and cannot be updated.

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

Parameter	Details
id	Integer `READ-ONLY` The ID of the campaign created by SCAYLE.
name	String Name of the campaign.
description	String Optional description of the campaign.
countryCodes	String List of country codes the campaign is valid for.
reduction	Double The reduction percentage applied to all variants, which do not have a specific reduction set.
startAt	String Start time of campaign in Iso8601 format.
endAt	String End time of campaign in Iso8601 format.
campaignKey	String A specific key to identify the campaign. If not provided, it will be generated by SCAYLE.
customData	CustomData

Examples

Simple Update

Update a campaign's overall reduction:

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

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.

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:

Parameter	Details
with	String Allows to load the following nested resources within this request: customData

Parameters

Parameter	Details
id	Integer READ-ONLY The ID of the campaign created by SCAYLE.
name	String Name of the campaign.
description	String Optional description of the campaign.
countryCodes	String List of country codes the campaign is valid for.
reduction	Double The reduction percentage applied to all variants, which do not have a specific reduction set.
startAt	String Start time of campaign in Iso8601 format.
endAt	String End time of campaign in Iso8601 format.
campaignKey	String A specific key to identify the campaign. If not provided, it will be generated by SCAYLE.
customData	CustomData

Examples

Get a Campaign by ID

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.

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	Details
limit	Integer Maximum number of items in the result. (default: `100`, maximum: `1000`)
filters[id]	String Comma-separated list of campaign IDs that should be used for filtering.
filters[minId]	Integer Minimum campaign ID of entities that should be returned.
filters[maxId]	Integer Maximum campaign ID of entities that should be returned.
with	String Allows to load the following nested resources within this request: customData

Parameter

Parameter	Details
entities	Campaign A collection of campaigns.
cursor	Cursor An object containing information for use in pagination.

Details

entities

Campaign

A collection of campaigns.

cursor

Cursor

An object containing information for use in pagination.

Examples

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.

This action can not be undone!

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

Example

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.

It can take up to an hour until the freshly created campaign appears in the Storefront API.

Get a Single Campaign

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

Parameters

Parameter	Type	Details
`campaignId`	Integer	ID of the price campaign to retrieve.

Example

Get a Specific Campaign by ID

All examples require a configured Storefront API client being available as client.

See Authentication for how to set up.

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

Response

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

Parameter	Type	Details
parameters	CampaignEndpointRequestParameters	Specify additional options

Example

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

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

Response

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

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.