Redeem a promotion
If you were to fetch 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
}
]
}
]Notice that several IDs are mentioned here:
promotionId - This is the main ID of the promotion (you can see it as the "template" this promotion was created from). Several users can have the same value for this, since it just refers to the main promotion. This CAN'T be used to redeem a promotion for a specific contact.
id - This identifies a specific "instance" of the promotion that is identified by promotionId. The id value is unique to that contact and used when redeeming this promotion for them.
externalId - 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.
Important
The value returned as id is the promotion instance ID and this is the one you must use to redeem a promotion.
How to redeem
A promotion can be redeemed for a contact using the unique promotion ID. The redemption channel can be POS, ECOM or OTHER. Since a promotion ID is always connected to a unique contact, the contact's details do not have to be used when redeeming, only the promotion ID (and the redemption channel).
To redeem the promotion, use this endpoint:
POST /api/v3/promotion-assignments/{assignmentId}/redeem
Caution
Be sure to use the assignmentId value of the promotion, which is unique for that contact, and not the promotionId value.
The request payload will look like this. Values of redemptionChannel are ECOM, POS and OTHER.
{
"redemptionChannel": "ECOM"
}Timeout
After 4.5 seconds this endpoint will give up and time out, provided it has not already saved the promotion as redeemed. If the promotion has been redeemed (this is also also known as the "point of no return") when the 4.5 seconds limit is passed, the request will be processed until completion.
It is 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.
Response codes
If the request to /api/v3/promotions/codes/{promotionId}/redeem 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