Metafield namespaces
Appstle Loyalty writes to two namespaces, on shop and customer resources.The
$app:appstle_loyalty namespace uses Shopify’s app-owned metafield protection. Only the Appstle Loyalty app can read and write it. Themes, Liquid templates, and other apps cannot access it.Shop metafields — appstle_loyalty
These metafields store the complete loyalty program configuration. They are written whenever a merchant saves settings in the Appstle admin, and updates are immediate.
Core configuration
Widget configuration
Points configuration
Example: point_earn_rules
Example: point_earn_rules
type is the way to earn, such as PURCHASE, BIRTHDAY or SUBSCRIBE_NEWSLETTER, and customerFacingLabel is text you can show to customers.Example: point_redeem_rules
Example: point_redeem_rules
ruleStartDate and ruleEndDate (either can be null). type says what the customer gets, such as DISCOUNT_CODE, FREE_SHIPPING, FREE_PRODUCT, DYNAMIC_DISCOUNT or STORE_CREDIT, and id is the redeemRuleId you send to redeem the rule from your own storefront code (see Build your own frontend).Feature flags
VIP tier configuration
Example: vip_tiers
Example: vip_tiers
serial), and this example shows the first. milestone is what a customer needs to reach the tier: points earned, money spent or orders placed, depending on type in vip_tier_setting (POINTS_EARNED, AMOUNT_SPENT or ORDERS_PLACED). In an AMOUNT_SPENT program, Appstle adds up the customer’s orders in the program’s evaluation period, or all their orders when timeToAchieveMilestone is LIFETIME, in the store’s currency. It counts each order at its total after refunds, including a refund entered as an amount without returning any items, and leaves out test orders and voided, cancelled and fully refunded orders. The customer’s total is vipTierSpentAmount in customer_loyalty. In an ORDERS_PLACED program, Appstle counts the customer’s orders in the program’s evaluation period, or all their orders when timeToAchieveMilestone is LIFETIME. It leaves out test orders, voided, cancelled and fully refunded orders, and orders whose current total after refunds, in the store’s currency, is below minimumOrderValue in vip_tier_setting. A minimumOrderValue of 0 or null counts every other order. The customer’s count is vipTierOrderCount in customer_loyalty. imageUrl is the tier’s badge image. customerFacingLabel is a template: replace {{milestone}} with the tier’s milestone and remove {{VIP_TYPE}} before you show it. In an ORDERS_PLACED program, a tier whose customerFacingLabel is still the default {{VIP_TYPE}} {{milestone}} points/amount. reads as points or money, so show your own text, such as Place 5 orders, as the Appstle widget does.amountOfTimeToAchieveTier sets how long a customer keeps the tier. With CUSTOM, the tier ends vipInterval months or years after the customer reaches it, and vipIntervalType says which (MONTH or YEAR). Read those two fields only for CUSTOM tiers. With LIFETIME, the tier has no length of its own, and the program’s rules in vip_tier_setting apply. allowedCustomerTags and restrictCustomersWithTags are comma-separated tag lists. When the allowed list is set, only customers with one of those tags can reach the tier, and customers with a restricted tag never can. additionalTags is a comma-separated list of extra tags the tier gives its customers (see Additional VIP tier tags).Appstle updates vip_tiers only while vip_tier_enabled is true. When the merchant turns VIP tiers off, the last value stays on the shop, so check vip_tier_enabled before you read vip_tiers.Referral configuration
Example: referral_loyalty
Example: referral_loyalty
referralGet is the reward text for the customer who refers a friend, and referredGet is the one for the friend. The texts are ready to show, with money in the store’s currency. A side with no reward has the text "0", so check for it before you show one. referralType is the friend’s action that completes the referral: CREATE_ACCOUNT (accepting the invitation), PURCHASE, SUBSCRIPTION, BUY_PRODUCT or BUY_PRODUCT_FROM_COLLECTION.referralGetAmounts and referredGetAmounts list each money amount a reward text can contain: the fixed discount, the minimum purchase and, for free shipping, the maximum shipping rate. Each entry has the raw amount and the exact text it’s written as. To show a reward text in a shopper’s market currency, replace each text you find in it with the converted amount. An amount can be listed without appearing in the text, like the $0.00 minimum purchase here. Both lists are empty when the reward is points or store credit.referralAllowedCustomerTags and referralRestrictedCustomerTags are comma-separated tag lists that decide who can refer. When the allowed list is set, only customers with one of those tags can refer, and customers with a restricted tag can’t. An empty string means no limit. Hide the referral link from customers who can’t refer: if a friend accepts a link from one of them anyway, Appstle rejects it.Appstle updates referral_loyalty only while the referral program is on. When the merchant turns it off, referral_enabled becomes false and the last value stays, so check referral_enabled first.Points expiration
expirationInterval is the length of the expiry window, and expirationIntervalType is its unit: DAY, MONTH or YEAR. A month counts as 30 days and a year as 365. The merchant also chooses how points expire:
- After a time without activity: all of a customer’s points expire once they go that long without earning or redeeming.
- A set time after they’re earned: each batch of points expires that long after the customer earned it, and points earned first are used first.
pointExpiryMode, as in the example above. A store that expires points a set time after they’re earned has "pointExpiryMode": "FIXED":
pointExpiryMode on November 17, 2026. A store that chose the set-time mode before then gets it the next time Appstle rewrites the store’s metafields, for example when the merchant saves a change to the points program. Until then, its metafield looks like an inactivity store’s, so when pointExpiryMode is missing, confirm the mode with the merchant.
Appstle checks for expired points once a day. The setting never touches store credit or pending points. pointsExpireAt in the customer_loyalty metafield below holds each customer’s next expiry date. Appstle removes points_expiration_setting when the merchant turns point expiration off.
Customer metafields — appstle_loyalty
customer_loyalty
The customer loyalty profile is stored as a JSON metafield on each enrolled customer. Appstle updates it after every loyalty event — points earned or redeemed, VIP tier changes, referrals, social engagement, and more. Updates are near real-time, typically within a few seconds.
Access in Liquid:
value:
lastActivityDate and currentVipTierId, and it doesn’t have vipTierExpiredAt. Each entry in rewards is a full reward record; the example shows its most useful fields.
referralLink is the customer’s short referral link, and its last part is their referral token. For where the link redirects and how to accept a referral with the token, see Referral links and tokens.
storeCreditBalance is the balance Appstle read from Shopify when it last updated this metafield. Store credit that someone adds or removes in the Shopify admin, or that expires, doesn’t update the metafield, so it can show an old balance until Appstle next updates the customer’s data. For the current balance in Liquid, use Shopify’s own customer.store_credit_account.balance. It’s the balance in the currency the customer is shopping in, and customer.store_credit_account is nil when the customer has no store credit in that currency. Like other Liquid money values, show it with a money filter such as money. From your server, call Get customer loyalty details. From storefront JavaScript, call GET /apps/loyalty/cp/api/customer-loyalty. Both read the balance from Shopify on each call.
pointsExpireAt and expiringPointsAmount are null unless point expiration is on and the customer has points. They can also be null for a customer with points, even when lastActivityDate is set, so always handle null. While point expiration is on, lastActivityDate is the later of the customer’s stored last activity and their newest points transaction, the date Appstle’s daily check counts from. In stores that expire points After a time without activity, pointsExpireAt is lastActivityDate plus the expiry window in points_expiration_setting: that’s when the customer’s points are due to expire if they don’t earn or redeem first, and expiringPointsAmount equals availablePoints. In stores that expire points A set time after they’re earned, pointsExpireAt is the date the oldest batch of points that isn’t fully spent expires: when that batch was earned plus the window. expiringPointsAmount is what’s left of that batch, which can be less than availablePoints, and both are null when the customer has no such batch. Later batches expire on later dates that these fields don’t show.
Show VIP status and progress
This example prints a signed-in customer’s VIP tier and how far they are from the next tier, for a custom loyalty page in your theme. It reads thecustomer_loyalty customer metafield and three shop metafields: vip_tier_enabled, vip_tier_setting and vip_tiers. To list the tiers for every visitor, signed in or not, read vip_tiers after you check vip_tier_enabled.
The example checks, in order:
- VIP tiers are on.
vip_tier_enabledistrueandvip_tier_settingexists. - The visitor is a member.
customeris empty for a signed-out visitor, andcustomer_loyaltyexists only for a customer who has joined the rewards program. - The VIP program can include the customer.
vip_tier_settingholds the VIP program’s Who can join tags inallowedCustomerTagsandrestrictCustomersWithTags, each a comma-separated list ornull. Appstle gives tiers automatically only to customers who have one of the allowed tags (when that list isn’t empty) and none of the restricted tags. It compares tags without regard to case or spaces around them. - The customer’s tier.
currentVipTieris the tier’s name, ornullwhen the customer has no tier. The example shows a tier the customer holds even when the VIP program leaves them out, because the merchant can give a tier by hand. A customer the VIP program leaves out who has no tier seesYour account isn't part of the VIP program. - The customer’s progress. The example shows progress only for a customer the VIP program can include.
achievableTierIdis theidof the next tier invip_tiers. Subtract the customer’s progress from that tier’smilestone. What counts as progress depends ontypeinvip_tier_setting:
You're not in a VIP tier yet. instead of the first line.
achievableTierId is null when no tier above the customer’s is open to them, for example in the highest tier, when the merchant set or removed the customer’s tier by hand, or when the VIP program’s tags leave the customer out. It’s also null when the program or a tier above the customer’s uses tags and Appstle can’t read the customer’s tags from Shopify. The example then shows no progress line. When a change to a customer’s tags moves them into or out of the VIP program, Appstle syncs the customer again and rewrites customer_loyalty. Appstle updates customer_loyalty within a few seconds after each loyalty event, so a page loaded right after an order or a change to the customer’s points can show the old values.
Customer metafields — $app:appstle_loyalty
customer_rewards
Stores the customer’s unredeemed reward discount codes. This metafield is private — it is used by Shopify’s discount function to auto-apply rewards at checkout and cannot be read by themes, Liquid templates, or other apps.
Customer tags
Appstle Loyalty applies tags only to customer resources — not orders or products.Enrollment tags
When a customer joins the loyalty program, Appstle adds the tagAppstle Loyalty Member to their Shopify customer profile, along with any tags the merchant lists under Additional Tags on Loyalty Enrollment in Advanced Settings. Use the tags to segment members in Shopify, for example in a customer segment or a Shopify Flow condition.
Appstle adds the tags when:
- The customer joins from the storefront, through the Appstle widget or the Storefront API (see Build your own frontend).
- You enroll the customer with
POST /api/external/enroll-customer(see the integration guide). - Shopify creates a customer account on a store that doesn’t require customers to opt in, and Appstle enrolls the new customer automatically.
- If the customer already has one of the tags in any letter case, such as
appstle loyalty member, Appstle leaves it as it is and doesn’t add it again. - Appstle skips any of the merchant’s tags longer than 255 characters, Shopify’s limit for a tag, so the customer still gets the others.
- The merchant can turn the default tag off with Add the “Appstle Loyalty Member” Tag on Enrollment. It’s on until they do. Their own tags are still added, and customers who already have the default tag keep it.
- Appstle never removes these tags, even when a customer leaves the program or the merchant excludes them.
VIP tier name tags
When a customer achieves or is assigned a VIP tier, the tier’s name is applied as a customer tag (e.g.,Silver, Gold, Platinum). When the tier changes, the old name tag is removed and the new one is added. Only one tier name tag is active at a time.
Tags are applied by:
- Automatic tier calculation based on spend, points, or order thresholds
- Manual tier assignment in the Appstle admin
- Referral flow tier assignment
- Shopify Flow
Assign VIP Tieraction - Bulk operations
Additional VIP tier tags
Each VIP tier can be configured with a comma-separated list ofadditionalTags. These are applied alongside the tier name tag and removed together with it on tier change.
For example, a Gold tier configured with additionalTags = "premium-member, vip-support" applies three tags when a customer reaches Gold: Gold, premium-member, vip-support. All three are replaced when the customer moves to the next tier.
Referral tags
When a referral is accepted by both parties, permanent tags are applied to record the relationship.
These tags are never removed.
Example: Customer A (ID
1111) refers Customer B (ID 2222):
- Customer A receives tag
referral:2222 - Customer B receives tag
referred:1111
Frequently asked questions
Can I read loyalty metafields from a Liquid theme?
Can I read loyalty metafields from a Liquid theme?
Yes. Metafields in the
appstle_loyalty namespace are public. Access them in Liquid via {{ customer.metafields.appstle_loyalty.customer_loyalty }}. The customer_rewards metafield in the $app:appstle_loyalty namespace is private and cannot be accessed from Liquid or other apps.How quickly are customer loyalty metafields updated?
How quickly are customer loyalty metafields updated?
Appstle updates customer loyalty metafields after every loyalty event. Updates are near real-time — typically within a few seconds of the event occurring.
Can other apps read the customer_rewards discount codes?
Can other apps read the customer_rewards discount codes?
No. The
customer_rewards metafield uses the $app:appstle_loyalty private namespace, which can only be read and written by the Appstle Loyalty app. This prevents discount codes from being exposed to unauthorized apps or themes.Next steps
Build your own frontend
Show a customer’s points, rewards and referrals in your own theme.
JavaScript events
Listen for the event the loyalty widget fires when a customer applies a reward.
Webhooks
Receive an event on your server when a customer joins, earns or redeems points, reaches a VIP tier or gets a referral reward.
API changelog
Dated changes to the metafields and tags, the Loyalty APIs, webhooks and Flow, with what to do about each.