Basics

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

REST API

API Resources

Webhook Events

Shopify Metafields

Accessing JSON metafields

Checking if metafields exist

Iterating over arrays

Displaying rewards

Combining shop and customer data

​Accessing JSON metafields

​Checking if metafields exist

​Iterating over arrays

​Displaying rewards

​Combining shop and customer data

Accessing JSON metafields

Checking if metafields exist

Iterating over arrays

Displaying rewards

Combining shop and customer data