🏷️ Metafields & Tags

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

Metafields are set on four Shopify resource types:

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

Shop metafields store the app's configuration and are used by the storefront widget, checkout extensions, and build-a-box features. They are written by SubscribeItScriptUtils.updateShopMetafieldsForSettings() whenever a merchant saves settings.

When updated: On every settings save in the Appstle admin, and on selling plan or bundle configuration changes. Updates are synchronous (immediate).

{
  "widgetEnabled": true,
  "sellingPlans": [...],
  "assetPaths": {
    "js": "https://cdn.appstle.com/...",
    "css": "https://cdn.appstle.com/..."
  },
  "labels": {...},
  "validationRules": {...}
}

Note: The key uses camelCase (all_Selling_Plans) — this is intentional and must not be changed.

{
  "preventDuplicateSubscriptions": true,
  "maxSubscriptionsPerCustomer": 5,
  "rules": [...]
}

Build-a-box bundles use multiple metafield keys for configuration, styling, and validation.

Build-a-box metafields are set by SubscriptionBundlingServiceImpl.handleMetafieldInputBuildABoxInfo(). The bab_info_* keys are zero-indexed — if a merchant has 3 bundles, the keys will be bab_info_0, bab_info_1, and bab_info_2.

{
  "frequencyCount": 1,
  "frequencyInterval": "MONTH",
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "discountType": "PERCENTAGE",
  "discountValue": 10.0
}

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

{
  "customer": {
    "id": "gid://shopify/Customer/1234567890"
  },
  "subscriptionContract": {
    "id": "gid://shopify/SubscriptionContract/9876543210",
    "status": "ACTIVE",
    "sellingPlanIds": ["gid://shopify/SellingPlan/111"],
    "sellingPlanNames": ["Monthly Subscription - 10% off"],
    "variantIds": ["gid://shopify/ProductVariant/222"],
    "variantNames": ["Default Title"],
    "currentCycle": 3,
    "groupPlanNames": ["Subscribe & Save"],
    "cancellationReason": null
  },
  "lineItems": [
    {
      "variantId": "gid://shopify/ProductVariant/222",
      "title": "Premium Coffee Beans",
      "productId": "gid://shopify/Product/333",
      "sellingPlanId": "gid://shopify/SellingPlan/111",
      "sellingPlanName": "Monthly Subscription - 10% off",
      "sku": "COFFEE-PREMIUM-1KG"
    }
  ],
  "firstOrder": {
    "id": "gid://shopify/Order/444",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

[
  {
    "id": "gid://shopify/SubscriptionContract/9876543210",
    "status": "ACTIVE",
    "sellingPlanNames": ["Monthly Subscription - 10% off"],
    "nextBillingDate": "2025-04-15T10:30:00Z",
    "lineItems": [
      {
        "title": "Premium Coffee Beans",
        "variantId": "gid://shopify/ProductVariant/222",
        "sku": "COFFEE-PREMIUM-1KG"
      }
    ]
  }
]

Important: Customer metafield updates are asynchronous. The main app queues the update via SQS, and subscription-async processes it. There may be a delay of a few seconds between a contract change and the metafield reflecting that change.

Appstle Subscriptions applies tags to Orders and Customers. All tags are merchant-configurable through the Appstle admin under Settings.

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

Order tags are static strings (no Liquid template support) that identify whether an order is the initial subscription order or a recurring billing order.

1. Go to Appstle Admin → Settings
2. Find the Order Tags section
3. Enter your desired tag values (or keep the defaults)
4. Save settings

Backfill endpoint: If you need to apply tags to orders that were created before tags were configured, use the MiscellaneousResource.applyMissedOrderTags() API endpoint to backfill missed tags.

Customer tags are dynamic — they change as subscription status changes. They support Liquid template syntax with access to subscription data variables, enabling highly customized tags.

Customer tags follow a strict priority hierarchy — only one status tag is active at a time:

ACTIVE > PAUSED > INACTIVE

When status changes:

1. The previous status tag is removed (TagsRemoveMutation)
2. The new status tag is added (TagsAddMutation)
3. The applied tag is tracked in the database (SubscriptionContractDetails.customerTag column)

Processing locations:

• subscription app: SubscriptionContractDetailsServiceImpl.updateCustomerTags()
• subscription-async: AbstractSubscriptionService.updateCustomerTags() — triggered from contract creation, status changes, and subscription events
• Deferred updates: Via AWS Step Functions state machine for batched/delayed processing

Customer tags support Liquid template syntax, allowing you to create dynamic, data-driven tags. Wrap variables in double curly braces: {{variable}}.

Line item variables (available within the contract context):

Static tag (default behavior):

appstle_subscription_active_customer

Dynamic tag with selling plan name:

active_subscriber_{{contract.sellingPlanNames}}

Result: active_subscriber_Monthly Subscription - 10% off

Dynamic tag with cycle count:

subscriber_cycle_{{contract.currentCycle}}

Result: subscriber_cycle_3

Dynamic tag with product SKU:

subscribed_to_{{contract.variantNames}}

Result: subscribed_to_Default Title

1. Go to Appstle Admin → Settings
2. Find the Customer Tags section
3. Enter your desired tag templates for each status (Active, Paused, Inactive)
4. Use Liquid variables for dynamic tags, or plain text for static tags
5. Save settings

In addition to metafields and tags, Appstle supports Shopify's native customAttributes on subscription contracts. These are key-value pairs that can be transferred from the original order.

These settings control whether data from the original order is copied to the subscription contract:

Configure these in Appstle Admin → Settings.