Skip to main content

Documentation Index

Fetch the complete documentation index at: https://appstleinc-aeca3e0a.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Appstle Subscriptions uses Shopify metafields and tags to store subscription data, power the storefront widget, and enable automation workflows. All metafields use the namespace appstle_subscription without an $app: prefix, which means they are publicly readable by other apps, themes, and Liquid templates.

​
Metafields overview

Metafields are set on four Shopify resource types:
ResourceKeysVisibilityPurpose
Shop15+PublicWidget settings, selling plans, Build-a-Box configuration
Selling Plan1PublicIndividual selling plan metadata
Order1PublicSubscription context for each order
Customer1PublicAll subscription contracts for the customer

​
Shop metafields

Shop metafields store the app’s configuration and are written whenever a merchant saves settings in the Appstle admin. Updates are synchronous (immediate).

​
appstle_subscription / setting

PropertyValue
Typejson
PurposeCore widget and app configuration — UI settings, asset paths, selling plans, labels, and validation rules
Updated whenMerchant saves settings
{
  "widgetEnabled": true,
  "sellingPlans": [],
  "assetPaths": {
    "js": "https://cdn.appstle.com/...",
    "css": "https://cdn.appstle.com/..."
  },
  "labels": {},
  "validationRules": {}
}

​
appstle_subscription / labels

PropertyValue
Typemulti_line_text_field
PurposeLocalized UI labels and translations for the subscription widget
Updated whenMerchant saves label translations

​
appstle_subscription / shop_info

PropertyValue
Typejson
PurposeShop metadata including money format, feature flags, and API tokens

​
appstle_subscription / selling_plans

PropertyValue
Typejson
PurposeFree-product selling plans only

​
appstle_subscription / all_Selling_Plans

PropertyValue
Typejson
PurposeAll selling plans including paid plans
The key uses mixed case (all_Selling_Plans) — this is intentional and must not be changed.

​
appstle_subscription / checkout_validation

PropertyValue
Typejson
PurposeCheckout validation rules including duplicate subscription restrictions and per-customer limits
{
  "preventDuplicateSubscriptions": true,
  "maxSubscriptionsPerCustomer": 5,
  "rules": []
}

​
Widget templates

KeyTypePurpose
widget_template_htmlmulti_line_text_fieldCustom widget template HTML (only set when a custom template is configured)
all_widget_template_htmljsonMap of all available widget templates

​
Build-a-Box metafields

KeyTypePurpose
bundlejsonBundle/Build-a-Box configuration
bab_subscription_cssjsonBuild-a-Box subscription CSS styles
bab_customization_cssjsonBuild-a-Box customization CSS
bab_validation_infojsonBuild-a-Box validation rules
bab_setting_infojsonBuild-a-Box settings
bab_info_0, bab_info_1, …jsonIndividual bundle details, one per enabled bundle (zero-indexed)
total_babintegerTotal count of enabled Build-a-Box bundles
The bab_info_* keys are zero-indexed. A store with three bundles has keys bab_info_0, bab_info_1, and bab_info_2.

​
Selling plan metafields

​
appstle_subscription / selling_plan

PropertyValue
Typejson
ResourceSelling Plan
PurposeIndividual selling plan metadata — frequency, billing policy, discounts
Updated whenSelling plan is created or modified
{
  "frequencyCount": 1,
  "frequencyInterval": "MONTH",
  "billingPolicy": {
    "interval": "MONTH",
    "intervalCount": 1
  },
  "discountType": "PERCENTAGE",
  "discountValue": 10.0
}

​
Order metafields

​
appstle_subscription / details

PropertyValue
Typejson
ResourceOrder
PurposeFull subscription contract context at the time the order was created
Updated whenOrder is created via subscription (initial or recurring billing)
Update timingAsynchronous — typically a few seconds after the order is 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"
  }
}

​
Customer metafields

​
appstle_subscription / subscriptions

PropertyValue
Typejson
ResourceCustomer
PurposeAll subscription contracts for this customer with full details
Updated whenAny contract changes — created, updated, paused, cancelled, billing attempt
Update timingAsynchronous — typically a few seconds after any contract change
[
  {
    "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"
      }
    ]
  }
]
Customer metafield updates are asynchronous. There may be a delay of a few seconds between a contract change and the metafield reflecting that change. Do not rely on this metafield for real-time data in time-sensitive operations.

​
Using metafields in Liquid

