appstle_membership without a $app: prefix, which means other apps, themes, and Liquid templates can read it. Appstle also keeps a few app-owned metafields in Shopify’s $app namespace for its own storefront script. They are private to the app and are not part of this interface.
Metafields overview
Metafields are set on three Shopify resource types:Shop metafields
Shop metafields store the membership program configuration and are used by the storefront for access gating, checkout validation, and widget rendering. They are updated synchronously on every settings save in the Appstle admin.appstle_membership / setting
Stores shop-level membership settings as a snapshot for storefront access. Used by the app and themes to determine global membership behavior.
appstle_membership / all_selling_plans
All selling plans configured for this store’s membership program. Themes and apps read this to display available membership options.
appstle_membership / rules_by_customer_tag
Access rules keyed by customer tag. The storefront reads this metafield alongside the customer’s tags to determine which collections and products each membership tier can access.
If a customer has the
premium-member tag, they see all collections and products mapped to that tag. Non-members or lower tiers see gated content as locked or hidden, depending on your theme configuration.appstle_membership / checkout_validation
Checkout validation configuration. Enforces member-only product purchase rules at checkout.
appstle_membership / widget_label
Storefront widget label translations for the default locale.
appstle_membership / customer_portal_label
Customer portal label translations for the default locale. For non-default locales, translations are registered via Shopify’s TranslationsRegisterMutation rather than separate metafields.
Customer metafields
Appstle writes customer metafields asynchronously, typically a few seconds after a change.appstle_membership / subscriptions
Unlike Subscriptions, Memberships writes the whole list to this one key.
This is a customer with one active and one cancelled membership:
membershipStartDate, nextBillingDate, billingCyclesCompleted, consecutiveSuccessfulCycles and membershipTier can be missing from every entry when Appstle rewrites a customer’s metafields outside a membership event, for example during a resync. They return with the customer’s next membership event, such as a billing attempt. Treat a missing field as unknown, not as 0.
To gate content on an active membership, check status === "active" on each entry. Don’t treat a customer as a member because the list has entries: cancelled memberships are in it too. To gate on a plan, check whether an active entry’s sellingPlanIds includes the plan’s ID.
appstle_membership / setting
Customer-level settings tracking trial and dunning state for this customer’s active plans.
The key
setting is used for both Shop-level and Customer-level metafields, but they contain different data structures. The resource type (Shop vs. Customer) distinguishes them.Order metafields
appstle_membership / details
Full membership contract context at the time the order was created. Set on both initial purchase orders and recurring renewal orders.
Customer tags
Customer tags are the primary mechanism for membership access control. Each membership plan has a merchant-configuredcustomerTag that is added to a customer’s Shopify profile when their contract is active.
Plan-based customer tags
A membership whose lines have no selling plan, such as one imported from another app, gets the
customerTag of the plan that matches each line: the one plan that lists the line’s variant or, when no plan lists the variant, the one plan that lists its product. When more than one plan matches, or none, Appstle adds no tag. Appstle checks when the membership is created and each time its contract is updated, and adds the tag only while the membership is active. After that, the tag follows the lifecycle below.
Tag lifecycle
Delayed vs. immediate tag removal
Cross-membership protection
When removing a tag on cancellation, pause or product removal, the app checks all other active contracts for the same customer. If another active contract uses the samecustomerTag, the tag is not removed — the customer retains access.
For example: a customer holds “Basic Monthly” and “Basic Annual”, both using the basic-member tag. Cancelling “Basic Monthly” does not remove the basic-member tag because “Basic Annual” is still active.
Trial-state tags
During a free trial, the plan’scustomerTag is applied — there is no separate trial tag. Trial members get identical access to paying members.
Dunning-state tags
When a billing attempt fails, the plan’scustomerTag may be removed and the tag is tracked in dunningTags. If a retry succeeds, the tag is re-added and access is restored automatically.
A cancelled membership that’s reactivated while its last renewal is unpaid gets its tag once a charge succeeds, not at reactivation, when the store’s Failed Payment Recovery settings have Retry Attempts set and Remove customer tag after last retry attempt turned on. Until then, its status is "active" and its dunning field is true. See the API changelog.
Plan upgrade/downgrade tag swap
When a member changes plans, tags are swapped atomically:- Old plan’s
customerTagis removed - New plan’s
customerTagis added - If the upgrade payment fails, the swap is rolled back: new tag removed, old tag restored, and the billing schedule from before the change put back (see the API changelog)
Order tags
Plan-based order tags
Applied to orders on initial membership purchase and on each renewal billing.First-time order tag
Recurring order tag
Liquid template variables for order tags
BothfirstTimeOrderTag and recurringOrderTag support Liquid template syntax:
Example — dynamic tag with contract info:
membership_gid://shopify/SubscriptionContract/9876
Reading metafields in Liquid
The membership metafields on this page are readable in Liquid templates because they use theappstle_membership namespace without an $app: prefix:
Complete metafield reference
Complete tag reference
FAQ
Can I read membership metafields from my Liquid theme?
Can I read membership metafields from my Liquid theme?
Yes. The membership metafields on this page use the
appstle_membership namespace without a $app: prefix, so they are accessible in Liquid via {{ shop.metafields.appstle_membership.setting }}, {{ customer.metafields.appstle_membership.subscriptions }}, and so on.What happens when a member cancels mid-billing-cycle?
What happens when a member cancels mid-billing-cycle?
By default (
immediateTagRemoveOnCancel=false), the customer keeps their membership tag until nextBillingDate. They retain access for the period they have already paid for. Set immediateTagRemoveOnCancel=true to remove access immediately on cancellation.What if a customer has the same tag from two different memberships?
What if a customer has the same tag from two different memberships?
The app has cross-membership protection. When removing a tag due to cancellation or pause, it checks whether any other active contract for this customer uses the same tag. If so, the tag is not removed and the customer retains access.
How quickly are customer metafields updated?
How quickly are customer metafields updated?
Customer metafield updates are queued and processed asynchronously. Typical latency is a few seconds, but during high-traffic periods it may take longer.
Do trial members get the same tag as paying members?
Do trial members get the same tag as paying members?
Yes. During a free trial, the plan’s
customerTag is applied — there is no separate trial tag. Trial members get the same access as paying members.What happens during dunning (failed payment)?
What happens during dunning (failed payment)?
When a billing attempt fails, the plan’s
customerTag may be removed and the member loses access. The dunningTags field tracks which tags are in dunning. If a retry succeeds, the tag is re-added and access is restored automatically.Next steps
Sell from a custom page
Add a membership to the cart from your own page.
JavaScript events
Embed the customer portal on your own page and start it from your code.
Webhooks
Receive membership lifecycle and billing events on your server.
API changelog
Dated changes to the customer tags, the Memberships APIs, webhooks and Flow, with what to do about each.