Loyalty

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

Pre-Requisites

Okendo Partner ID

If you're integrating with Okendo Loyalty using these APIs, send an email to [email protected] 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.

Recommended Usage

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 /stores/{subscriberId}/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-authenticated 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 Authenticated 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 /stores/{subscriberId}/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 /stores/{subscriberId}/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.

  4. 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: the okendo-partner-id header will need to be set to the same value as the enrollmentChannel.

  5. The customer is now enrolled in the loyalty program. Their sign-up points will be awarded and their initial VIP tier will be set.

Unauthenticated

Get Earning Rules

get
Path parameters
subscriberIdstringRequired

The unique identifier for the store. Available on the Okendo integration settings page.

Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

A list of earning rules

application/json
get
/stores/{subscriberId}/loyalty/earning_rules
GET /v1/stores/{subscriberId}/loyalty/earning_rules HTTP/1.1
Host: api.okendo.io
okendo-api-version: 2025-02-01
Accept: */*
200

A list of earning rules

{
  "earningRules": [
    {
      "earningRuleId": "123e4567-e89b-12d3-a456-426614174000",
      "action": "sign-up",
      "actionCategory": "account",
      "actionLink": "https://example.com",
      "dateComponentsToCapture": "day-month",
      "icon": "text",
      "imageUrl": "https://example.com",
      "pointsPerText": "dollar",
      "promotion": {
        "promotionId": "123e4567-e89b-12d3-a456-426614174000",
        "title": "text",
        "description": "text",
        "type": "fixed-point",
        "value": 1,
        "icon": "text",
        "dateStart": "2025-11-08T01:42:16.514Z",
        "dateEnd": "2025-11-08T01:42:16.514Z",
        "appliesToEarningRules": [
          "text"
        ],
        "eligibleVipTiers": [
          "text"
        ]
      },
      "socialPageLink": "https://example.com",
      "title": "text",
      "reward": {
        "type": "fixed-amount",
        "amount": 1
      }
    }
  ]
}

Get Redemption Rules

get
Path parameters
subscriberIdstringRequired

The unique identifier for the store. Available on the Okendo integration settings page.

Query parameters
countryCodestringOptional

Country code for localisation

languageCodestringOptional

Language code for localisation

currencyCodestringOptional

Currency code for localisation

Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

A list of redemption rules

application/json
get
/stores/{subscriberId}/loyalty/redemption_rules
GET /v1/stores/{subscriberId}/loyalty/redemption_rules HTTP/1.1
Host: api.okendo.io
okendo-api-version: 2025-02-01
Accept: */*
200

A list of redemption rules

{
  "redemptionRules": [
    {
      "redemptionRuleId": "123e4567-e89b-12d3-a456-426614174000",
      "title": "text",
      "type": "free-product",
      "icon": "text",
      "imageUrl": "https://example.com",
      "reward": {
        "points": 1,
        "product": {
          "productId": "text",
          "name": "text",
          "imageUrl": "https://example.com",
          "url": "https://example.com",
          "price": "text",
          "currencyCode": "text"
        },
        "variants": [
          {
            "variantRemoteId": "text",
            "title": "text",
            "price": "text",
            "currencyCode": "text"
          }
        ]
      },
      "appliesToCollections": [
        {
          "collectionId": "text",
          "title": "text",
          "url": "https://example.com"
        }
      ],
      "expiresAfterDays": 1,
      "minimumPurchase": 1,
      "purchaseType": "single",
      "recurringCycleLimit": 1
    }
  ],
  "localisation": {
    "currency": {
      "code": "text",
      "exchangeRate": 1
    }
  }
}

Get VIP Program

get
Path parameters
subscriberIdstringRequired

The unique identifier for the store. Available on the Okendo integration settings page.

Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

The VIP program details

