Synchronising User Award Information
This details how to seed and synchronise users loyalty information Pepper's CRM and a 3rd party CRM
What to Synchronise - Pepper Award Resources
The types of loyalty awards that a user can be rewarded with are defined in as "perks" in the pepper platform. A "perk" is a template that defines the characteristics of the award, for instance:
- the type of award - eg STAMP_CARD, PSEUDO_CURRENCY
- how fast an award is earned and redeemed
- rules controlling whether or not an award can be redeemed against an order basket
- the terms and conditions text
- how an award is appears in an App visually
The details of the perk model and how to achieve different loyalty journeys is covered in another guide.
When a perk is granted to a user, the user will receive an "award" resource that tracks the accrual and redemption of points corresponding to the award. (It also contains a copy of the perk template as a cache)
So in order to completely track the Pepper Awards records, a 3rd party CRM should maintain a copy of:
- the perks resources for a merchant
- the following fields from the awards resources for all users of the merchant:
_id, points, userId, perkId. No other fields are required since they are a copy of the fields within the perk.
Perks and Awards are exposed as 2 types of endpoints for legacy reasons:
perksandpointperks, andawardsandpointawards. These are not different types of resource - they both refer to the same perks and awards resources. We will be working to remove this duplication in future versions of the API
Synchronising Perks from Pepper
Downloading Perks
Perk resources for a merchant should be accessed via the GET /perks endpoint. See the API reference Get Perks.
Synchronising Perks
Perks change only occasionally, so it is only necessary to synchronise once a day - or less if the 3rd party CRM is responsible for managing perks itself.
There are no actions associated with changes to perks.
Synchronising User Awards
Download User Awards
To synchronise with user award records, you should first download all the awards using GET /awards to seed your CRM with award points for each user. You only need to store points and the ids to reference the user and the perk.
This is a paged response - remember to make further calls to access all the pages.
For example
GET https://api.pepperhq.com/awards
Authorization: Token <token-provided-by-pepper>
x-application-id: <merchant-code>
x-api-version: 8
Accept: application/json
Accept-Encoding: gzip, deflate
200 OK
{
"items": [
{
...
}
],
"page": {
...
}
}
It is also possible to download awards that have changed since a point in time using the updatedAt query parameter.
See Get Awards API reference.
Synchronise Awards
The GET /actions endpoint should be called on a regular schedule to receive notification of changes since the last call. A suitable schedule is every 5 minutes, or shorter if your responses require multiple pages to retrieve.
You should set query parameters for when.timestamp to a range starting after the last time you requested up to and including the current time. For example: when.timestamp.gt=2021-02-01T10:00:00.000Z & when.timestamp.lte=2021-02-01T10:05:00.000Z will return actions after 10 AM on Feb 1 up to and including 10.05 AM.
You should then process the response for the following events that are relevant for award record changes:
REWARD_EARNEDa user has received an award or earned more points.REDEEM_PERKa user has redeemed some or all of an awardAWARD_POINTS_REFUNDEDa user award redemption has been refunded
Each action will contain a meta data block detailing the users current points balance in metadata.pointsAvailable, and the points added, redeemed or refunded in pointsAdded, pointsRedeemed and pointsRefunded respectively.
Loyalty actions that are associated with a location can be identified by inspecting the action context.location block.
Legacy award events such as REWARD_EARNED should be ignored.
Note, this call should be combined with the user synchronisation actions processing into one omnibus call.
Examples of actions are at the bottom of this section.
Adding and changing Perks
Perks can be added, updated and deleted via the API. See:
Limit the number of perk records for a merchant. Adding hundreds of perks and not cleaning up inactive perk records will adversely affect the merchant's app performance.
Granting or changing User Awards
You can grant awards to users, redeem them, refund them, or directly update their points balance via the API. See:
Awards can also be granted to all users in a segment by using Grant Perk to Segment Users. This results in a long running operation. You can inspect the status using Get Operation By Id.
Action Examples
REWARD_EARNED
{
"_id": "xxxx",
"context": {
"tenant": {
"_id": "xxxx",
"title": "The Grill"
},
"user": {
"_id": "xxxx",
"fullName": "Tom Jones",
"primaryPlatform": "IOS"
},
"location": {
"_id": "xxx",
"title": "Arches",
"geo": [
-0.0970637,
51.5045788
],
"regions": [],
"tags": [
""
]
},
"tags": []
},
"tenantId": "xxxx",
"type": "REWARD_EARNED",
"source": "API_SERVER",
"version": "0",
"when": {
"timezone": "Europe/London",
"timestamp": "2021-03-05T13:37:52.194Z",
"year": 2021,
"monthofyear": 2,
"weekofyear": 10,
"dayofmonth": 5,
"dayofweek": 5,
"daypart": "LUNCH"
},
"metadata": {
"awardId": "xxxxx",
"perkId": "xxxxx",
"loyaltyEarned": 2,
"pointsAdded": 2,
"pointsAvailable": 2,
"trigger": "GLOBAL"
},
"environment": "BETA"
}
REDEEM_PERK
As REWARD_EARNED, but the metadata field contains the following:
{
"type": "REDEEM_PERK",
"metadata": {
"awardId": "xxx",
"perkId": "xxx",
"pointsAvailable": 5,
"pointsRedeemed": 16
}
}
AWARD_POINTS_REFUNDED
As AWARD_POINTS_REFUNDED, but the metadata field contains the following:
{
"type": "AWARD_POINTS_REFUNDED",
"metadata": {
"awardId": "xxx",
"perkId": "xxx",
"pointsAvailable": 15,
"pointsRefunded": 5
}
}