> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mageloyalty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started with Mage Metafields

> Access your loyalty program data directly in Shopify Liquid templates using metafields.

Mage Loyalty automatically syncs loyalty data into [Shopify metafields](https://shopify.dev/docs/apps/custom-data/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, and referral settings |
| **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     |