Shopify metafield sync is available for Shopify merchants on our Classic plan and above.

What are metafields?

LoyaltyLion will push customer properties to Shopify customer metafields when a customer changes: When a customer earns points, or their tier changes, we can update a metafield on the corresponding customer resource in Shopify.

Metafields can be accessed in Liquid templates as well as from the API, which enables some powerful integrations and custom interfaces.

LoyaltyLion fields

The following fields are pushed as customer metafields, and the Loyalty Tier is also pushed as a customer tag.

Description	Metafield Name	Example
Points approved	loyaltylion.points_approved	800
Points lifetime	loyaltylion.points_lifetime	2000
Points pending	loyaltylion.points_pending	200
Points spent	loyaltylion.points_spent	1000
Points total	loyaltylion.points_total	1000
Number of rewards claimed	loyaltylion.rewards_claimed	5
Number of rewards used	loyaltylion.rewards_used	3
Loyalty Tier	loyaltylion.loyalty_tier	Silver
Birthday (YYYY-MM-DD)	loyaltylion.birthday	1970-03-15
Customer is blocked	loyaltylion.blocked	False
Date enrolled in program (YYYY-MM-DD)	loyaltylion.enroll_date	2024-03-23
Referral URL	loyaltylion.referral_url	http://prz.io/KzByQ2Fa
Loyalty Tier (customer tag)	n/a	tag: Silver

Tier Eligibility Fields

If your program has Loyalty Tiers, we will also push tier eligibility metafields:

Description	Metafield Name	Example
The customer's current progress toward maintaining or upgrading their tier	loyaltylion.tier_progress_value	800
When the customer's current tier ends	loyaltylion.tier_expiration_date	2027-03-23
The next tier the customer would reach if they upgrade	loyaltylion.tier_upgrade_tier_name	Gold
The tier the customer is forecasted to be in when their current tier expires	loyaltylion.tier_forecasted_tier_name	Silver
The customer's projected progress when their current tier expires	loyaltylion.tier_progress_value_at_expiration	200
How much more progress the customer needs to keep their current tier when it expires	loyaltylion.tier_progress_needed_for_renewal	300
How much more progress the customer needs to reach the next tier	loyaltylion.tier_progress_needed_for_upgrade	500

Steps for filling in the metafields

You will need to fill in the metafields to show the customer's LL data in Shopify.

❗ You may also see an unstructured metafield called "loyaltylion.seamless-product-discounts" or "loyaltylion.crr-voucher-id" - do NOT add a definition for these metafields, as this may cause issues with LoyaltyLion discounts

Go to Settings in Shopify -> Custom data -> Customers and select View unstructured metafields
After clicking Add definition for one of the LoyaltyLion fields :
1. Add a Name
2. Click Select Type, and select the correct type for the field as per the screenshot below
3. Do not add any Validations
4. Make sure the Storefronts access under Options is set to Read
5. The metafield should then look like the below screenshot
6. Save the metafield
7. Continue steps a through f for the remaining LoyaltyLion unstructured metafields

Make sure to set the definitions types as per screenshot. Otherwise, the integration won't work as expected.

Do not put validations when creating metafields.

3. After saving, the metafield appeared in Definitions with the added “customer.metafields”.

Using metafields

Within Liquid templates

You can reference metafields in most Liquid templates like so:

{{ customer.metafields.loyaltylion.points_total }}

For example, to display the customer's unique referral link:

 referral url: #{{ customer.metafields.loyaltylion.points_total }}

Things to be aware of: sync timing.

Although we generally sync metafields straight away, usually within a few minutes of a customer changing in LoyaltyLion, the sync can be delayed, particularly if many customers change at once, due to Shopify API rate limit restrictions.

If you're using metafields in an integration or in a template, you should account for their values being slightly out of date, or, in the case of new customers, blank.

If a customer has reported that their values look out of date, you can perform a singular sync for that specific customer, by going to their customer profile in your LoyaltyLion program, clicking on the actions button, and selecting 'Sync Metafields'