Skip to main content

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" 
}

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

In this section: