Skip to main content
Mage Loyalty automatically syncs loyalty data into Shopify metafields, making it available in your Liquid templates, theme editor, and Storefront API — no custom code or API calls required.

​
How it works

Mage writes two JSON metafields under the mage.loyalty namespace:
OwnerLiquid accessDescription
Shopshop.metafields.mage.loyaltyYour full loyalty program configuration — earning rules, rewards, VIP tiers, and referral settings
Customercustomer.metafields.mage.loyaltyIndividual customer data — points balance, lifetime points, VIP tier, and status
Both metafields are kept in sync automatically. Shop metafields update whenever you change your program settings in the dashboard. Customer metafields update whenever a customer earns points, redeems a reward, or changes VIP tier.

​
Enabling metafields

1

Open the integration page

In the Mage Loyalty dashboard, go to Integrations > Shopify Metafields.
2

Enable the integration

Toggle the integration on. This creates the metafield definitions on your Shopify store with storefront access enabled, which allows Liquid templates to read the data.
3

Use in your theme

Access the metafields in any Liquid template. See the Examples section for common patterns.

​
Namespace and key

All Mage metafields use the same namespace and key:
PropertyValue
Namespacemage
Keyloyalty
Typejson

​
When metafields update

EventWhat updates
Customer earns points (purchase, signup, review, etc.)Customer metafield
Customer redeems a rewardCustomer metafield
Customer VIP tier changesCustomer metafield
Points expireCustomer metafield
You edit earning rules, rewards, or tiers in the dashboardShop metafield
You enable/disable a programShop metafield
Metafield syncs are fire-and-forget — they never block or slow down the primary loyalty operation. If a sync fails (e.g. due to a temporary Shopify API issue), the data will be corrected on the next qualifying event.