Skip to main content
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: 
{% 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: 
{% 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: 
{% 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: 
{% 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: 
{% 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

{% 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: 
{% 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 %}