{{ shop.metafields.mage.loyalty.value }}
Since the metafield type is
json, you access nested properties through .value in Liquid.Full object shape
{
"app_id": "f0e1d2c3b4a5968778695a4b3c2d1e0f",
"memberships_enabled": false,
"points_program": {
"enabled": true,
"ways_to_earn": [
{
"name": "Place an order",
"description": "Earn points for every dollar you spend",
"points": 5,
"type": "purchase",
"category": "orders",
"is_active": true,
"customer_facing_label": "5 points per $1 spent",
"call_to_action_url": null
}
],
"points_rewards": [
{
"name": "$5 Off",
"points_cost": 500,
"discount_type": "fixed",
"discount_amount": 5.0,
"minimum_spend": null,
"is_active": true
}
],
"points_expiry_enabled": false,
"points_expiry_days": null,
"points_expiry_mode": "date_acquired"
},
"vip_program": {
"enabled": true,
"multiplier_mode": "purchase",
"tiers": [
{
"name": "Silver",
"threshold": 0,
"multiplier": 1.0,
"badge_color": "#C0C0C0",
"badge_image_url": null,
"position": 1
},
{
"name": "Gold",
"threshold": 1000,
"multiplier": 1.5,
"badge_color": "#FFD700",
"badge_image_url": null,
"position": 2
}
]
},
"referral_program": {
"enabled": true,
"referral_rewards": [
{
"name": "10% Off for your friend",
"discount_type": "percentage",
"reward_type": "referred_customer"
},
{
"name": "200 bonus points",
"discount_type": "points",
"reward_type": "referring_customer"
}
],
"social_settings": {
"twitter": true,
"facebook": true,
"email": true,
"whatsapp": false
},
"customer_account_required": false
},
"bonus_campaign": {
"active": true,
"name": "Double Points Weekend",
"multiplier_rules": [
{
"earning_rule_name": "Place an order",
"multiplier": 2.0
}
],
"ends_at": "2026-07-01T00:00:00.000Z"
}
}
Field reference
Top level
| Field | Type | Description |
|---|---|---|
app_id | string | The Mage Loyalty app identifier. Rarely needed in templates |
memberships_enabled | boolean | Whether paid memberships are enabled for the shop |
points_program | object | Points earning and redemption configuration |
vip_program | object | VIP tier configuration |
referral_program | object | Referral program configuration |
bonus_campaign | object | null | The currently active bonus campaign, or null when none is running |
points_program
| Field | Type | Description |
|---|---|---|
enabled | boolean | Whether the points program is active |
ways_to_earn | array | List of earning rules |
points_rewards | array | List of rewards available for redemption |
points_expiry_enabled | boolean | Whether points expire |
points_expiry_days | number | null | Days until points expire (null if disabled) |
points_expiry_mode | string | When the expiry clock starts: date_acquired or last_purchase_date |
points_program.ways_to_earn[]
| Field | Type | Description |
|---|---|---|
name | string | Earning rule name |
description | string | null | Optional description |
points | number | Points awarded |
type | string | Rule action type (e.g. purchase, signup, birthday, follow_on_instagram) |
category | string | null | Rule category |
is_active | boolean | Whether the rule is currently active |
customer_facing_label | string | null | Display label for customers |
call_to_action_url | string | null | Optional URL for social/action rules |
points_program.points_rewards[]
| Field | Type | Description |
|---|---|---|
name | string | Reward name |
points_cost | number | Points required to redeem |
discount_type | string | Discount type (fixed, percentage, free-shipping, free-product) |
discount_amount | number | null | Discount value (null for free shipping/product) |
minimum_spend | number | null | Minimum order amount required |
is_active | boolean | Whether the reward is currently active |
vip_program
| Field | Type | Description |
|---|---|---|
enabled | boolean | Whether the VIP program is active |
multiplier_mode | string | null | Which actions the tier multiplier applies to: purchase (orders only), all (all earning), or null when not configured |
tiers | array | List of VIP tiers (sorted by threshold, ascending). Empty when the VIP program is disabled |
vip_program.tiers[]
| Field | Type | Description |
|---|---|---|
name | string | Tier name |
threshold | number | Lifetime points needed to reach this tier |
multiplier | number | Points earning multiplier (e.g. 1.5 = 1.5x points) |
badge_color | string | null | Hex color for the tier badge |
badge_image_url | string | null | Custom badge image URL |
position | number | The tier’s rank, 1-indexed by threshold ascending (e.g. Silver = 1, Gold = 2) |
referral_program
| Field | Type | Description |
|---|---|---|
enabled | boolean | Whether the referral program is active |
referral_rewards | array | Rewards offered for referrals. Empty when the program is disabled |
social_settings | object | Which sharing channels are enabled |
customer_account_required | boolean | Whether referred friends must create an account |
referral_program.referral_rewards[]
| Field | Type | Description |
|---|---|---|
name | string | Reward name |
discount_type | string | Type of discount (percentage, fixed, points, free-shipping, free-product) |
reward_type | string | Who receives it (referring_customer or referred_customer) |
referral_program.social_settings
| Field | Type | Description |
|---|---|---|
twitter | boolean | Twitter/X sharing enabled |
facebook | boolean | Facebook sharing enabled |
email | boolean | Email sharing enabled |
whatsapp | boolean | WhatsApp sharing enabled |
bonus_campaign
null when no bonus campaign is currently active. When a campaign is running:
| Field | Type | Description |
|---|---|---|
active | boolean | Always true while present |
name | string | null | Campaign name |
multiplier_rules | array | The earning rules boosted by this campaign |
ends_at | string | null | ISO 8601 timestamp when the campaign ends |
bonus_campaign.multiplier_rules[]
| Field | Type | Description |
|---|---|---|
earning_rule_name | string | The name of the boosted earning rule |
multiplier | number | The bonus multiplier applied during the campaign |