Headless SDK

#Implement a loyalty program in Hydrogen: 30-minute quickstart

Adding a loyalty program to a Shopify Hydrogen storefront takes about 30 minutes with an API-first provider: roughly 10 minutes for environment variables and a signed-token loader, 15 minutes for the widget component and route wiring, and the rest for testing the logged-in and logged-out states.

The reason it is a 30-minute job rather than a multi-day one comes down to three architecture decisions. Get these right and the implementation is wiring; get them wrong and you end up rebuilding a loyalty UI from scratch.

The four steps

1. 1
   Set your environment variables (5 min)

   Add PUBLIC_ANCHOR_LOYALTY_API_KEY and ANCHOR_SIGNING_SECRET to your Hydrogen environment. The API key is public and travels to the browser; the signing secret never leaves the server.

2. 2
   Generate the signed customer token in your loader (5 min)

   HMAC-SHA256 over customerId.timestamp, returned from the loader alongside the rest of your route data. Tokens expire after five minutes, so regenerate on each page load. Copy-paste loader code is in Security.

3. 3
   Mount the widget component (15 min)

   A small client component loads the SDK and calls AnchorLoyaltySDK.init() with the customer ID, the signed token, and your locale. Render it once in your root layout, not per route. Full component in Quick Start, and the ID-extraction detail in Getting the Customer ID.

4. 4
   Test both states before you ship (5 min)

   Logged out: the widget should show the guest prompt and no balance. Logged in: balance renders and a redemption returns a discount code. Then confirm a redemption attempt with a tampered or expired token returns 403. If it succeeds, your token is not actually being verified.

#Overview

The Anchor Loyalty Headless SDK allows you to add the loyalty widget to any storefront that doesn't use Shopify's Online Store channel: including Hydrogen, Next.js, Gatsby, Vue, or any custom frontend.

The SDK renders the exact same widget as the embedded version: same UI, same features, lightweight footprint. No custom UI development required.

• checkAnchor Loyalty app installed on your Shopify store
• checkPRO plan subscription
• checkAPI key generated from the Anchor Loyalty dashboard

#Authentication

All headless SDK API calls require an API key.

1. 1Generate your API key, from the Anchor Loyalty dashboard (Headless SDK section).
2. 2Save the key securely, it is displayed only once. If you lose it, use "Regenerate Key" to create a new one (this invalidates the old key).
3. 3Include apiKey in your SDK initialization, call (see Quick Start below).
4. 4Revoke and regenerate, if a key is compromised, revoke it from the dashboard. A new key can be generated immediately.
5. 5Generate customer tokens, Your backend must sign a customer token using HMAC-SHA256 with your signing secret. The signing secret is shown alongside the API key when generated, store it securely in your backend environment variables. Required for all authenticated requests (reads and redemptions). See Security section.

#Security, Customer Token

The API key authenticates your store, but it's visible in your page source. To prevent unauthorized access, all authenticated headless requests require a customer token, an HMAC-signed proof that your backend verified the customer.

#How it works

1. 1Customer logs in, on your storefront.
2. 2Your backend generates a signed token, using HMAC-SHA256 with your signing secret (never send the signing secret to the browser).
3. 3Frontend passes the token, to the SDK via the customerToken parameter.
4. 4Anchor verifies the signature, before processing any request.

#Generating the token (backend)

const crypto = require('crypto');
const ts = Math.floor(Date.now() / 1000);
const hmac = crypto.createHmac('sha256', SIGNING_SECRET)
  .update(`${customerId}.${ts}`).digest('hex');
const customerToken = `${customerId}.${ts}.${hmac}`;

// In a Hydrogen loader (e.g., app/routes/($locale)._index.tsx)
import crypto from 'crypto';

export async function loader({ context }: LoaderFunctionArgs) {
  const isLoggedIn = await context.customerAccount.isLoggedIn();
  let customerToken = null;

  if (isLoggedIn) {
    const { data } = await context.customerAccount.query(`
      query { customer { id } }
    `);
    const customerId = data.customer.id.replace('gid://shopify/Customer/', '');
    const ts = Math.floor(Date.now() / 1000);
    const hmac = crypto.createHmac('sha256', context.env.ANCHOR_SIGNING_SECRET)
      .update(`${customerId}.${ts}`).digest('hex');
    customerToken = `${customerId}.${ts}.${hmac}`;
  }

  return json({ customerToken });
}

#When is it required?

#Quick Start

#HTML / Custom Storefront

Recommended, only API key needed:

<script src="https://anchorloyalty.app/api/sdk.js?key=YOUR_API_KEY"></script>
<script>
  AnchorLoyaltySDK.init({
    apiKey: 'YOUR_API_KEY',
    customerId: '12345', // Shopify Customer ID (numeric)
    customerToken: 'TOKEN_FROM_YOUR_BACKEND', // HMAC-signed token
  });
</script>

Alternative, with explicit shop domain:

<script src="https://anchorloyalty.app/api/sdk.js?shop=YOUR-STORE.myshopify.com"></script>
<script>
  AnchorLoyaltySDK.init({
    shop: 'YOUR-STORE.myshopify.com',
    apiKey: 'YOUR_API_KEY',
    customerId: '12345',
  });
