Skip to main content
Appstle Memberships uses Shopify metafields and customer tags to store membership data, power storefront access gating, and drive checkout validation. This reference covers every metafield and tag you can use — what it contains, when it is set, and how to use it in your integration or Liquid theme. Every metafield on this page uses the namespace 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.
sellingPlanIds, variantIds, sellingPlanNames and variantNames are sets. Each holds a value once even when several lines share it, their order is arbitrary and can change when the lines change, and they don’t line up: the third name doesn’t belong to the third ID.
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 writes this metafield after an event, so it can be a few seconds behind a membership’s real state. For a membership’s current state, read it with Appstle’s Admin API.

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-configured customerTag 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 same customerTag, 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’s customerTag 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’s customerTag 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:
  1. Old plan’s customerTag is removed
  2. New plan’s customerTag is added
  3. 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

Both firstTimeOrderTag and recurringOrderTag support Liquid template syntax: Example — dynamic tag with contract info:
Result: membership_gid://shopify/SubscriptionContract/9876

Reading metafields in Liquid

The membership metafields on this page are readable in Liquid templates because they use the appstle_membership namespace without an $app: prefix:

Complete metafield reference

Complete tag reference

FAQ

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.
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.
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.
Customer metafield updates are queued and processed asynchronously. Typical latency is a few seconds, but during high-traffic periods it may take longer.
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.
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.