application/json
get
/stores/{subscriberId}/loyalty/vip_program
GET /v1/stores/{subscriberId}/loyalty/vip_program HTTP/1.1
Host: api.okendo.io
okendo-api-version: 2025-02-01
Accept: */*
200

The VIP program details

{
  "vipProgram": {
    "vipTiers": [
      {
        "vipTierId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "entryRequirement": {
          "spend": 1
        },
        "style": {
          "badge": {
            "type": "framed",
            "icon": "text",
            "color": "text",
            "frame": {
              "type": "bronze"
            },
            "svgUrl": "https://example.com"
          }
        },
        "customPerks": [
          "text"
        ],
        "earningRules": [
          {
            "earningRuleId": "123e4567-e89b-12d3-a456-426614174000",
            "action": "sign-up",
            "actionCategory": "account",
            "actionLink": "https://example.com",
            "dateComponentsToCapture": "day-month",
            "icon": "text",
            "imageUrl": "https://example.com",
            "pointsPerText": "dollar",
            "promotion": {
              "promotionId": "123e4567-e89b-12d3-a456-426614174000",
              "title": "text",
              "description": "text",
              "type": "fixed-point",
              "value": 1,
              "icon": "text",
              "dateStart": "2025-11-08T01:42:16.514Z",
              "dateEnd": "2025-11-08T01:42:16.514Z",
              "appliesToEarningRules": [
                "text"
              ],
              "eligibleVipTiers": [
                "text"
              ]
            },
            "socialPageLink": "https://example.com",
            "title": "text",
            "reward": {
              "type": "fixed-amount",
              "amount": 1
            }
          }
        ],
        "redemptionRules": [
          {
            "redemptionRuleId": "123e4567-e89b-12d3-a456-426614174000",
            "title": "text",
            "type": "free-product",
            "icon": "text",
            "imageUrl": "https://example.com",
            "reward": {
              "points": 1,
              "product": {
                "productId": "text",
                "name": "text",
                "imageUrl": "https://example.com",
                "url": "https://example.com",
                "price": "text",
                "currencyCode": "text"
              },
              "variants": [
                {
                  "variantRemoteId": "text",
                  "title": "text",
                  "price": "text",
                  "currencyCode": "text"
                }
              ]
            },
            "appliesToCollections": [
              {
                "collectionId": "text",
                "title": "text",
                "url": "https://example.com"
              }
            ],
            "expiresAfterDays": 1,
            "minimumPurchase": 1,
            "purchaseType": "single",
            "recurringCycleLimit": 1
          }
        ]
      }
    ]
  }
}

Get FAQ

get
Path parameters
subscriberIdstringRequired

The unique identifier for the store. Available on the Okendo integration settings page.

Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

A list of FAQ items

application/json
get
/stores/{subscriberId}/loyalty/faq
GET /v1/stores/{subscriberId}/loyalty/faq HTTP/1.1
Host: api.okendo.io
okendo-api-version: 2025-02-01
Accept: */*
200

A list of FAQ items

{
  "faqItems": [
    {
      "question": "text",
      "answer": "text"
    }
  ]
}

Get Legal Policies

get

Retrieve legal policies information including terms and conditions, privacy policy URLs, and policy text templates for the loyalty program

Path parameters
subscriberIdstringRequired

The unique identifier for the store. Available on the Okendo integration settings page.

Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

Legal policies information

application/json
get
/stores/{subscriberId}/loyalty/legal_policies
GET /v1/stores/{subscriberId}/loyalty/legal_policies HTTP/1.1
Host: api.okendo.io
okendo-api-version: 2025-02-01
Accept: */*
200

Legal policies information

{
  "acceptTermsAndJoinProgramButtonText": "Join & Agree",
  "policySentence": {
    "template": "By joining you agree to our {{ termsAndConditions }} and {{ privacyPolicy }}.",
    "html": "By joining you agree to our <a href=\"https://okendo.io/terms-conditions\" target=\"_blank\">Terms and Conditions</a> and <a href=\"https://okendo.io/privacy-policy\" target=\"_blank\">Privacy Policy</a>."
  },
  "privacyPolicyUrl": "https://okendo.io/privacy-policy",
  "termsAndConditionsUrl": "https://okendo.io/terms-conditions",
  "version": "1.0.0"
}

Login

post
Path parameters
subscriberIdstringRequired

The unique identifier for the store. Available on the Okendo integration settings page.

Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Body
one ofOptional
or
Responses
200

Login successful

application/json
post
/stores/{subscriberId}/loyalty/login
POST /v1/stores/{subscriberId}/loyalty/login HTTP/1.1
Host: api.okendo.io
okendo-api-version: 2025-02-01
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "customerAccessToken": "text"
}
200

Login successful

{
  "jwt": "text",
  "loyaltyCustomerDetails": {
    "balance": 1,
    "status": "enrolled",
    "vipTierId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Customer Authenticated

Get Customer Details

get

Retrieve detailed information about the authenticated loyalty customer

Authorizations
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

Customer details retrieved successfully

application/json
get
/loyalty/customer_details
GET /v1/loyalty/customer_details HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Accept: */*

