# JavaScript Hooks & Events

Appstle Subscription emits JavaScript events that you can listen to for custom integrations, analytics tracking, or dynamic UI updates on your storefront.

## How to Listen

All events are dispatched on both `document` and `window`, so you can listen on either:

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

## Subscription Widget Events

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 (variant change, etc.) | 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 |
| `appstle_widget_updated` | Widget DOM is updated (jQuery event on `document`) | — |


## Cart Widget Events

| 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 | — |


## Examples

### Track subscription selections in analytics

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

### Show custom UI when widget loads

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

### React to cart subscription changes

```javascript
document.addEventListener('AppstleSubscription:SubscriptionWidget:SwitchedToSubscription', function(event) {
  console.log('Item switched to subscription:', event.detail);
  // Update custom cart UI
});

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

### Embed customer portal after it's ready

```javascript
document.addEventListener('AppstleSubscription:CustomerPortal:ReadyToEmbed', function() {
  // Custom logic before embedding
  console.log('Customer portal is ready');
});

document.addEventListener('AppstleSubscription:CustomerPortal:Embedded', function() {
  // Custom logic after embedding
  console.log('Customer portal embedded successfully');
});
```

Source
These events are dispatched by `appstle-subscription.js` which is automatically loaded on your storefront when the Appstle Subscriptions app is installed.