codeDeveloper Docs

Headless SDK

Add the full Anchor loyalty widget to any headless storefront — Hydrogen, Next.js, Gatsby, Vue, or custom builds.

widgetsFull widget experience

memoryLightweight footprint

deployed_codeFramework-agnostic

workspace_premiumThe Headless SDK is available on the Pro plan ($39.99/mo)

#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.

infoHow it works

All communication between the SDK and Anchor is handled securely through Shopify's platform. You only need to provide your shop domain during initialization — the SDK takes care of the rest.

#Requirements

checkAnchor Loyalty app installed on your Shopify store
checkPRO plan subscription
checkHeadless or Hydrogen sales channel configured

#Authentication

All headless SDK API calls require an API key for authentication.

1Generate your API key — from the Anchor Loyalty dashboard under Settings > Headless / API.
2Save the key securely — it is displayed only once at the time of creation. If you lose it, you will need to generate a new one.
3Include apiKey in your SDK initialization — call (see Quick Start examples below).
4Revoke and regenerate — if a key is compromised or no longer needed, you can revoke it and generate a new one from the same dashboard page. Revoking a key immediately invalidates it.

descriptionAuthentication exampleJS

AnchorLoyaltySDK.init({
  shop: 'YOUR-STORE.myshopify.com',
  apiKey: 'your-api-key-here',
  customerId: '12345',
});

#Quick Start

#HTML / Custom Storefront

Add the SDK script tag and initialize with your store domain and customer ID:

descriptionindex.htmlHTML

<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-here',
    customerId: '12345', // Shopify Customer ID
    primaryColor: '#4A56E2',
  });
</script>

#Hydrogen / React

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

descriptionLoyaltyWidget.tsxTSX

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

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

  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://anchorloyalty.app/api/sdk.js?shop=YOUR-STORE.myshopify.com';
    script.async = true;
    script.onload = () => {
      window.AnchorLoyaltySDK?.init({
        shop: 'YOUR-STORE.myshopify.com',
        apiKey: 'your-api-key-here',
        customerId: customer?.id?.replace('gid://shopify/Customer/', '') || null,
        customerName: customer?.firstName || '',
        locale: 'en',
      });
    };
    document.body.appendChild(script);

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

  return null;
}

#Next.js

For Next.js, use a client component with 'use client':

descriptionLoyaltyWidget.tsxTSX

'use client';
import { useEffect } from 'react';

export function LoyaltyWidget({ customerId, customerName }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://anchorloyalty.app/api/sdk.js?shop=YOUR-STORE.myshopify.com';
    script.async = true;
    script.onload = () => {
      window.AnchorLoyaltySDK?.init({
        shop: 'YOUR-STORE.myshopify.com',
        apiKey: 'your-api-key-here',
        customerId,
        customerName,
      });
    };
    document.body.appendChild(script);

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

  return null;
}

#Getting the Customer ID

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

#From Hydrogen

descriptionHydrogen Customer QueryTSX

// In your Hydrogen app, query the Customer Account API:
const customer = await context.customerAccount.query(CUSTOMER_QUERY);
// The ID looks like: "gid://shopify/Customer/12345"
// Extract the numeric part:
const customerId = customer.id.replace('gid://shopify/Customer/', '');

#From Storefront API

descriptionStorefront API QueryGraphQL

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

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

#From Custom Backend

If your backend has Shopify Admin API access:

descriptionAdmin APIHTTP

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

Use the id field from the response.

#Guest Users (Not Logged In)

Pass null or omit customerId:

descriptionGuest ModeJS

AnchorLoyaltySDK.init({
  shop: 'YOUR-STORE.myshopify.com',
  customerId: null, // Guest mode — shows sign-in prompt
});

#All Parameters