{
  "loyaltyCustomer": {
    "email": "[email protected]",
    "dateEnrolled": "2025-11-08T01:42:16.514Z",
    "dateTierExpires": "2025-11-08T01:42:16.514Z",
    "fullName": "text",
    "avatarDynamicKey": "text",
    "status": "enrolled",
    "vipTierId": "123e4567-e89b-12d3-a456-426614174000",
    "isTierLocked": true,
    "minimumVipTierId": "123e4567-e89b-12d3-a456-426614174000",
    "points": {
      "balance": 1,
      "dateUpdated": "2025-11-08T01:42:16.514Z",
      "pending": 1,
      "spent": 1
    },
    "referralSender": {
      "referralSenderId": "123e4567-e89b-12d3-a456-426614174000",
      "shareableLinkUrl": "https://example.com"
    },
    "rewardsClaimed": 1,
    "birthday": {
      "day": 1,
      "month": 1,
      "year": 1
    }
  }
}

Activate (Enrol) Loyalty Customer

post

Enrol a customer into the loyalty program

Authorizations
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Body
enrollmentChannelstringRequired

The channel through which the customer is enrolling into the loyalty program

legalPoliciesVersionAcceptedstringRequired

Version of legal policies accepted by the customer. To fetch the legal policies to display and their version, call the GET /stores/{subscriberId}/loyalty/legal_policies endpoint.

Responses
200

Customer activated successfully

