This article is aimed at explaining a few of the Loyalty API endpoints listed on our developer portal. Understanding their behavior and requirements can help a lot during implementation. We will begin by some golden rules, and then, a parameter common to many endpoints.
Golden rules
When changing validity period, always put the end of validity after the beginning. It’s logical, but if you forget, it will create problems.
If you want to delete a value, please put null without quotes.
Cursor-based pagination
|
|
This new search method replaces the paging, and is more reliable: you can’t get twice the same item in the results, and it helps to compare. The values for:
|
Here is the list of the API endpoints working with cursor-based pagination:
Update a member (PATCH)
This API call is used to modify the Loyalty member system and custom fields. Here is a list you should and should not modify:
|
Fields |
Specifics |
|
card_code |
Don’t modify |
|
program_joined_at |
Don’t modify |
|
card_expire_at |
If the date is in the past, and you change to null or a date in the future, the cardcode is valid again |
|
q_point and nq_point |
Specific endpoint to change the balance |
|
Birthday |
You can modify |
|
Individual |
Can be modified once if the card is not currently linked to a contact. |
|
custom fields |
You can modify |
|
tier |
Specific endpoint to modify it (see next paragraph) |
Change the tier (POST)
This API call is used to modify the tier (regular or VIP) of a Loyalty member.
The force_point parameter will attribute the missing amount of qpoints to reach the tier you specified in the body. If you don’t use this parameter, the member will be in the tier without the needed amount of qpoints.
Rule completion (GET)
This API call is used to retreive the completion of a member of any rule.
| Fields |
Specifics |
|
completion_rate |
the current percentage of completion of the rule by the member |
|
already_matched |
The number of times the member has completed the rule |
The completion rate can be displayed in the personal space of the member (website or app) to encourage to complete the rule to get the outcome.
Create / edit a master reward (POST)
Once a Master Reward is created, only a few of its fields can be modified. The others need to stay the same.
|
Fields you can’t modify |
Fields you can modify |
|
external_id |
limited |
|
price |
auto_generated |
|
nqp_value |
picture_path |
|
holding_days |
Custom fields |
|
validity_interval_count |
Get a member’s eligible rewards
This API call is used by POS to check if a member is eligible to be granted a reward.
Step 1: Get a member’s eligible rewards
Step 2: Grant a reward
Step 3: Use a granted reward