Parameter	Type	Default	Description
shop	string	required	Your Shopify store domain (e.g., store.myshopify.com)
apiKey	string	required	API key from your Anchor dashboard (Settings > Headless / API)
customerId	string \| null	null	Shopify Customer ID (numeric). null = guest mode
customerName	string	''	Customer's first name for welcome message
locale	string	'en'	Language code. The SDK includes all 33 locales.
position	string	'bottom-right'	Widget position: 'bottom-right' or 'bottom-left'
primaryColor	string	'#4A56E2'	Primary brand color (hex)
backgroundColor	string	'#FFFFFF'	Widget background color
textColor	string	'#1F2937'	Widget text color
launcherStyle	string	'bubble'	Launcher style: 'bubble', 'bubble-text', 'icon-only', 'pill', 'square'
launcherGradient	string	'solid'	Gradient: 'solid', 'sunset', 'ocean', 'forest', 'candy', 'midnight'
launcherShadow	string	'medium'	Shadow: 'none', 'subtle', 'medium', 'strong', 'glow'
launcherAnimation	string	'pulse'	Animation: 'none', 'pulse', 'bounce', 'shake', 'glow'
launcherTextType	string	'static'	'static' shows 'Rewards', 'dynamic' shows points balance
animationDelay	number	5	Seconds before first animation plays
animationRepeat	number	30	Seconds between animation repeats (0 = no repeat)
animateOnScroll	boolean	true	Trigger animation when user scrolls 25% down
bannerImage	string	''	URL to hero banner image
bannerLink	string	''	URL the banner links to
bannerLinkNewTab	boolean	false	Open banner link in new tab
showRewards	boolean	true	Show rewards tab
showReferral	boolean	true	Show referral tab
showGuestMessage	boolean	true	Show sign-in prompt for guests
accountUrl	string	'/account'	"View Account" link destination
loginUrl	string	'/account/login'	"Sign In" link for guests
registerUrl	string	'/account/register'	"Create Account" link for guests
translations	object	{}	Override any default translation key

#Locale Support

The SDK embeds translations for all 33 supported locales. Set the locale parameter to auto-select the right language:

descriptionLocale exampleJS

AnchorLoyaltySDK.init({
  shop: 'store.myshopify.com',
  locale: 'de', // German translations auto-applied
});

Supported locales

arcsdadeelenesfifrfr-CAhehihuiditjakomsnlnoplpt-BRpt-PTrorusvthtrukvizh-CNzh-TW

You can also override individual keys on top of the locale translations:

descriptionOverride specific keysJS

AnchorLoyaltySDK.init({
  shop: 'store.myshopify.com',
  locale: 'fr',
  translations: {
    title: 'Mon Programme Fidélité', // Override just this key
  },
});

#Methods

AnchorLoyaltySDK.init(options)

Initialize the widget. Call once after the script loads.

AnchorLoyaltySDK.destroy()

Remove the widget completely. Cleans up:

- Widget DOM element
- Injected <style> tag (CSS)
- Injected <script> tag (widget JS)
- window.anchorLoyaltyConfig, window.anchorLoyaltyTranslations, window.anchorLoyalty globals

Safe for SPA route transitions — call on unmount/cleanup.

AnchorLoyaltySDK.update(newOptions)

Update options and re-initialize (e.g., after login/logout).

descriptionExample: Update after loginJS

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

#Custom Translations

Override any translation key to match your brand voice or locale:

descriptionCustom TranslationsJS

AnchorLoyaltySDK.init({
  shop: 'store.myshopify.com',
  translations: {
    title: 'Mes Récompenses',
    points: 'points',
    tab_rewards: 'Récompenses',
    tab_earn: 'Gagner',
    tab_activity: 'Activité',
    tab_referral: 'Parrainer',
    view_account: 'Voir le compte',
    // ... any key from the default translations
  },
});

The SDK includes 33 built-in languages. Custom translations override these defaults.

#Troubleshooting

Issue	Solution
SDK returns 403	Verify API key is correct and not revoked. Generate a new key from your dashboard if needed. Also verify PRO plan is active.
Widget doesn't appear	Check browser console for errors. Verify shop param is correct
Customer data not loading	Verify customerId is the numeric Shopify ID, not the GID
Wrong language	Set locale parameter to the correct ISO code (e.g., 'de', 'fr', 'ja')
Widget overlaps UI	Adjust position parameter or use custom CSS
API calls failing on headless	Ensure the Anchor app is properly installed and your Shopify store domain is correct in the shop parameter

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 Anchor View Pro Plan

Need help? Contact support or email hello@anchorloyalty.com