Contents

Purpose

The Update Points Balance endpoint is used to add or remove loyalty points from a customer’s account. This endpoint can be leveraged by Gamification partners such as Brame to be able assign loyalty points to a customer that has successfully played a game. For more information on Brame, please refer to: Gamification Offer and Points Assignment via Brame.

Request format

Endpoint

POST /loyalty/user/{loyaltyUserId}/points

Headers

As documented here: Loyalty API - Getting Started.

Body

• points <integer>: positive value: Will award points to the user. Negative value: Will remove points from the user’s account.

• partner <enum>: please, contact your RBI Representative to get your assigned partner ID.

• reference <string>: reference to the reason for why the points were assigned. (Eg: “Gamification Campaign Prize #3”).

Example Request

• Assigning 100 points to the user:

{
    "partner": "Partner",
    "points": 100,
    "reference": "Gamification Campaign Prize #3"
}

• Deducting 100 points from the user:

{
    "partner": "Partner",
    "points": -100,
    "reference": "Guest needs to spend 100 points to participate of the Brame game"
}

Response format

Success response body

• id <string>: unique identifier of the loyalty transaction created in UUID format.

• shortId <string>: autogenerated code for easy lookup of the order via support tool.

• loyaltyId <string>: unique identifier of the loyalty user in UUID format.

• channel <string>: “Restaurant”, “App”, or “Web”. Always use “Restaurant” for In-Restaurant orders.

• status <string>: status of the order that indicates if the order is still pending or if it has been completed. This can be “PENDING” for orders not yet completed and “CLAIMED” for orders that were completed.

• createdAt <string>: string that represents the current date and time of the request.

• claimedAt <string>: string that represents date and time of when the request was completed successfully.

• serviceMode <string>: service mode of the order being placed. This can be “EAT_IN”, “TAKEOUT”, ”DRIVE_THRU”, “CURBSIDE”, or “TABLE_SERVICE”.

• pointsEarned <number>: this represents the number of loyalty points the user has earned.

• pointsDeducted <number>: this represents the number of loyalty points the user has redeemed.

• pointsUsed <number>: this represents the number of loyalty points the user has used in a loyalty order in the app or in restaurant. In this request from an external partner, it will always be 0.

• bonusPointsEarned <number>: this represents the number of bonus loyalty points the user has earned in a loyalty order in the app or in restaurant. In this request from an external partner, it will always be 0.

• impactedExpirationBuckets: array identifying how many and when points will expire:

  • expirationDate <string>: string that represents the date and time of when points will expire.

  • points <number>: this represents the number of loyalty points that will expire on this date.

• transactionDetails: object identifying order information from the request (POS or Kiosk):

  • fulfillment: object identifying how the order was completed:

    • autoRelease <boolean>: true if points are assigned immediately to the customer.

    • type <string>: this is the type of request, "POINT_ASSIGNMENT".

• metadata: object identifying request information:

  • partner <enum>: returns “partner” sent in request.

  • reference <string>: reference to the reason for why the points were assigned. (Eg: “Gamification Campaign Prize #3”). returns “reference” sent in the request.

Success response example

• Assigning 100 points to the user:

{
    "id": "45601bf3-6d2a-4318-8842-affc38f563ba",
    "shortId": "EZMHC05S5AYMO2G9",
    "loyaltyId": "6d13456a-1304-5109-a117-af4de20b2487",
    "channel": "CAMPAIGN",
    "status": "CLAIMED",
    "createdAt": "2024-02-28T02:14:05.453Z",
    "impactedExpirationBuckets": [
        {
            "expirationDate": "2024-06-28",
            "points": 100
        }
    ],
    "claimedAt": "2024-02-28T02:14:05.453Z",
    "pointsEarned": 100,
    "bonusPointsEarned": 0,
    "pointsUsed": 0,
    "transactionDetails": {
        "fulfillment": {
            "autoRelease": true,
            "type": "POINT_ASSIGNMENT"
        },
        "orders": [],
        "payments": []
    },
    "metadata": {
        "partner": "Partner",
        "reference": "Gamification Campaign Prize #3"
    },
    "pointsDeducted": 0
}

• Deducting 100 points from the user:

{
    "id": "1ae098e0-dc41-42cc-a4ea-b75b44148381",
    "shortId": "GM2CKQ2QRUAPP90K",
    "loyaltyId": "6d13456a-1304-5109-a117-af4de20b2487",
    "channel": "CAMPAIGN",
    "status": "CLAIMED",
    "createdAt": "2024-02-28T02:15:27.784Z",
    "impactedExpirationBuckets": [
        {
            "expirationDate": "2024-06-28",
            "points": -100
        }
    ],
    "claimedAt": "2024-02-28T02:15:27.784Z",
    "pointsEarned": 0,
    "bonusPointsEarned": 0,
    "pointsUsed": 0,
    "transactionDetails": {
        "fulfillment": {
            "autoRelease": true,
            "type": "POINT_ASSIGNMENT"
        },
        "orders": [],
        "payments": []
    },
    "metadata": {
        "partner": "Partner",
        "reference": "Reason why points were deducted"
    },
    "pointsDeducted": 100
}

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:

  • "TransactionInsufficientPoints": the user want to redeem more points than the user has.

• 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:

  • "UserNotFoundError": the Loyalty user (specifically the loyalty id) was not found.