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