application/json
post
/loyalty/customer_activation
POST /v1/loyalty/customer_activation HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "enrollmentChannel": "text",
  "legalPoliciesVersionAccepted": "text"
}
{
  "loyaltyCustomer": {
    "dateEnrolled": "2025-11-08T01:42:16.514Z",
    "points": {
      "balance": 1,
      "dateUpdated": "2025-11-08T01:42:16.514Z",
      "pending": 1,
      "spent": 1
    },
    "rewardsClaimed": 1,
    "status": "enrolled",
    "vipTierId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Get Earning Rules For Customer

get

Retrieve earning rules for the authenticated customer, including completion status

Authorizations
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

Earning rules retrieved successfully

application/json
get
/loyalty/earning_rules
GET /v1/loyalty/earning_rules HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Accept: */*

{
  "earningRules": [
    {
      "earningRuleId": "123e4567-e89b-12d3-a456-426614174000",
      "action": "sign-up",
      "actionCategory": "account",
      "actionLink": "https://example.com",
      "dateComponentsToCapture": "day-month",
      "icon": "text",
      "imageUrl": "https://example.com",
      "pointsPerText": "dollar",
      "promotion": {
        "promotionId": "123e4567-e89b-12d3-a456-426614174000",
        "title": "text",
        "description": "text",
        "type": "fixed-point",
        "value": 1,
        "icon": "text",
        "dateStart": "2025-11-08T01:42:16.514Z",
        "dateEnd": "2025-11-08T01:42:16.514Z",
        "appliesToEarningRules": [
          "text"
        ],
        "eligibleVipTiers": [
          "text"
        ]
      },
      "socialPageLink": "https://example.com",
      "title": "text",
      "reward": {
        "type": "fixed-amount",
        "amount": 1
      },
      "isCompleted": true
    }
  ]
}

Trigger Social Earning Rule

post

Trigger a social earning rule to earn points for the authenticated customer

Authorizations
Path parameters
earningRuleIdstringRequired

The unique identifier for the earning rule to trigger

Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Body
objectOptional
Responses
200

Earning rule triggered successfully

application/json
post
/loyalty/earning_rules/{earningRuleId}/trigger
POST /v1/loyalty/earning_rules/{earningRuleId}/trigger HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
{
  "pointsEarned": 1
}

Update Customer Birthday

put

Updates the birthday for the given customer.

Authorizations
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Body
dayinteger · min: 1 · max: 31Required

The day of the month, from 1 to 31.

monthinteger · min: 1 · max: 12Required

The month of the year, from 1 to 12.

Responses
204

Successfully updated customer birthday.

No content
put
/loyalty/customer_birthday
PUT /v1/loyalty/customer_birthday HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "day": 1,
  "month": 1
}
No content

Get Redemption Rules For Customer

get

Retrieve redemption rules for the authenticated customer with localization support

Authorizations
Query parameters
languageCodestringOptional

Language code for localization

Example: en
countryCodestringOptional

Country code for localization

Example: us
currencyCodestringOptional

Currency code for localization

Example: USD
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

Redemption rules retrieved successfully

application/json
get
/loyalty/redemption_rules
GET /v1/loyalty/redemption_rules HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Accept: */*

{
  "redemptionRules": [
    {
      "redemptionRuleId": "123e4567-e89b-12d3-a456-426614174000",
      "title": "text",
      "type": "free-product",
      "icon": "text",
      "imageUrl": "https://example.com",
      "reward": {
        "points": 1,
        "product": {
          "productId": "text",
          "name": "text",
          "imageUrl": "https://example.com",
          "url": "https://example.com",
          "price": "text",
          "currencyCode": "text"
        },
        "variants": [
          {
            "variantRemoteId": "text",
            "title": "text",
            "price": "text",
            "currencyCode": "text"
          }
        ]
      },
      "appliesToCollections": [
        {
          "collectionId": "text",
          "title": "text",
          "url": "https://example.com"
        }
      ],
      "expiresAfterDays": 1,
      "minimumPurchase": 1,
      "purchaseType": "single",
      "recurringCycleLimit": 1
    }
  ],
  "localisation": {
    "currency": {
      "code": "USD",
      "exchangeRate": 1
    }
  }
}

Redeem Points

post

Redeem loyalty points for rewards using a redemption rule

Authorizations
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Body
redemptionRuleIdstring · uuidRequired

The unique identifier of the redemption rule to use

Responses
200

Points redeemed successfully

application/json
post
/loyalty/redemptions
POST /v1/loyalty/redemptions HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Content-Type: application/json
Accept: */*
Content-Length: 166

{
  "redemptionRuleId": "123e4567-e89b-12d3-a456-426614174000",
  "variableValue": {
    "points": 1,
    "value": 1
  },
  "localisation": {
    "currencyCode": "USD",
    "clientValue": 1,
    "locale": "en"
  }
}
{
  "reward": {
    "rewardType": "coupon",
    "result": {
      "success": true,
      "data": {
        "code": "text"
      }
    }
  },
  "customerPoints": {
    "balance": 1,
    "dateUpdated": "2025-11-08T01:42:16.514Z",
    "pending": 1,
    "spent": 1
  }
}

Get Loyalty Transactions

get

Retrieve paginated list of loyalty transactions for the authenticated customer

Authorizations
Query parameters
limitinteger · min: 1 · max: 100Optional

Maximum number of transactions to return

Default: 25
lastEvaluatedstringOptional

Token for pagination to get the next page of results

orderBystring · enumOptional

Field and direction to order results by

Default: date descPossible values:
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

Loyalty transactions retrieved successfully

application/json
get
/loyalty/transactions
GET /v1/loyalty/transactions HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Accept: */*

{
  "transactions": [
    {
      "loyaltyTransactionId": "123e4567-e89b-12d3-a456-426614174000",
      "amount": 1,
      "notificationText": "text",
      "date": "2025-11-08T01:42:16.514Z",
      "status": "complete",
      "type": "earn",
      "bonusPoints": 1
    }
  ],
  "nextUrl": "https://example.com"
}

Get Customer Spend

get

Retrieve the customer's spending amount within the current VIP tier eligibility period

Authorizations
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

Customer spend retrieved successfully

application/json
get
/loyalty/customer_spend
GET /v1/loyalty/customer_spend HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Accept: */*

{
  "customerSpend": 1,
  "dateFrom": "2025-11-08T01:42:16.514Z"
}

Loyalty x Referrals

Before making a referral, the customer will need to be registered as a "referral sender". See Referrals.

Send Referral Request

post

Sends a referral request to the specified email address

Authorizations
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Body
emailstring · emailRequired

The email of the person being referred to the loyalty program

referralSenderIdstring · uuidRequired

The Referral Sender ID of the loyalty member. This can be found in the response from the Get Customer Details authenticated endpoint.

Responses
204

Successfully sent referral request.

No content
post
/loyalty/referrals
POST /v1/loyalty/referrals HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "email": "[email protected]",
  "referralSenderId": "123e4567-e89b-12d3-a456-426614174000"
}
No content

Get Referral History

get

Retrieves the referral history for the authenticated customer

Authorizations
Query parameters
lastEvaluatedstringOptional

Token for pagination to get the next page of results

Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

Referral history retrieved successfully

application/json
get
/loyalty/referrals
GET /v1/loyalty/referrals HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Accept: */*
200

Referral history retrieved successfully

{
  "referrals": [
    {
      "dateCreated": "text",
      "recipient": {
        "email": "[email protected]"
      },
      "status": "complete"
    }
  ],
  "nextUrl": "https://example.com"
}

Get Referral Count

get

Retrieves the number of referrals by an authenticated customer

Authorizations
Header parameters
okendo-api-versionstring · enumRequired

API version header

Possible values:
okendo-partner-idstringOptional
Responses
200

Referral count retrieved successfully

application/json
get
/loyalty/referral_aggregate
GET /v1/loyalty/referral_aggregate HTTP/1.1
Host: api.okendo.io
Authorization: Bearer YOUR_SECRET_TOKEN
okendo-api-version: 2025-02-01
Accept: */*
200

Referral count retrieved successfully

{
  "referralsTotal": 1
}
PreviousReviewsNextReferrals

Last updated