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 information can be published on the online store.

LoyaltyLion fields

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

Metafield name	Type	Example	Description
loyaltylion.points_total	Integer	1000	Points total
loyaltylion.points_approved	Integer	800	Points approved
loyaltylion.points_pending	Integer	200	Points pending
loyaltylion.points_spent	Integer	1000	Points spent
loyaltylion.points_lifetime	Integer	2000	Points lifetime
loyaltylion.rewards_claimed	Integer	5	Number of rewards claimed
loyaltylion.rewards_used	Integer	3	Number of rewards used
loyaltylion.enroll_date	Single line text	2024-03-23	Date enrolled in program (YYYY-MM-DD)
loyaltylion.referral_url	Single line text		Loyalty Tier
loyaltylion.receipt_upload_url	Single line text	https://uploads.loyaltylion.net/47921/954250ad40ff42d1cc008962031ac93c	Receipt upload URL
loyaltylion.loyalty_pass_url	Single line text		Loyalty pass URL
loyaltylion.loyalty_tier	Single line text	Silver	Loyalty Tier
loyaltylion.birthday	Single line text	1970-03-15	Birthday (YYYY-MM-DD)
loyaltylion.blocked	True or false	False	Customer is blocked

Tier Eligibility Fields

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

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

Steps for filling in the metafields

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

❗ You may also see unstructured Customer metafields 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

Only Customer metafields require definitions - do not add any definitions for non-Customer loyaltylion metafields, eg Shop metafields

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 Type in LoyaltyLion fields section
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'

References

FAQ

Q. What's the difference between Loyalty Tier and Loyalty Tier (customer tag)?

Loyalty Tier syncs a metafield, which can be referenced in your Shopify theme.

Loyalty Tier (customer tag) adds a tag, which appears in the customer profile.

[Shopify] Metafields