The shop metafield contains your full loyalty program configuration. Access it in Liquid at:
{{ shop.metafields.mage.loyalty.value }}
Since the metafield type is json, you access nested properties through .value in Liquid.
Full object shape
{
"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
},
"vip_program": {
"enabled": true,
"multiplier_mode": "multiplier",
"tiers": [
{
"name": "Silver",
"points_required": 0,
"multiplier": 1.0,
"badge_color": "#C0C0C0",
"badge_image_url": null,
"description": "Welcome to the program"
},
{
"name": "Gold",
"points_required": 1000,
"multiplier": 1.5,
"badge_color": "#FFD700",
"badge_image_url": null,
"description": "Earn 1.5x points on every purchase"
}
]
},
"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
}
}
Field reference
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_program.ways_to_earn[]
| Field | Type | Description |
|---|
name | string | Earning rule name |
description | string | null | Optional description |
points | number | Points awarded |
type | string | Rule type (e.g. purchase, signup, birthday, review) |
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 | How multipliers are applied |
tiers | array | List of VIP tiers (sorted by points required, ascending) |
vip_program.tiers[]
| Field | Type | Description |
|---|
name | string | Tier name |
points_required | 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 |
description | string | null | Tier description |
referral_program
| Field | Type | Description |
|---|
enabled | boolean | Whether the referral program is active |
referral_rewards | array | Rewards offered for referrals |
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 |
