🏷️ Metafields & Tags

All metafields use the namespace appstle_membership and are managed through the Shopify GraphQL Admin API (MetafieldsSetMutation).

Metafields are set on three Shopify resource types:

Namespace visibility: All membership metafields use the appstle_membership namespace (no $app: prefix), which means they are readable by other apps, themes, and Liquid templates.

Shop metafields store the membership program configuration and are used by the storefront for access gating, checkout validation, and widget rendering.

When updated: On every settings save in the Appstle admin. Updates are synchronous (immediate).

[
  {
    "id": "gid://shopify/SellingPlan/111",
    "name": "Basic Monthly Membership",
    "billingPolicy": {
      "interval": "MONTH",
      "intervalCount": 1
    },
    "customerTag": "basic-member",
    "orderTag": "membership-order"
  },
  {
    "id": "gid://shopify/SellingPlan/222",
    "name": "Premium Annual Membership",
    "billingPolicy": {
      "interval": "YEAR",
      "intervalCount": 1
    },
    "customerTag": "premium-member",
    "orderTag": "premium-membership-order"
  }
]

{
  "basic-member": {
    "accessibleCollections": ["gid://shopify/Collection/111"],
    "accessibleProducts": [],
    "gatingType": "COLLECTION"
  },
  "premium-member": {
    "accessibleCollections": ["gid://shopify/Collection/111", "gid://shopify/Collection/222"],
    "accessibleProducts": ["gid://shopify/Product/333"],
    "gatingType": "COLLECTION_AND_PRODUCT"
  }
}

How gating works: The storefront reads this metafield and the customer's tags to determine what content is visible. If a customer has the premium-member tag, they see all products and collections mapped to that tag. Non-members or lower tiers see gated content as locked/hidden.

Multi-language support: For non-default locales, labels are NOT stored as separate metafields. Instead, the app fetches the existing default-locale metafield ID and registers a Shopify Translation on it (using TranslationsRegisterMutation). This leverages Shopify's built-in translation system.

This metafield contains a complete snapshot of the membership context at the time the order was created:

{
  "customer": {
    "id": "gid://shopify/Customer/1234567890",
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "subscriptionContract": {
    "id": "gid://shopify/SubscriptionContract/9876543210",
    "status": "ACTIVE",
    "sellingPlanIds": ["gid://shopify/SellingPlan/111"],
    "sellingPlanNames": ["Premium Monthly Membership"],
    "variantIds": ["gid://shopify/ProductVariant/222"],
    "variantNames": ["Premium Membership"]
  },
  "firstOrder": {
    "id": "gid://shopify/Order/444",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

[
  {
    "id": "gid://shopify/SubscriptionContract/9876543210",
    "status": "ACTIVE",
    "sellingPlanIds": ["gid://shopify/SellingPlan/111"],
    "sellingPlanNames": ["Premium Monthly Membership"],
    "variantIds": ["gid://shopify/ProductVariant/222"],
    "variantNames": ["Premium Membership"],
    "nextBillingDate": "2025-04-15T10:30:00Z"
  }
]

{
  "trialTags": "basic-member,premium-member",
  "dunningTags": "premium-member"
}

Note: The same 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.

Appstle Memberships applies tags to both Customer and Order resources. Customer tags are the primary mechanism for membership access control — they determine which content, products, and collections a member can access.

All tags are applied using the Shopify GraphQL Admin API (TagsAddMutation / TagsRemoveMutation).

This is the core tag mechanism for Appstle Memberships. Each selling plan (membership tier) has a merchant-configured customerTag that controls access.

Merchants can configure when tags are removed on cancellation or pause:

Best practice: Keep the defaults (false) to ensure members retain access for the period they've already paid for. Only set to true if your membership grants access to ongoing services (not prepaid periods).

When removing a customer tag on cancel/pause, the app checks all other active memberships for the same customer. If another active contract uses the same customerTag, the tag is not removed.

Method: getCustomerTagsForOtherActiveMembership() — ensures a customer who holds the same membership tag from two different contracts doesn't lose access when one is cancelled.

A customer has two contracts:

1. "Basic Monthly" → customerTag: basic-member (ACTIVE)
2. "Basic Annual" → customerTag: basic-member (ACTIVE)

If the customer cancels "Basic Monthly", the basic-member tag is not removed because "Basic Annual" is still active.

During a free trial:

• The plan's customerTag is applied (member gets access during trial)
• The tag is tracked in the customer's setting metafield under trialTags
• When the trial ends (expires without payment), the tag is removed

Key point: Trial members get the same tag as paying members. There is no separate "trial" tag — access is identical. The trialTags field in the customer metafield is for internal tracking only.

When a billing attempt fails:

• The plan's customerTag may be removed (member loses access during dunning)
• The tag is tracked in the customer's setting metafield under dunningTags
• If payment succeeds on retry, the tag is re-added

When a member changes plans (variant swap), tags are swapped in a single operation:

Rollback method: SubscriptionBillingAttemptService.rollbackCustomerTags() (membership-async)

Both firstTimeOrderTag and recurringOrderTag support Liquid template syntax using the TagModel:

Static tag:

membership_first_order

Dynamic tag with contract info:

membership_{{subscriptionContract.id}}

Result: membership_gid://shopify/SubscriptionContract/9876

When transferOrderNoteAttributesToSubscription is enabled (default: true), the app transfers the original order's customAttributes (note attributes) to each renewal order. These are not tags but Shopify's native key-value pairs on orders.