Metafield sync is for Shopify stores. It runs for all your customers automatically, with nothing to turn on.
What are metafields?
LoyaltyLion pushes customer properties to Shopify customer metafields when a customer changes. When a customer earns points or their tier changes, we update the metafields on that customer 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 | Approved and pending points |
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 | Approved, pending and spent points |
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-23T14:05:00.000Z | Date and time the customer enrolled in your program (ISO 8601, UTC) |
loyaltylion.referral_url | Single line text |
| Referral URL |
loyaltylion.receipt_upload_url | Single line text | 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-15T09:00:00+00:00 | Birthday, as a date and time in your store’s time zone (ISO 8601) |
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 |
The loyalty tier customer tag
Alongside the loyaltylion.loyalty_tier metafield, we add your customer's tier to their Shopify profile as a tag. The tag is written in the form tier: Tier name, so a customer in your Gold tier carries the tag tier: Gold.
We update the tag in real time as your customers move between tiers, and remove the old one, so each customer only ever carries the tag for the tier they are in. The first sync can take a couple of hours, depending on how many customers you have.
Commas are removed from your tier name when we build the tag. A tier called Gold, VIP produces the tag tier: Gold VIP, so filter on that rather than on the tier name exactly as you typed it.
To find every customer in a tier, go to Customers in your Shopify admin, click Filter customers, select Tagged with, and enter the tag.
Steps for filling in the metafields
You will need to fill in the Customer metafields to show the customer's LoyaltyLion data in Shopify.
❗ You may also see unstructured Customer metafields called "loyaltylion.seamless-product-discounts" or "loyaltylion.entitlements". 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 :
Add a Name
Click Select Type, and select the correct type for the field as per the
Typein LoyaltyLion fields section
Do not add any Validations
Make sure the Storefronts access under Options is set to Read
The metafield should then look like the below screenshot
Save the metafield
Repeat these steps for each of 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.
Once saved, each metafield appears under Definitions.
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.referral_url }}
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 Actions, and selecting Sync metafields
References
FAQ
Q. What's the difference between the loyalty tier metafield and the tier tag?
The loyaltylion.loyalty_tier metafield can be referenced in your Shopify theme.
The tier: tag appears on the customer profile in your Shopify admin, and you can filter customers by it. We sync both. You don’t need to choose between them.
