Get promotions for contact
This endpoint is used to fetch all available promotions assigned to a contact:
GET /api/v2/contacts/{contactId}/promotions
You will need the unique contactId of the contact. If you don’t have it, you can use this endpoint to get it.
Getting the promotions
When calling this endpoint you can add a query-string parameter redemptionChannelType to filter the response.
The value of redemptionChannelType can be either ECOM, POS or OTHER. Here's how that looks:
GET /api/v2/contacts/67ea9958-0e09-484f-b4c4-aa3e00e1e24c/promotions?redemptionChannelType=ECOM
If this parameter is left out, then all promotions for this contact will be returned.
The response will look something like this:
[
{
"id": "00000000-0000-0000-0000-000000000000",
"promotionId": "00000000-0000-0000-0000-000000000000",
"externalId": "string",
"type": "string",
"name": "string",
"expiresOn": "2024-10-24T11:39:34.699Z",
"heading": "string",
"description": "string",
"redeemed": true,
"redeemedOn": "2024-10-24T11:39:34.699Z",
"imageUrl": "string",
"link": "string",
"redemptionChannels": [
{
"type": "POS",
"valueType": "PERCENT",
"value": 10,
"localValues": [
{}
],
"instruction": "string"
}
]
}
]Important
A request to this endpoint will only return promotions where the assigned promotion AND the main promotion are active, with a start date that is not in the future. This query will not filter out redeemed promotions as long as they otherwise fulfill the criteria for being active.
Redemption channels
The object redemptionChannels 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.
redemptionChannels.type declares which channel the promotion applies to.
redemptionChannels.valueType declares which type of discount we want to assign (percentage, monetary or external code).
redemptionChannels.value is the percentage, monetary amount or the external code referring to the external price rule. With a monetary discount we also expose the group currency set in Engage for the specific client.
redemptionChannels.instruction is an instruction that can be added to the promotion by the Engage user to, for example, give some information to store staff regarding the promotion.
These can be displayed in all currencies declared for the client installation of Engage.
A POS promotion with a percentage discount
"redemptionChannels": [
{
"type": "POS",
"valueType": "PERCENT",
"value": 15,
"instruction": "POS instructions."
}
]An e-com promotion with an external discount code
"redemptionChannels": [
{
"type": "ECOM",
"valueType": "EXTERNALOFFER",
"value": "DISCOUNTCODE",
"instruction": "POS instructions."
}
]A POS promotion with a monetary discount
"redemptionChannels": [
{
"type": "POS",
"valueType": "MONEY",
"value": {
"currency": "EUR",
"amount": 10
}
}
]