Contents

Purpose

The Redeem Promo Code endpoint is used to redeem promo codes and unlock related offers at a client device (typically a POS or Kiosk terminal). For more information on customer journeys related to this endpoint, please refer to: Kiosk - Promo Codes.

Request format

Endpoint

POST /loyalty/promo-code/redeem

Headers

As documented here: TBC LINK

Body

• loyaltyId <string>: Loyalty ID in UUID format.

• promoCode <string>: string that represents the unique promo code the customer has that when inputted at a client device will unlock an offer.

• posVendor: object identifying system making the request (POS or Kiosk):

  • transactionId <string>: the POS transaction identifier.

  • storeId <integer>: uniquely identifies the store where the guest is identifying from.

  • terminal <string> (optional): identifies the POS or Kiosk terminal used in the restaurant

  • operator <string> (optional): identifies the POS operator (only applicable for orders made on a POS terminal)

  • posType <string>: identified the type of POS or Kiosk system making the request. This value must have been previously agreed between the vendor and RBI, so that the correct integration configuration is applied. In most cases, this will be set to a value of “Partner”.

  • supportingPos <string> (optional): in case the posType is “Partner”, this field should be used to identify the POS/Kiosk brand for analytical purposes.

Example request

{
  "loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7", // uuid of the loyalty user
  "promoCode": "123456", // promo code identifier
  "posVendor": {
    "operator": "300", // cashier / operator id
    "posType": "Kiosk vendor name",
    "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
    "storeId": "9999",
    "terminal": "0", // terminal id
  },
}

Response Format

Success response body

• sanityId <string>: sanity ID of the offer redeemed.

Success response example

{
  "sanityId": "5f887b7e-348f-4861-822a-7dad712989e8" // sanityid of the offer redeemed
}

Error responses

• HTTP 400 (Bad Request) if the request body has an incorrect format. In this case, the response will include details about which specific field or fields have an incorrect format.

• HTTP 401 (Unauthorized) if authentication headers are missing or not valid.

• HTTP 404 (Not Found): in the following scenarios indicated in the code field of the error response:

  • "IdentifierNotFound": if the specified identifier was not found.

  • "StoreNotFound": if the specified storeId was not found.

Error response examples

• Promo code does not exist

{
  "code": "INVALID_PROMO_CODE",
  "details": {
    "promoCode": "123456", // promo code identifier
  },
  "httpCode": 404,
  "message": 'Promo code does not exist'
}

• Promo code is unredeemable

{
  "code": UNREDEEMABLE_PROMO_CODE",
  "details": {
    "promoCode": "123456", // promo code identifier
  },
  "httpCode": 422,
  "message": 'Promo code is unredeemable' | 'Promo code vendor no response' | 'Promo code has already been used'
}

• Promo code partner misconfiguration

{
  "code": "PROMO_CODE_VENDOR_CONFIG_ERROR,
  "httpCode": 422,
  "details": {
    "vendor": $vendorName
  }
  "message": 'Promo Code vendor ${vendor} is not supported.' | 'Promo code vendor config is not correct'
}

Testing

Please use this Postman collection for testing purposes: