JavaScript events for the Appstle storefront widget

Appstle Subscriptions dispatches JavaScript events from appstle-subscription.js, which is automatically injected into your storefront when the app is installed. You can listen to these events to track subscription interactions in analytics tools, show or hide custom UI, and react to customer actions in the cart and portal. All events are dispatched on both document and window, so you can attach listeners to either.

document.addEventListener('AppstleSubscription:SubscriptionWidget:SellingPlanSelected', function(event) {
  console.log('Selling plan selected, widget ID:', event.detail);
});

These events are dispatched by appstle-subscription.js, which loads automatically on your storefront once the Appstle Subscriptions app is installed. No additional configuration is required to start listening.

These events fire when customers interact with the subscription widget on product pages.

Event name	Fires when	`event.detail`
`AppstleSubscription:SubscriptionWidget:widgetInitialised`	Widget loads on a product page	Widget ID
`AppstleSubscription:SubscriptionWidget:SubscriptionWidgetUpdated`	Widget is re-rendered (e.g. on variant change)	Widget ID
`AppstleSubscription:SubscriptionWidget:SellingPlanSelected`	Customer selects a subscription option	Widget ID
`AppstleSubscription:SubscriptionWidget:SellingPlanRemoved`	Subscription selling plan is removed from cart	Widget ID
`AppstleSubscription:SubscriptionWidget:SellingPlanDeSelected`	Customer switches away from subscription	Widget ID
`AppstleSubscription:SubscriptionWidget:sellingPlanChanged`	Customer changes the selling plan (frequency, etc.)	Selling Plan ID
`AppstleSubscription:SubscriptionWidget:AddToCartIntent`	Customer initiates an add-to-cart with a subscription plan selected (fires before the cart request)	`{ trigger: 'form_submit' \| 'fetch_form_data' \| 'appstle_add_to_cart', widgetId?: string }`
`appstle_widget_updated`	Widget DOM is updated (jQuery event on `document`)	—

Event name	Fires when	`event.detail`
`AppstleSubscription:CartWidget:Updated`	Cart widget is updated	—
`AppstleSubscription:SubscriptionWidget:SwitchedToOneTime`	Customer switches a cart item from subscription to one-time	Line item key
`AppstleSubscription:SubscriptionWidget:SwitchedToSubscription`	Customer switches a cart item from one-time to subscription	Line item key

Customer portal events

Event name	Fires when	`event.detail`
`AppstleSubscription:CustomerPortal:ReadyToEmbed`	Customer portal is ready to be embedded	—
`AppstleSubscription:CustomerPortal:Embedded`	Customer portal has been embedded in the page	—

Build-a-Box events

Event name	Fires when	`event.detail`
`AppstleSubscription:Bab:Embedded`	Build-a-Box widget has been embedded	—
`appstleBundlesAppliedVolumeDiscount:request`	Volume discount is requested for bundles	`true`

Other events

Event name	Fires when	`event.detail`
`OpenAppstleContracts`	Request to open the contracts/subscriptions view	—

Code examples

Track subscription selections in analytics

document.addEventListener('AppstleSubscription:SubscriptionWidget:SellingPlanSelected', function(event) {
  // Google Analytics 4
  gtag('event', 'subscription_selected', {
    widget_id: event.detail
  });
});

document.addEventListener('AppstleSubscription:SubscriptionWidget:widgetInitialised', function(event) {
  const banner = document.querySelector('.my-custom-subscription-banner');
  if (banner) {
    banner.style.display = 'block';
  }
});

React to cart subscription changes

document.addEventListener('AppstleSubscription:SubscriptionWidget:SwitchedToSubscription', function(event) {
  console.log('Item switched to subscription, line item key:', event.detail);
  // Update custom cart UI, apply promotions, etc.
});

document.addEventListener('AppstleSubscription:SubscriptionWidget:SwitchedToOneTime', function(event) {
  console.log('Item switched to one-time, line item key:', event.detail);
});

Run custom logic around customer portal embedding

document.addEventListener('AppstleSubscription:CustomerPortal:ReadyToEmbed', function() {
  // Run setup logic before the portal renders
  console.log('Customer portal is ready to embed');
});

document.addEventListener('AppstleSubscription:CustomerPortal:Embedded', function() {
  // Run post-render logic, e.g. hide a loading spinner
  const loader = document.querySelector('.portal-loader');
  if (loader) loader.remove();
});

Track selling plan changes

document.addEventListener('AppstleSubscription:SubscriptionWidget:sellingPlanChanged', function(event) {
  const newSellingPlanId = event.detail;
  console.log('Customer changed to selling plan:', newSellingPlanId);

  // Update UI to reflect new frequency/discount
});

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

JavaScript events for the Appstle storefront widget

Subscription widget events

Cart widget events

Customer portal events

Build-a-Box events

Other events

Code examples

Track subscription selections in analytics

Show custom UI when the widget loads

React to cart subscription changes

Run custom logic around customer portal embedding

Track selling plan changes

​Subscription widget events

​Cart widget events

​Customer portal events

​Build-a-Box events

​Other events

​Code examples

​Track subscription selections in analytics

​Show custom UI when the widget loads

​React to cart subscription changes

​Run custom logic around customer portal embedding

​Track selling plan changes

Subscription widget events

Cart widget events

Customer portal events

Build-a-Box events

Other events

Code examples

Track subscription selections in analytics

Show custom UI when the widget loads

React to cart subscription changes

Run custom logic around customer portal embedding

Track selling plan changes