Shop Object Reference

The shop metafield contains your full loyalty program configuration. Access it in any Liquid file with:

{% assign loyalty = shop.metafields.mage.loyalty.value %}

Points Program

Field	Type	Description
`points_program.enabled`	Boolean	Whether the points program is turned on
`points_program.points_expiry_enabled`	Boolean	Whether points expire
`points_program.points_expiry_days`	Number or null	Number of days before points expire

Ways to Earn (`points_program.ways_to_earn`)

An array of all earning rules configured in your program.

Field	Type	Description
`name`	String	The name of the earning rule (e.g. "Place an Order")
`description`	String or null	A description of the earning rule
`points`	Number	Number of points awarded
`type`	String	The trigger type (e.g. `purchase`, `signup`, `birthday`, `follow_on_instagram`)
`category`	String or null	The rule category (e.g. `purchase`, `social`, `engagement`)
`is_active`	Boolean	Whether this rule is currently active
`customer_facing_label`	String or null	Optional custom label shown to customers
`call_to_action_url`	String or null	URL for the action (e.g. a social media profile link)

Example — Display earning rules

{% assign loyalty = shop.metafields.mage.loyalty.value %}
{% if loyalty.points_program.enabled %}
  <h2>Ways to Earn Points</h2>
  <ul>
    {% for rule in loyalty.points_program.ways_to_earn %}
      {% if rule.is_active %}
        <li>{{ rule.name }} — Earn {{ rule.points }} points</li>
      {% endif %}
    {% endfor %}
  </ul>
{% endif %}

Rewards (`points_program.points_rewards`)

An array of all rewards customers can redeem with their points.

Field	Type	Description
`name`	String	The reward name (e.g. "$5 Off")
`points_cost`	Number	How many points are needed to redeem
`discount_type`	String	One of: `fixed`, `percentage`, `free-shipping`, `free-product`
`discount_amount`	Number or null	The discount value (e.g. `5` for $5 off or 5% off)
`minimum_spend`	Number or null	Minimum order amount required, if any
`is_active`	Boolean	Whether this reward is currently available

Example — Show available rewards

{% assign loyalty = shop.metafields.mage.loyalty.value %}
{% for reward in loyalty.points_program.points_rewards %}
  {% if reward.is_active %}
    <div class="reward">
      <h3>{{ reward.name }}</h3>
      <p>{{ reward.points_cost }} points</p>
    </div>
  {% endif %}
{% endfor %}

VIP Program

Field	Type	Description
`vip_program.enabled`	Boolean	Whether the VIP tier program is turned on

Note: When the VIP program is disabled, tiers will be an empty array.

Tiers (`vip_program.tiers`)

An array of VIP tiers, ordered from lowest to highest.

Field	Type	Description
`name`	String	Tier name (e.g. "Gold")
`points_required`	Number	Lifetime points needed to reach this tier
`multiplier`	Number	Points multiplier for this tier (e.g. `2` means 2x points)
`badge_color`	String or null	Hex color code for the tier badge
`description`	String or null	Tier description

Example — Display VIP tiers

{% assign loyalty = shop.metafields.mage.loyalty.value %}
{% if loyalty.vip_program.enabled %}
  <h2>VIP Tiers</h2>
  {% for tier in loyalty.vip_program.tiers %}
    <div class="tier" style="border-color: {{ tier.badge_color }}">
      <h3>{{ tier.name }}</h3>
      <p>Earn {{ tier.points_required }} lifetime points to unlock</p>
      {% if tier.multiplier > 1 %}
        <p>{{ tier.multiplier }}x points on every order</p>
      {% endif %}
    </div>
  {% endfor %}
{% endif %}

Referral Program

Field	Type	Description
`referral_program.enabled`	Boolean	Whether the referral program is turned on
`referral_program.customer_account_required`	Boolean	Whether customers need an account to refer

Note: When the referral program is disabled, referral_rewards will be an empty array.

Referral Rewards (`referral_program.referral_rewards`)

Field	Type	Description
`name`	String	Reward name
`discount_type`	String	One of: `fixed`, `percentage`, `free-shipping`, `free-product`
`reward_type`	String	Either `referrer` (the person referring) or `friend` (the person being referred)

Social Settings (`referral_program.social_settings`)

Which sharing channels are enabled for referrals.

Field	Type	Description
`twitter`	Boolean	X/Twitter sharing enabled
`facebook`	Boolean	Facebook sharing enabled
`email`	Boolean	Email sharing enabled
`whatsapp`	Boolean	WhatsApp sharing enabled

Example — Show referral program info

{% assign loyalty = shop.metafields.mage.loyalty.value %}
{% if loyalty.referral_program.enabled %}
  <h2>Refer a Friend</h2>
  {% for reward in loyalty.referral_program.referral_rewards %}
    {% if reward.reward_type == 'referrer' %}
      <p>You get: {{ reward.name }}</p>
    {% elsif reward.reward_type == 'friend' %}
      <p>Your friend gets: {{ reward.name }}</p>
    {% endif %}
  {% endfor %}
{% endif %}

Full Example — Loyalty Landing Page

{% assign loyalty = shop.metafields.mage.loyalty.value %}
{% if loyalty.points_program.enabled %}
  <section class="loyalty-landing">
    <h1>Our Rewards Program</h1>
    <h2>Earn Points</h2>
    {% for rule in loyalty.points_program.ways_to_earn %}
      {% if rule.is_active %}
        <div>{{ rule.name }} — {{ rule.points }} points</div>
      {% endif %}
    {% endfor %}
    <h2>Spend Points</h2>
    {% for reward in loyalty.points_program.points_rewards %}
      {% if reward.is_active %}
        <div>{{ reward.name }} — {{ reward.points_cost }} points</div>
      {% endif %}
    {% endfor %}
    {% if loyalty.vip_program.enabled %}
      <h2>VIP Tiers</h2>
      {% for tier in loyalty.vip_program.tiers %}
        <div>{{ tier.name }} — {{ tier.points_required }} points</div>
      {% endfor %}
    {% endif %}
    {% if loyalty.referral_program.enabled %}
      <h2>Referral Program</h2>
      <p>Refer friends and earn rewards!</p>
    {% endif %}
    {% if loyalty.points_program.points_expiry_enabled %}
      <p>
        <small>Points expire after {{ loyalty.points_program.points_expiry_days }} days.</small>
      </p>
    {% endif %}
  </section>
{% endif %}