Loyalty API v1 - Redeem Promo Code

Owned by Lopes da Costa, Valentina
Last updated: Nov 21, 2024
2 min read

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: Loyalty API - Getting Started.

Body

  • loyaltyId <string> (optional): 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>: identifies the POS or Kiosk terminal used in the restaurant

    • operator <string>: 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): used mainly by kiosk vendors, this field will need to refer to the POS vendor of the store the kiosk is sending the request from.

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

All error responses use the standard Loyalty API v1 - Error Responses format.

  • 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

  • Promo code partner misconfiguration