All metafields use the appstle_subscription namespace without an $app: prefix, so they are accessible directly in Liquid: 
{{ shop.metafields.appstle_subscription.setting }}
{{ customer.metafields.appstle_subscription.subscriptions }}

​
Order tags

Order tags are static strings applied to identify the type of subscription order. They are never removed once applied.
TagConfig fieldDefault valueApplied when
First-time orderfirstTimeOrderTagappstle_subscription_first_orderInitial subscription order is created
Recurring orderrecurringOrderTagappstle_subscription_recurring_orderEach subsequent billing order is created
Configure tags in Appstle Admin → Settings → Order Tags.
If you need to apply tags to orders created before you configured tags, use the applyMissedOrderTags API endpoint to backfill them.

​
Customer tags

Customer tags are dynamic — they change as subscription status changes. They follow a strict priority hierarchy: Active > Paused > Inactive. Only one status tag is active at a time.
StatusConditionConfig fieldDefault value
ActiveCustomer has 1+ active contractscustomerActiveSubscriptionTagappstle_subscription_active_customer
PausedCustomer has paused contracts but no active onescustomerPausedSubscriptionTagappstle_subscription_paused_customer
InactiveAll contracts cancelledcustomerInActiveSubscriptionTagappstle_subscription_inactive_customer
Tags are updated on every subscription lifecycle event: contract created, paused, resumed, cancelled, and billing attempts.

​
Liquid template variables

Customer tags support Liquid template syntax. Wrap variables in double curly braces: 
active_subscriber_{{contract.sellingPlanNames}}
Available variables:
VariableTypeDescriptionExample
{{customer.id}}StringShopify customer GIDgid://shopify/Customer/1234567890
{{contract.id}}StringSubscription contract GIDgid://shopify/SubscriptionContract/9876
{{contract.sellingPlanIds}}StringComma-separated selling plan IDsgid://shopify/SellingPlan/111
{{contract.sellingPlanNames}}StringComma-separated selling plan namesMonthly Subscription - 10% off
{{contract.variantIds}}StringComma-separated variant IDsgid://shopify/ProductVariant/222
{{contract.variantNames}}StringComma-separated variant namesDefault Title
{{contract.currentCycle}}NumberCurrent billing cycle number3
{{contract.cancellationReason}}StringCancellation reason if cancelledToo expensive
{{order.id}}StringFirst order GIDgid://shopify/Order/444
{{order.createdAt}}StringFirst order creation date (ISO 8601)2025-01-15T10:30:00Z
Template examples: 
# 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 variant name
subscribed_to_{{contract.variantNames}}
# Result: subscribed_to_Default Title

​
Complete metafield reference

ResourceNamespaceKeyType
Shopappstle_subscriptionsettingjson
Shopappstle_subscriptionwidget_template_htmlmulti_line_text_field
Shopappstle_subscriptionall_widget_template_htmljson
Shopappstle_subscriptionbundlejson
Shopappstle_subscriptionlabelsmulti_line_text_field
Shopappstle_subscriptionselling_plansjson
Shopappstle_subscriptioncheckout_validationjson
Shopappstle_subscriptionbab_subscription_cssjson
Shopappstle_subscriptionbab_customization_cssjson
Shopappstle_subscriptionshop_infojson
Shopappstle_subscriptionbab_validation_infojson
Shopappstle_subscriptionbab_setting_infojson
Shopappstle_subscriptionall_Selling_Plansjson
Shopappstle_subscriptionbab_info_[0-N]json
Shopappstle_subscriptiontotal_babinteger
Selling Planappstle_subscriptionselling_planjson
Orderappstle_subscriptiondetailsjson
Customerappstle_subscriptionsubscriptionsjson

​
FAQ

Yes. All subscription metafields use the appstle_subscription namespace without an $app: prefix, so they are accessible in Liquid via {{ shop.metafields.appstle_subscription.setting }}, {{ customer.metafields.appstle_subscription.subscriptions }}, and so on.
Customer metafield updates are processed asynchronously. Typical latency is a few seconds, but during high-traffic periods it may take a bit longer.
Tags follow the priority hierarchy Active > Paused > Inactive. If a customer has both active and paused subscriptions, the active tag takes precedence. The inactive tag is only applied when all contracts are cancelled.
Yes. Use the applyMissedOrderTags API endpoint to apply tags to orders that were created before your tag configuration was set up.