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 route, 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
   Add a token route that signs the customer token (5 min)

   A small resource route (for example /api/loyalty-token) checks the Customer Account session and returns HMAC-SHA256 over customerId.timestamp. Tokens are valid for 60 seconds, so the SDK calls this route itself through getCustomerToken whenever it needs a fresh one. Copy-paste route 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, a getCustomerToken function, 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 and signing secret generated from the Anchor Loyalty dashboard
• checkA backend endpoint (server route or serverless function) that signs customer tokens for logged-in customers

#Authentication

Generating a key gives you two credentials, shown together and only once: the public API key (ak_...), passed as apiKey to the SDK, and the private signing secret (sk_...), which stays on your server. Never put the signing secret in browser code or in a VITE_, NEXT_PUBLIC_ or PUBLIC_ variable.

1. 1Generate the credentials, on the Anchor Loyalty app home page, in the Headless SDK section. Copy both values; neither is shown again.
2. 2Lost the signing secret?, click "Regenerate Key". You get a new API key and a new signing secret; the old API key stops working, so update your storefront too.
3. 3Include apiKey in your SDK initialization, call (see Quick Start below).
4. 4Revoke, the key from the dashboard if it is compromised. A new key can be generated immediately.
5. 5Sign customer tokens on your backend, with HMAC-SHA256 and your signing secret, and hand them to the SDK through getCustomerToken. Required for every request about a logged-in customer (reads and redemptions). See Security, Customer Token.

#Security, Customer Token

The API key authenticates your store, but it's visible in your page source. So every request for a customer's data (points, codes, redemptions) must also carry a customer token, an HMAC-signed proof that your backend verified the customer. Without it, /api/customer, /api/codes and /api/redeem return 403 for a logged-in customer. Guests need no token.

#How it works

1. 1Customer logs in, on your storefront.
2. 2Your backend exposes a token route, that checks the session and returns a token signed with HMAC-SHA256 and your signing secret (never send the signing secret to the browser).
3. 3The SDK calls that route, through the getCustomerToken function you pass to init(), and sends the token in the X-Anchor-Customer-Token header.
4. 4Anchor verifies the signature, and the timestamp before processing any request.

#Signing the token (backend)

import { createHmac } from 'node:crypto';

export function signCustomerToken(customerId, signingSecret) {
  const ts = Math.floor(Date.now() / 1000);
  const hmac = createHmac('sha256', signingSecret).update(`${customerId}.${ts}`).digest('hex');
  return `${customerId}.${ts}.${hmac}`;
}

On Hydrogen / Oxygen and other edge runtimes there is no node:crypto; use Web Crypto:

export async function signCustomerToken(customerId, signingSecret) {
  const ts = Math.floor(Date.now() / 1000);
  const key = await crypto.subtle.importKey(
    'raw', new TextEncoder().encode(signingSecret),
    { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
  );
  const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${customerId}.${ts}`));
  const hex = [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, '0')).join('');
  return `${customerId}.${ts}.${hex}`;
}

#The token route

Expose an endpoint on your own backend, for example GET /api/loyalty-token, that checks the logged-in session and returns a freshly signed token as plain text. In Hydrogen that is a resource route:

import { signCustomerToken } from '~/lib/loyalty-token'; // the Web Crypto helper above

export async function loader({ context }: LoaderFunctionArgs) {
  const isLoggedIn = await context.customerAccount.isLoggedIn();
  if (!isLoggedIn) {
    return new Response('', { status: 401 });
  }

  const { data } = await context.customerAccount.query(`
    query { customer { id } }
  `);
  const customerId = data.customer.id.replace('gid://shopify/Customer/', '');
  const token = await signCustomerToken(customerId, context.env.ANCHOR_SIGNING_SECRET);

  return new Response(token, { headers: { 'Cache-Control': 'no-store' } });
}

#Giving the token to the SDK

Pass a function that calls your route. The SDK calls it when it needs a token, not on every request:

AnchorLoyaltySDK.init({
  apiKey: 'YOUR_API_KEY',
  customerId: '12345',
  getCustomerToken: () =>
    fetch('/api/loyalty-token', { credentials: 'include' }).then((r) => r.text()),
});

#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); null for guests
    getCustomerToken: () =>
      fetch('/api/loyalty-token', { credentials: 'include' }).then((r) => r.text()),
  });
</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',
    getCustomerToken: () =>
      fetch('/api/loyalty-token', { credentials: 'include' }).then((r) => r.text()),
  });
</script>

#Hydrogen / React

Create a LoyaltyWidget component that loads the SDK and initializes it with the authenticated customer. Store the API key in PUBLIC_ANCHOR_LOYALTY_API_KEY; the signing secret is not public, keep it in a server-only variable and use it only inside the token route.

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,
        customerName: customer?.firstName || '',
        locale: 'en',
        // Resource route on your storefront that signs a token for the
        // logged-in customer (see "Security, Customer Token" above).
        getCustomerToken: () =>
          fetch('/api/loyalty-token', { credentials: 'include' }).then((r) => r.text()),
      });
    };
    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 }: {
  customerId: string | null;
  customerName?: 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,
          // A Route Handler (app/api/loyalty-token/route.ts) that signs a
          // token for the logged-in customer with the Node.js helper above.
          getCustomerToken: () =>
            fetch('/api/loyalty-token', { credentials: 'include' }).then((r) => r.text()),
        });
      }}
    />
  );
}

#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 GraphQL API)

query CustomerByEmail($query: String!) {
  customers(first: 1, query: $query) {
    nodes { id }
  }
}

With variables { "query": "email:user@example.com" }. Requires the read_customers scope. The id is a GID; extract the numeric part with id.split('/').pop().

#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',
});

// After logout:
AnchorLoyaltySDK.update({ customerId: null });

#Architecture

Your Headless Storefront                    Anchor Loyalty API
(Hydrogen, Next.js, etc.)                   (anchorloyalty.app)
        |                                            |
        |  1. Load SDK                               |
        |  GET /api/sdk.js?key=ak_xxx                |
        |------------------------------------------->|
        |  <-- ~242 KB JS (~70 KB gzipped)           |
        |                                            |
        |  2. API calls (automatic)                  |
        |  GET /api/customer                         |
        |  Header: X-Anchor-Api-Key: ak_xxx          |
        |  Header: X-Anchor-Customer-Token: <token>  |
        |  Params: ?shop=...&customer_id=...         |
        |------------------------------------------->|
        |  <-- JSON (points, rewards, tier, etc.)    |
        |                                            |
        |  3. Redeem reward                          |
        |  POST /api/redeem                          |
        |  Header: X-Anchor-Api-Key: ak_xxx          |
        |  Header: X-Anchor-Customer-Token: <token>  |
        |------------------------------------------->|
        |  <-- 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