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 a promotion has two IDs:

  • promotionId - This is the main ID of the promotion (the "template"). Several users can have the same value in this field, since it just refers to the main promotion. It can't be used to redeem a promotion for any specific contact.

  • id - This identifies a specific "instance" of that promotion. It is unique to that contact and is used to redeem the promotion for that contact.

Important

The value id 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" 
}

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

In this section: