Getting Started with Mage Metafields

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:

Owner	Liquid access	Description
Shop	`shop.metafields.mage.loyalty`	Your full loyalty program configuration: earning rules, rewards, VIP tiers, referral settings, and any active bonus campaign
Customer	`customer.metafields.mage.loyalty`	Individual 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.

Namespace and key

All Mage metafields use the same namespace and key:

Property	Value
Namespace	`mage`
Key	`loyalty`
Type	`json`

When metafields update

Event	What updates
Customer earns points (purchase, signup, review, etc.)	Customer metafield
Customer redeems a reward	Customer metafield
Customer VIP tier changes	Customer metafield
Points expire	Customer metafield
You edit earning rules, rewards, or tiers in the dashboard	Shop metafield
You enable/disable a program	Shop metafield

REST API

API Resources

Webhook Events

Shopify Metafields

How it works

Namespace and key

When metafields update

​How it works

​Namespace and key

​When metafields update

How it works

Namespace and key

When metafields update