Skip to main content
Appstle Loyalty uses Shopify metafields and customer tags to persist loyalty data, power storefront widgets, and enable automation in Shopify Flow and Liquid themes. This page documents each loyalty metafield and tag: what it contains, when it’s updated, and how to use it in your integration or theme.

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

Each entry is a full rule, and this example shows only some of its fields. type is the way to earn, such as PURCHASE, BIRTHDAY or SUBSCRIBE_NEWSLETTER, and customerFacingLabel is text you can show to customers.
Each entry is a full rule, and this example shows only some of its fields. The list includes rewards outside their start and end dates, so show a reward only between its 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

The array holds one entry per active tier, in the order the merchant arranged them (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

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.
A store that expires points after a time without activity has no pointExpiryMode, as in the example above. A store that expires points a set time after they’re earned has "pointExpiryMode": "FIXED":
Appstle added 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:
Read a field through value:
Full schema: The value is a JSON object with almost the same fields as Get customer loyalty details: it adds 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 the customer_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:
  1. VIP tiers are on. vip_tier_enabled is true and vip_tier_setting exists.
  2. The visitor is a member. customer is empty for a signed-out visitor, and customer_loyalty exists only for a customer who has joined the rewards program.
  3. The VIP program can include the customer. vip_tier_setting holds the VIP program’s Who can join tags in allowedCustomerTags and restrictCustomersWithTags, each a comma-separated list or null. 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.
  4. The customer’s tier. currentVipTier is the tier’s name, or null when 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 sees Your account isn't part of the VIP program.
  5. The customer’s progress. The example shows progress only for a customer the VIP program can include. achievableTierId is the id of the next tier in vip_tiers. Subtract the customer’s progress from that tier’s milestone. What counts as progress depends on type in vip_tier_setting:
For a Bronze customer with 782.2 credited points, where the next tier is Silver at 1500 points, the example prints:
The example rounds the amount left up and the percentage down to whole numbers. For a customer with no tier, it prints You're not in a VIP tier yet. instead of the first line.
Since November 19, 2026, achievableTierId is null for a customer the VIP program’s Who can join tags leave out, wherever it appears: the customer_loyalty metafield, the Admin API’s Get customer loyalty details, the Storefront API’s Get customer loyalty information and customerLoyaltyDetails in webhooks. Before then it checked only each tier’s own tags, and a customer_loyalty metafield that Appstle wrote before then keeps its old value until Appstle next updates it. Keep the check from step 3 before you show progress. achievableTierId is the tier with the lowest milestone above the customer’s current tier, among the tiers whose own allowedCustomerTags and restrictCustomersWithTags allow the customer.
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 tag Appstle 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.
The tags follow these rules:
  • 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.
A missing tag doesn’t mean a customer isn’t a member. Members who joined before August 31, 2026 may not have the tag. Appstle doesn’t add the tags when it enrolls a customer while processing an order or a customer sync, such as an existing Shopify customer’s first order on a store that doesn’t require opt-in. If adding a tag fails, Appstle doesn’t try again. To check whether a customer is a member, look for the customer_loyalty metafield in Liquid, as the Appstle widget does, or call Get customer loyalty details from your server.

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 Tier action
  • Bulk operations

Additional VIP tier tags

Each VIP tier can be configured with a comma-separated list of additionalTags. 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

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.
Appstle updates customer loyalty metafields after every loyalty event. Updates are near real-time — typically within a few seconds of the event occurring.
When a customer’s tier changes, the old tier name tag and all its configured additionalTags are removed. The new tier name tag and its additionalTags are then added. Only one tier’s tags are active at any given time.
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.