Promotions

Rewarding your customers always pays off. For this, Engage has a Promotions module. There are several kinds of promotions available in Engage but the kind you can interact with via the Engage API are multichannel promotions so these are the main focus here.

Multichannel promotions

A multichannel promotion is one that can be set up to be used in-store or online or both ways. These promotions can be assigned to a contact based on their previous purchases or on any other type of contact data or interaction. You can assign multichannel promotions to segments as well as to single contacts in Engage. For this reason they’re also known as personal offers. Multichannel promotions can be used:

In-store - Here the contact is identified at the POS and their active multichannel promotions are fetched from Engage and are ready to use in the checkout
Online - Here the customer will also need to identify themselves at some point in the flow, either by logging in, or when they fill in their details at the checkout. Then all available multichannel promotions can be fetched from Engage and shown. How exactly this is done will depend on how the e-com has been set up.

Creating multichannel promotions

There are several ways to create and assign multichannel promotions when working with Engage. In this article the focus will be mostly on the Engage API but there are also these methods:

Promotions via the Engage UI

Setting up a multichannel promotion in Engage

You will select the type of the promotion from the dropdown. You can use different values for “Can be used in store” and “Can be used online” in the same promotion. The options available are:

Monetary discount
Discount in percent
Manual instruction (only for in-store POS)
External promotion code

In the value type “External promotion code” the actual price rule is not stored in the promotion itself but in the retailer’s system (ERP or e-com platform). When this kind of promotion is displayed, the POS looks up the relevant price rule using the external promotion code and then displays those details. Staff or customers will not notice this happening.

Learn about setting up multichannel promotions

Promotions via XML file import

Assigning promotions by XML file import are covered in this article:

Assigning promotions by XML file

Get promotions for contact

The API endpoint used to fetch all available promotions assigned to a contact is:

GET /api/v3/promotion-assignments

These query string parameters are used:

contactId - The contact’s unique ID. If you have some other contact identifier, use this endpoint to get the contactId you will need for this request.
redemptionChannelType - “ECOM”, “POS” or “OTHER”. If left out, all promotions are returned.

See example request

GET /api/v3/promotion-assignments?contactId=67ea5555-0e09-484f-b4c4-aa3e00e1e24c&redemptionChannelType=ECOM

See example response

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "promotionId": "00000000-0000-0000-0000-000000000000",
    "externalId": "string",
    "type": "string",
    "name": "string",
    "expiresOn": "2026-04-24T10:44:50.626Z",
    "validFrom": "2026-04-24T10:44:50.626Z",
    "heading": "string",
    "description": "string",
    "redeemed": true,
    "redeemedOn": "2026-04-24T10:44:50.626Z",
    "assignedOn": "2026-04-24T10:44:50.626Z",
    "source": "Automation",
    "imageUrl": "string",
    "link": "string",
    "redemptionChannels": [
      {
        "type": "POS",
        "valueType": "PERCENT",
        "value": 10,
        "localValues": [
          {
            "amount": 123.45,
            "currency": "EUR"
          }
        ],
        "instruction": "string"
      }
    ]
  }
]

string

This identifies a specific “instance” of the promotion that was created from the “template” that was identified by promotionId. The id value is unique to that contact and is the one used when redeeming this promotion.

string

This is the ID of the main promotion (the “template” this particular promotion was created from). Many customers can have the same value for this, since it just refers to the main promotion. This CAN’T be used to redeem a promotion.

string

This value exists when the promotion has been created over the API. If the promotion was created manually in the Engage UI, this is null. It is not important when redeeming the promotion.

The value returned as id is what you must use to redeem the promotion.

A request to this endpoint will only return those promotions where the assigned promotion AND the main promotion are active, and with a start date that is not in the future. This query will include already redeemed promotions as long as they otherwise fulfill the criteria for being active.

Redemption channels

When getting a contact’s promotion data, you’ll get back something like this:

