The customer metafield contains the logged-in customer's loyalty data. Access it in any Liquid file with:
{% if customer %} {% assign loyalty = customer.metafields.mage.loyalty.value %} {% endif %}Important: Customer metafields are only available when a customer is logged in. Always wrap your code in {% if customer %} to avoid errors for guest visitors.
Fields
Field | Type | Description |
| Number | The customer's current available points |
| Number | Total points the customer has earned (all time) |
| Number | Total points the customer has redeemed |
| String | The customer's current VIP tier name (e.g. "Gold") |
| String | Either |
Examples
Points balance badge
Display the customer's points in your header or navigation:
{% if customer %}
{% assign loyalty = customer.metafields.mage.loyalty.value %}
{% if loyalty %}
<span class="points-badge">{{ loyalty.points_balance }} pts</span>
{% endif %}
{% endif %}VIP tier badge
Show the customer's current tier:
{% if customer %}
{% assign loyalty = customer.metafields.mage.loyalty.value %}
{% if loyalty.vip_tier %}
<span class="vip-badge">{{ loyalty.vip_tier }} Member</span>
{% endif %}
{% endif %}Account page stats
Display a loyalty summary on the customer's account page:
{% if customer %}
{% assign loyalty = customer.metafields.mage.loyalty.value %}
{% if loyalty %}
<div class="loyalty-stats">
<div>
<strong>{{ loyalty.points_balance }}</strong> <span>Available Points</span>
</div>
<div>
<strong>{{ loyalty.lifetime_points }}</strong> <span>Lifetime Points</span>
</div>
<div>
<strong>{{ loyalty.redeemed_points }}</strong> <span>Redeemed</span>
</div>
</div>
{% if loyalty.vip_tier %}
<p>
Your VIP Tier: <strong>{{ loyalty.vip_tier }}</strong>
</p>
{% endif %}
{% endif %}
{% endif %}Progress towards next reward
Combine the customer and shop metafields to show how close a customer is to their next reward:
{% if customer %}
{% assign loyalty = customer.metafields.mage.loyalty.value %}
{% assign shop_loyalty = shop.metafields.mage.loyalty.value %}
{% if loyalty and shop_loyalty.points_program.enabled %}
{% assign balance = loyalty.points_balance %}
{% for reward in shop_loyalty.points_program.points_rewards %}
{% if reward.is_active and balance < reward.points_cost %}
{% assign remaining = reward.points_cost | minus: balance %}
{% assign progress = balance | times: 100 | divided_by: reward.points_cost %}
<div class="next-reward">
<p>
{{ remaining }} more points until <strong>{{ reward.name }}</strong>
</p>
<div class="progress-bar"><div class="progress-fill" style="width: {{ progress }}%"></div></div>
</div>
{% break %}
{% endif %}
{% endfor %}
{% endif %}
{% endif %}Personalised message based on tier
Show different content depending on the customer's VIP tier:
{% if customer %}
{% assign loyalty = customer.metafields.mage.loyalty.value %}
{% if loyalty %}
{% case loyalty.vip_tier %}
{% when 'Bronze' %}
<p>Welcome! Earn more points to unlock better rewards.</p>
{% when 'Silver' %}
<p>Great progress! You're on your way to Gold.</p>
{% when 'Gold' %}
<p>You're a Gold member — enjoy 2x points on every order!</p>
{% when 'Platinum' %}
<p>Thank you for being a top-tier Platinum member!</p>
{% endcase %}
{% endif %}
{% endif %}Hide content for excluded customers
If a customer has been excluded from the loyalty program, you may want to hide loyalty content:
{% if customer %}
{% assign loyalty = customer.metafields.mage.loyalty.value %}
{% if loyalty and loyalty.status == 'member' %}
<!-- Show loyalty content -->
<p>You have {{ loyalty.points_balance }} points</p>
{% endif %}
{% endif %}When Does This Data Update?
The customer metafield is automatically updated whenever:
A customer earns points (from a purchase, signup, social action, review, etc.)
A customer redeems points for a reward
A customer's VIP tier changes
Points are manually adjusted by a store admin
A customer is excluded from or re-included in the program
No action is needed on your part — the data stays in sync automatically.