</script>

#Hydrogen / React

Create a LoyaltyWidget component that loads the SDK and initializes it with the authenticated customer:

import { useEffect } from 'react';
import { useCustomer } from '~/hooks/useCustomer';

const API_KEY = import.meta.env.PUBLIC_ANCHOR_LOYALTY_API_KEY;

export function LoyaltyWidget() {
  const customer = useCustomer();

  useEffect(() => {
    if (!API_KEY) {
      console.error('Missing PUBLIC_ANCHOR_LOYALTY_API_KEY env var');
      return;
    }
    const script = document.createElement('script');
    script.src = `https://anchorloyalty.app/api/sdk.js?key=${API_KEY}`;
    script.async = true;
    script.onload = () => {
      window.AnchorLoyaltySDK?.init({
        apiKey: API_KEY,
        customerId: customer?.id?.replace('gid://shopify/Customer/', '') || null,
        customerToken: customerToken, // Pass token from your backend
        customerName: customer?.firstName || '',
        locale: 'en',
      });
    };
    document.body.appendChild(script);

    return () => {
      window.AnchorLoyaltySDK?.destroy();
      script.remove();
    };
  }, [customer]);

  return null;
}

#Next.js

For Next.js, use the built-in next/script component with the onReady callback. This ensures the SDK re-initializes on SPA route transitions:

'use client';
import Script from 'next/script';

const API_KEY = process.env.NEXT_PUBLIC_ANCHOR_LOYALTY_API_KEY;

export function LoyaltyWidget({ customerId, customerName, customerToken }: {
  customerId: string | null;
  customerName?: string;
  customerToken?: string;
}) {
  if (!API_KEY) {
    console.error('Missing NEXT_PUBLIC_ANCHOR_LOYALTY_API_KEY env var');
    return null;
  }
  return (
    <Script
      src={`https://anchorloyalty.app/api/sdk.js?key=${API_KEY}`}
      strategy="lazyOnload"
      onReady={() => {
        window.AnchorLoyaltySDK?.init({
          apiKey: API_KEY,
          customerId,
          customerName,
          customerToken,
        });
      }}
    />
  );
}

#Getting the Customer ID

The customerId must be the Shopify numeric Customer ID (not the GID).

#From Hydrogen (Customer Account API)

// In a Hydrogen loader:
const isLoggedIn = await context.customerAccount.isLoggedIn();
if (isLoggedIn) {
  const { data } = await context.customerAccount.query(`
    query { customer { id firstName lastName } }
  `);
  // data.customer.id = "gid://shopify/Customer/12345"
  const numericId = data.customer.id.replace('gid://shopify/Customer/', '');
  // numericId = "12345"
}

#From Storefront API

query {
  customer(customerAccessToken: "TOKEN") {
    id  # Returns "gid://shopify/Customer/12345"
  }
}

Extract the numeric part: id.split('/').pop() → "12345"

#From Custom Backend (Admin API)

GET /admin/api/2026-01/customers.json?email=user@example.com

Use the id field from the response (already numeric).

#Guest Users (Not Logged In)

Pass null or omit customerId:

AnchorLoyaltySDK.init({
  apiKey: 'YOUR_API_KEY',
  customerId: null, // Guest mode, shows sign-in prompt
});

#All Parameters

#Locale Support

32 built-in locales, set locale to auto-select:

AnchorLoyaltySDK.init({ apiKey: '...', locale: 'de' }); // Deutsch

Override individual keys:

AnchorLoyaltySDK.init({
  apiKey: '...',
  locale: 'fr',
  translations: { title: 'Mon Programme Fidélité' },
});

#Methods

// After user logs in:
AnchorLoyaltySDK.update({
  customerId: '12345',
  customerName: 'Jane',
});

#Architecture

Your Headless Storefront                    Anchor Loyalty API
(Hydrogen, Next.js, etc.)                   (anchorloyalty.app)
        |                                            |
        |  1. Load SDK                               |
        |  GET /api/sdk.js?key=ak_xxx                |
        |------------------------------------------->|
        |  <-- JS (widget + CSS + 32 locales)        |
        |                                            |
        |  2. Fetch customer data (automatic)        |
        |  GET /api/customer                         |
        |------------------------------------------->|
        |  <-- JSON (points, rewards, tier, etc.)    |
        |                                            |
        |  3. Redeem reward                          |
        |  POST /api/redeem                          |
        |------------------------------------------->|
        |  <-- JSON (discount code)                  |
        |                                            |
        |  4. Redeem reward (with customer token)    |
        |  POST /api/redeem                          |
        |  Headers: X-Anchor-Customer-Token:         |
        |    {customerId}.{ts}.{hmac}                |
        |------------------------------------------->|
        |  <-- JSON (discount code)                  |

#Troubleshooting

Ready to add loyalty to your headless store?

Install Anchor, upgrade to Pro, and drop the SDK into your storefront. Full widget experience in minutes.

Install AnchorView Pro Plan