[
  {
    "id": "bb247ef7-80bb-440c-beb7-ab4172e56666",
    "promotionId": "1a50b7aa-d697-4dc6-3ce7-ab2c00b3a920",
    "externalId": "SO-14034",
    "type": "Multichannel",
     ...
    "redemptionChannels": [
      {
        "type": "POS",
        "valueType": "EXTERNALOFFER",
        "value": "10056",
        "instruction": null
      },
      {
        "type": "ECOM",
        "valueType": "EXTERNALOFFER",
        "value": "10056",
        "instruction": null
      }
    ]
  }
]

The redemptionChannels object in the response specifies if a promotion is a percentage, a monetary amount to be withdrawn from the total amount of the transaction, or an external discount code that refers to a price rule in your platform.

See redemption channels object

[
  {
    ...
    "redemptionChannels": [
      {
        "type": "POS",
        "valueType": "MONEY",
        "value": {
            "currency": "EUR",
            "amount": 10
        },
        "instruction": null
      }
    ]
  }
  ...
]

These are the fields in the redemptionChannels object:

type - Which channel the promotion applies to.
valueType - Which type of discount we want to assign (percentage, monetary or external code).
value - The percentage, monetary amount or external code referring to the external price rule. With a monetary discount we also expose the group currency set in Engage for that client.
instruction - An instruction that can be used, for example, to give some information to store staff regarding the promotion.

These can be displayed in all currencies declared in your Engage environment.

Some redemptionChannels examples:

Example: POS promotion with percentage discount

"redemptionChannels": [
    {
        "type": "POS",
        "valueType": "PERCENT",
        "value": 15,
        "instruction": "POS instructions."
    }
]

Example: E-com promotion with external discount code

"redemptionChannels": [
    {
        "type": "ECOM",
        "valueType": "EXTERNALOFFER",
        "value": "Mega_discount_March25",
        "instruction": "POS instructions."
    }
]

Example: POS promotion with monetary discount

"redemptionChannels": [
    {
        "type": "POS",
        "valueType": "MONEY",
        "value": {
            "currency": "EUR",
            "amount": 10
        }
    }    
]

Assign a promotion

Multichannel promotions, as mentioned, can be assigned to contacts in these ways:

Over the Engage API
Manually in the Engage UI
Though an XML file import

Here we will continue to focus on the Engage API method, with this endpoint:

POST /api/v3/promotion-assignments

With this request you send the following kind of payload:

{
    "contactId": "e0e63d15-1881-4f9a-9ce1-94c3e21c6f47",
    "promotionId": "132aa326-fa89-4a8b-af9f-0b232157f8a2"
}

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

400: InvalidContactId, InvalidPromotionId
404: ContactNotFound, PromotionNotFound

Redeem a promotion

As soon as a promotion is used in a purchase, it must be redeemed in Engage so it can’t be used again. To do this you’ll need to know:

the promotion’s unique assignment ID
the redemption channel, either “POS” or “ECOM”

Since the assignment ID is already connected to a unique contact, the contact’s details are not needed when redeeming a promotion.

There are two steps in redeeming:

Call the /redeem endpoint

Redeem the promotion with a call to this endpoint, adding the assignment ID in the path:

POST /api/v3/promotion-assignments/{id}/redeem

In the request body, add the redemption channel:

{  
   "redemptionChannel": "ECOM" 
}

Add promotion ID to /receipts call

As with every purchase, you will also call this endpoint with the full receipt information:

POST /api/v3/receipts

Here you will add the assignment ID of the promotion used to the usedPromotions block in the body of the query:

...
"usedPromotions": [
    {
        "promotionId": "6374dfaa-31c5-4e34-bb88-7ccfc5fe8bf7"
    }
]
...

If you only call the /receipts endpoint but not /redeem, the promotion will still be redeemed, but often after a delay, bringing the risk that it could be used again. If you call /redeem but miss to add the promotion assignment ID to the /receipts call, the system will not know which transaction to connect the redeemed promotion to. It will try to work it out based on the timestamp, checking for transactions within ±5 minutes of the redemption. So you should always do both of these things whenever a promotion is used in a purchase.

After 4.5 seconds the /redeem endpoint will time out, provided it has not already saved the promotion as redeemed. If the promotion has been redeemed (this is known as the “point of no return”) when the 4.5 seconds limit is passed, the request will be processed until completion. It is therefore recommended to not have a timeout shorter than 60 seconds, in order to avoid situations where a promotion is redeemed in Engage but the calling system does not know it due to aborting the request.

