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 identified by promotionId. It 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/v2/promotions/codes/{promotionId}/redeem

Caution

Despite how it looks in the request description, be sure to use the id value of the promotion here, 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" 
}

Another way to redeem a promotion is with this endpoint, using the same payload as above:

POST /api/v2/contacts/{contactId}/promotions/{promotionId}/redeem

This method will first validate that the given contactId actually has the promotion with this unique promotionId value assigned to them, and then proceed with the redemption if this validation succeeds. Apart from this, both redemption methods are the same and run the same code.

Response codes

If the request to /api/v2/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: