Skip to main content

Create a promotion

You can create a draft version of a promotion via the Engage API. The activation of this promotion, and assigning it to a specific contact, must be manually done in Engage.

Create a draft promotion with the following endpoint:

POST /api/v2/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

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

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 promition'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"
    }
  ]
}

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 promition'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"
    }
  ]
}

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

In this section: