Skip to main content

Loyalty

Storefront REST API endpoints related to Okendo Loyalty. Both unauthenticated and after customer authentication.

If you're rendering in Liquid, a snapshot of the customer's points balance, enrolment status, and VIP tier name is already available without an API call via Customer Metafields.

Pre-Requisites​

Okendo Partner ID​

If you're integrating with Okendo Loyalty using these APIs, send an email to solutions@okendo.io to retrieve the value of your okendo-partner-id header.

Terminology​

  • Earning Rule: a way for a customer to earn points.
  • Redemption Rule: a way for a customer to redeem points for a reward.
  • Transaction: an instance of points being awarded or removed from a customer.

For anonymous customers, use the unauthenticated endpoints to display general details about the loyalty program. Once a customer has logged into their Shopify account and you have their user token, you should call POST /loyalty/login to exchange this for an Okendo Loyalty customer token (JWT).

Once you have an Okendo Loyalty customer token, you can call the Customer Authed endpoints which will tailor the response content for that specific customer. For example some earning or redemption rules may only be available to certain customers or they will earn more points if they're on a certain VIP tier. To call these Customer Authed endpoints, provide your Okendo Loyalty customer token as Bearer authentication in the request header. Note: A customer that hasn’t enrolled in the loyalty program can still be logged in and shown details like their points balance and earning history. However to redeem points for rewards, be placed in a tier, and more they will need to enrol in the program.

Program Enrolment​

Okendo requires each customer to explicitly enrol in the loyalty program. By using these APIs you agree to follow the following steps in compliance with our enrolment flow:

  1. After the POST /loyalty/login call, if the customer's status is pending, continue to step 2. If the customer's status is blocked, they should not have access to participate in the program. If the customer's status is enrolled, the following steps can be skipped as the customer has already agreed to the terms during previous enrolment.
  2. Call the GET /loyalty/legal_policies endpoint to retrieve the policies and legal texts of the loyalty program (both by Okendo and by the merchant).
  3. These terms must be shown to the customer before they agree to enrol in the loyalty program. The acceptTermsAndJoinProgramButtonText is to be used as the button text and the policySentence.html (or equivalent using policySentence.template, privacyPolicyUrl and termsAndConditionsUrl) is to be displayed below or above the opt-in button. The version of the terms is also provided and will be required in the next step. The following is an example of how the enrol button and terms are to be displayed.
  1. When the enrol button is clicked, call the POST /loyalty/customer_activation endpoint with the following body: { enrollmentChannel: <your_okendo_partner_id>, legalPoliciesVersionAccepted: <'version' field value from step 3> }. Note: If you're a technology partner, the okendo-partner-id header will need to be set to the same value as the enrollmentChannel.
  2. The customer is now enrolled in the loyalty program. Their sign-up points will be awarded and their initial VIP tier will be set.