Skip to main content

Create a promotion

Creation of a multichannel promotion can be done the Engage UI, by the API or by XML file import.

This article goes through creating a multichannel promotions via the Engage API.

Tip

A new promotion is created in Engage as a draft. It must then be activated so that it can be assigned to individual contacts. This assignment is manually done in the Engage UI.

Promotion creation

Create a draft promotion with the following endpoint:

POST /api/v3/promotions/multichannels

You can create a promotion in two ways:

  • By giving a start date and a validity time

  • By giving a start date and also an end date

Caution

When sending in the startDate or endDate, send only the year, month and day as in the examples below. Promotions can't be made to start or end at user-defined times during the day.

1) Start date and validity time

Here is what such a request looks like:

{
  "externalId": "externalIdentifier",
  "name": "Example promotion name",
  "validity": {
    "startDate": "2020-03-18",
    "assignedValidity": {
      "unit": "Months",
      "amount": 3
    }
  },
  "presentation": {
    "heading": "Example heading",
    "description": "Example description",
    "link": "http://www.example.com"
  },
  "redemptionChannels": [
    {
      "type": "POS",
      "valueType": "EXTERNALOFFER",
      "value": "POS-CAMPAIGN-123",
      "instruction": "Example POS instruction"
    },
    {
      "type": "ECOM",
      "valueType": "EXTERNALOFFER",
      "value": "ECOM-CAMPAIGN-1337"
    }
  ]
}

Here is a successful response, containing the promotion's ID:

{
  "id": "9125f018-1838-4f65-929d-87f0b4353661",
  "status": "Draft",
  "externalId": "externalIdentifier",
  "name": "Example promotion ame",
  "validity": {
    "startDate": "2020-03-18T00:00:00+02:00",
    "assignedValidity": {
      "unit": "Months",
      "amount": 3
    }
  },
 "presentation": {
    "heading": "Example heading",
    "description": "Example description",
    "link": "http://www.example.com"
  },
  "redemptionChannels": [
    {
      "type": "POS",
      "valueType": "EXTERNALOFFER",
      "value": "POS-CAMPAIGN-123",
      "instruction": "Example POS instruction"
    },
    {
      "type": "ECOM",
      "valueType": "EXTERNALOFFER",
      "value": "ECOM-CAMPAIGN-1337"
    }
  ]
}

Important

The value id here is the ID for the promotion definition. This is used to assign this promotion to individual contacts. Each assignment gets its own ID, connecting this promotion and contact.

2) Start date and end date

Here is what such a request looks like:

{
  "externalId": "externalIdentifier",
  "name": "Example promotion name",
  "validity": {
    "startDate": "2020-03-18",
    "endDate": "2020-06-18",
  },
  "presentation": {
    "heading": "Example heading",
    "description": "Example description",
    "link": "http://www.example.com"
  },
  "redemptionChannels": [
    {
      "type": "POS",
      "valueType": "EXTERNALOFFER",
      "value": "POS-CAMPAIGN-123",
      "instruction": "Example POS instruction"
    },
    {
      "type": "ECOM",
      "valueType": "EXTERNALOFFER",
      "value": "ECOM-CAMPAIGN-1337"
    }
  ]
}

Here is a successful response, containing the promotion's ID:

{
  "id": "9125f018-1838-4f65-929d-87f0b4353661",
  "status": "Draft",
  "externalId": "externalIdentifier",
  "name": "Promotion Name",
  "validity": {
    "startDate": "2020-03-18T00:00:00+02:00",        
    "endDate": "2020-06-18T23:59:59+02:00",
    "assignedValidity": null
  },
  "presentation": {
    "heading": "Promotion presentation title",
    "description": "Promotion presentation description",
    "link": "http://www.example.com"
  },
  "redemptionChannels": [
    {
      "type": "POS",
      "valueType": "EXTERNALOFFER",
      "value": "POS-CAMPAIGN-123"
    },
    {
      "type": "ECOM",
      "valueType": "EXTERNALOFFER",
      "value": "ECOM-CAMPAIGN-1337"
    }
  ]
}

Caution

The maximum value for end date is 9999-12-30.

Response codes

If your request has been successful, you'll get a HTTP 200 OK response. Otherwise you'll get one of these:

  • 400: BadRequest

  • 500: Error