Redemption response codes

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

400: NotAValidRedemptionChannel, InvalidPromotionIdNoData
404: PromotionNotFound, PromotionNotAssociatedWithContact
409: PromotionNotValidForRedemptionChannel, PromotionAlreadyRedeemed, PromotionAlreadyRedeemed
504: GatewayTimeout

Create a promotion

Creation of a multichannel promotion can be done in three ways:

Over the Engage API
Manually in the Engage UI
Though an XML file import

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

Create a draft promotion using 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 an end date

When sending in the startDate or endDate send only the year, month and day as in the examples shown below. Specific times in a day cannot be used.

Creating promotion with 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"
    }
  ]
}

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.

Creating promotion with 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"
    }
  ]
}

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

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

400: BadRequest
500: Error

Update a promotion

You can update (alter) a multichannel promotions over the Engage API.

Only draft promotions can be updated, not active promotions.

You can update the entire promotion or only its validity. Each method uses a different API endpoint:

Updating the entire promotion

To update the entire multichannel promotion, used this endpoint:

PUT /api/v3/promotions/multichannels/{id}

Send a payload in the same format as when you created the promotion, including your updates:

{
  "id": "24138ab3-0421-4688-a4b0-40a3c410fa4f",
  "status": "Draft",
  "externalId": "externalIdentifier",
  "name": "Promotion Name",
  "validity": {
    "startDate": "2019-10-15T11:18:50.5258317+02:00",
    "assignedValidity": {
      "unit": "Months",
      "amount": 3
    }
  },
  "presentation": {
    "heading": "Promotion presentation title",
    "description": "Promotion presentation description",
    "link": "http://www.example.com"
  },
  "redemptionChannels": [
    {
      "type": "POS",
      "valueType": "EXTERNALOFFER",
      "value": "PromotionCode123",
    },
    {
      "type": "ECOM",
      "valueType": "EXTERNALOFFER",
      "value": "PromotionCode123"
    }
  ]
}

Updating the promotion's validity

To update just the duration of an existing multichannel promotion, send a PUT to this endpoint:

PUT /api/v3/promotions/multichannels/{id}/validity

With a payload formatted like this:

{
  "startDate": "2019-10-14T09:18:50.885+01:00",
  "endDate": "2021-10-14T09:18:50.885+01:00",
  "assignedValidity": {
    "unit": "Months",
    "amount": 4
  }
}

Delete a promotion

You can delete a promotion using its Engage ID or its external ID (assuming an external ID was used when creating the promotion).

Only unassigned promotions can be deleted.

Delete a promotion using its Engage ID

To delete a multichannel promotion using the ID, use this endpoint:

DELETE /api/v3/promotions/multichannels/{id}

The id value here is the Engage ID (“31bc4f89-6e71-4086-8627-af8f01073331” or similar).

Delete a promotion using its external ID

To delete a multichannel promotion using the external ID, use this endpoint with externalId as the query parameter:

DELETE /api/v3/promotions/multichannels?externalId=whatever

Export promotions by XML

Exporting promotions by XML files are covered in this article:

Contacts

Transactions

Orders

Loyalty

Product data

Elevate

Ratings and Reviews

Multichannel promotions

Creating multichannel promotions

Learn about setting up multichannel promotions

Assigning promotions by XML file

Get promotions for contact

Redemption channels

Assign a promotion

Redeem a promotion

Redemption response codes

Create a promotion

Update a promotion

Delete a promotion

Export promotions by XML

Exporting promotions by XML file

​Multichannel promotions

​Creating multichannel promotions

Learn about setting up multichannel promotions

Assigning promotions by XML file

​Get promotions for contact

​Redemption channels

​Assign a promotion

​Redeem a promotion

​Redemption response codes

​Create a promotion

​Update a promotion

​Delete a promotion

​Export promotions by XML

Exporting promotions by XML file

Multichannel promotions

Creating multichannel promotions

Get promotions for contact

Redemption channels

Assign a promotion

Redeem a promotion

Redemption response codes

Create a promotion

Update a promotion

Delete a promotion

Export promotions by XML