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

# Basics

> Learn the fundamentals of accessing Mage Loyalty metafields in Liquid.

This guide covers the basics of reading Mage Loyalty metafields in your Shopify Liquid templates.

## Accessing JSON metafields

Mage metafields are stored as JSON. In Liquid, you access the parsed data through the `.value` property:

```liquid theme={null}
{% assign loyalty = shop.metafields.mage.loyalty.value %}
{% assign customer_loyalty = customer.metafields.mage.loyalty.value %}
```

Once assigned to a variable, you can access nested properties using dot notation:

```liquid theme={null}
{% assign loyalty = shop.metafields.mage.loyalty.value %}

{% if loyalty.points_program.enabled %}
  <p>Our loyalty program is active!</p>
{% endif %}
```

## Checking if metafields exist

Always check that a metafield exists before using it. This prevents errors on pages where the data may not be available:

```liquid theme={null}
{% assign loyalty = shop.metafields.mage.loyalty.value %}

{% if loyalty %}
  {%- comment -%} Safe to use loyalty data {%- endcomment -%}
  <p>Earn points on every purchase</p>
{% endif %}
```

For customer metafields, also ensure the customer is logged in:

```liquid theme={null}
{% if customer %}
  {% assign customer_loyalty = customer.metafields.mage.loyalty.value %}

  {% if customer_loyalty %}
    <p>You have {{ customer_loyalty.points_balance }} points</p>
  {% endif %}
{% endif %}
```

## Iterating over arrays

Earning rules, rewards, and VIP tiers are arrays. Loop through them with `for`:

```liquid theme={null}
{% assign loyalty = shop.metafields.mage.loyalty.value %}

{% if loyalty.points_program.enabled %}
  <h3>Ways to earn</h3>
  <ul>
    {% for rule in loyalty.points_program.ways_to_earn %}
      {% if rule.is_active %}
        <li>{{ rule.name }} — {{ rule.points }} points</li>
      {% endif %}
    {% endfor %}
  </ul>
{% endif %}
```

## Displaying rewards

```liquid theme={null}
{% assign loyalty = shop.metafields.mage.loyalty.value %}

{% if loyalty.points_program.enabled %}
  <h3>Redeem your points</h3>
  {% for reward in loyalty.points_program.points_rewards %}
    {% if reward.is_active %}
      <div>
        <strong>{{ reward.name }}</strong>
        <span>{{ reward.points_cost }} points</span>
      </div>
    {% endif %}
  {% endfor %}
{% endif %}
```

## Combining shop and customer data

A common pattern is to show the customer how close they are to a reward:

```liquid theme={null}
{% if customer %}
  {% assign loyalty = shop.metafields.mage.loyalty.value %}
  {% assign customer_loyalty = customer.metafields.mage.loyalty.value %}

  {% if loyalty and customer_loyalty %}
    {% for reward in loyalty.points_program.points_rewards %}
      {% if reward.is_active %}
        {% assign points_needed = reward.points_cost | minus: customer_loyalty.points_balance %}

        {% if points_needed <= 0 %}
          <p>You can redeem <strong>{{ reward.name }}</strong> now!</p>
        {% else %}
          <p>{{ points_needed }} more points until <strong>{{ reward.name }}</strong></p>
        {% endif %}
      {% endif %}
    {% endfor %}
  {% endif %}
{% endif %}
```