# Installing Loyalty on Headless Instances
### Overview
For stores specifically running Shopify Hydrogen 2, please [look here](https://docs.okendo.io/okendo-shopify-hydrogen-support) for further support.
This guide explains how to integrate Okendo Loyalty into your headless Shopify store. The implementation requires 2-3 code snippets depending on your needs.
**Prerequisites:**
* Active Okendo Loyalty subscription
* Headless Shopify storefront
* Customer authentication implemented (via Customer Account API or Storefront API)
**Quick Links:**
* [Required: Loyalty Settings](https://untitled+.vscode-resource.vscode-cdn.net/Untitled-1#1-loyalty-settings-metafield)
* [Required: Customer Authentication](https://untitled+.vscode-resource.vscode-cdn.net/Untitled-1#2-customer-access-token-script-tag)
* [Optional: Additional Widgets](https://untitled+.vscode-resource.vscode-cdn.net/Untitled-1#3-loyalty-landing-page--other-widgets-optional)
### Implementation Steps
To implement Okendo Loyalty, you will need to render two or three snippets on your store:
### 1. Loyalty Settings Metafield
Located in your Shop Metafields, under the `okendo` namespace and `LoyaltySettings` key, you will find a snippet containing 2 script tags (one for the loyalty widget settings, and one for the initialisation script).
**Purpose:** Loads the Loyalty App with your customized settings and displays the Floating Widget.
**Implementation:** Render the metafield content in the `` section of your store pages.
```liquid
{{ shop.metafields.okendo.LoyaltySettings }}
```
```javascript
// GraphQL query example (for Hydrogen/Remix)
query metafields {
shop {
metafield(namespace: "okendo", key: "LoyaltySettings") {
value
}
}
}
```
The metafield contains 2 script tags:
1. Widget settings configuration
2. Initialization script
**Result:** The Floating Widget will appear automatically (unless disabled in Okendo Admin settings).
> **⚠️ Important:** This must be rendered on every page where you want loyalty features to appear.
### 2. Customer Access Token Script Tag
**Purpose:** Authenticates the customer to display personalized loyalty information.
**Required for:**
* Logged-in customer experience
* Points balance display
* Rewards redemption
* Member-specific content
Choose **one** implementation method based on your authentication approach:
#### Option A: Customer Account API (Recommended for New Hydrogen Stores)
**When to use:** Your store uses the [Customer Account API](https://shopify.dev/docs/api/customer/2025-01#authentication) for authentication (Shopify's newer authentication method).
**Implementation:**
```html
```
**Example (React/Hydrogen):**
```tsx
// In your root layout or auth context
export function LoyaltyAuth({accessToken}: {accessToken: string}) {
return (
);
}
```
**Where to get the token:**
* The `access_token` is obtained during your login flow from the Customer Account API
* Typically stored in session/cookies after the OAuth redirect
* Usually already available since it's required for Customer Account API requests
**Token Lifecycle:**
* ✅ **Must** implement automatic token refresh when it expires
* ✅ Remove or update the script tag when customer logs out
* ✅ Check token expiry before rendering
> **💡 Tip:** Most Hydrogen projects already manage this token in an auth context or session.
#### Option B: Storefront API (Legacy Authentication)
**When to use:** Your store uses the [Storefront API](https://shopify.dev/docs/api/storefront/2025-01/mutations/customerAccessTokenCreate) for authentication (older method).
**Implementation:**
```html
```
**Example (React):**
```tsx
export function LoyaltyAuthStorefront({
customerToken,
storefrontToken,
}: {
customerToken: string;
storefrontToken: string;
}) {
return (
);
}
```
**Required Token #1: `storefrontCustomerAccessToken`**
**Source:** Returned from the `customerAccessTokenCreate` mutation.
```graphql
mutation {
customerAccessTokenCreate(input: {
email: "customer@example.com"
password: "password"
}) {
customerAccessToken {
accessToken # ← Use this value
expiresAt
}
}
}
```
**What you need:** The `accessToken` string from the response.
**Required Token #2: `storefrontAccessToken`**
**Source:** Your Storefront API public access token.
**Where to find it:**
1. Go to `Shopify Admin → Sales channels`
2. Click on your headless storefront
3. Navigate to `Storefront API → Public access token`
4. Copy the token value
**Environment variable:** Usually stored as `PUBLIC_STOREFRONT_API_TOKEN` and used for your `X-Shopify-Storefront-Access-Token` header.
> **💡 Tip:** You're likely already using this token for all Storefront API requests in your project.
### 3. Loyalty Landing Page / Other Widgets (Optional)
#### Loyalty Page
To display the Loyalty Page Widget on one of your store pages (e.g. a dedicated loyalty page) all you need to do is render the snippet below:
```
```
When the app initialisation script runs, it will detect this `div` and render the Loyalty Page widget there.
Other valid snippets for rendering individual modules from the Loyalty Page Widget are listed below:
| Module | Snippet |
| -------------- | ----------------------------------------------- |
| Member Profile | `` |
| Redeem Rewards | `` |
| Earn Rewards | `` |
| VIP Tiers | `` |
| Achievements | `` |
| Refer A Friend | `` |
| FAQ | `` |
#### Cart Banner Widget
Display a banner showing points information at the top of your Cart page or cart drawer.
**Use cases:**
* Cart page header
* Cart drawer header
* Checkout flow
**Implementation:**
```html
```
#### Points Preview Widget
We also offer a Points Preview widget for products, which can help inform customers how many points they will receive upon purchasing a specific product (usually displayed under the price on the Product Display Page, but also works on product carousels, etc).
This div also accepts other data attributes which will help it identify the correct product, and can also be used to help style it for different use cases on different pages:
| Attribute | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| data-oke-loyalty-points-preview-id | We will use this Product ID to calculate the reward. If not supplied then we will try to find it elsewhere on the page. |
| data-oke-loyalty-variant-id | The Variant ID of the product for the calculation. If not supplied then we will try to find it elsewhere on the page or else use the default for the product. |
| data-oke-loyalty-selling-plan-id | If you offer subscription options for the product then you can use this to tell us which one is currently selected. If not supplied then we will try to find it elsewhere on the page or else use the default for the product. |
| data-oke-loyalty-background | A Hex Color Code (e.g. `#FFFFFF`) for the background of the widget |
| data-oke-loyalty-icon | The name of the Icon to be displayed in the widget. Accepts most Font Awesome icon names |
| data-oke-loyalty-target | If you are using this widget in the cart, please set this to `"cart"`. If you are using this widget in a cart drawer, please set this to `"cart-drawer"`. This is purely for analytics purposes. |
As a simple example, your snippet may look something like this:
```html
```
**Complete example with optional attributes:**
```html
```
### Troubleshooting
#### Widget Not Appearing
**Check:**
1. ✅ Loyalty Settings metafield is rendered in `` as HTML and not text (you may be required to use `dangerouslySetInnerHTML`)
2. ✅ Script tags are loading without errors (check browser console)
3. ✅ Customer access token is valid and not expired
4. ✅ Floating Widget is enabled in Okendo Admin settings
#### Customer Not Logged In to Loyalty
**Check:**
1. ✅ Customer access token script tag is present on the page
2. ✅ Token is valid (not expired)
3. ✅ Correct script ID is used (`oke-loyalty-customer-access-token` or `oke-loyalty-storefront-customer-access-token`)
4. ✅ JSON format is valid (use a JSON validator)
#### Points Not Showing on Products
**Check:**
1. ✅ Correct product ID is being passed to `data-oke-loyalty-points-preview-id`
2. ✅ Product exists in your Shopify store
3. ✅ Points earning rules are configured in Okendo Admin
#### Console Errors
Common errors and solutions:
* **"Cannot find metafield"**: Ensure Loyalty is enabled in Okendo Admin
* **"Invalid token"**: Check token format and expiry
* **"Widget initialization failed"**: Verify settings script is loaded and formatted correctly
### Testing Checklist
Before going live, verify:
* Floating Widget appears on all pages
* Customer can log in to loyalty widget when authenticated
* Points balance displays correctly for logged-in customers
* Products show points preview on product pages
* Loyalty page displays all modules correctly
* Cart banner shows points information
* Widget styling matches your brand
* All widgets work on mobile devices
* Token refresh works correctly when token expires
### Additional Resources
* [Okendo Admin Dashboard](https://reviews.okendo.io/admin)
* [Shopify Customer Account API Docs](https://shopify.dev/docs/api/customer/2025-01)
* [Shopify Storefront API Docs](https://shopify.dev/docs/api/storefront/2025-01)
* Need help? Contact Okendo Support
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.okendo.io/on-site/advanced-widget-installs/installing-loyalty-on-headless-instances.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.