Seal Subscriptions Merchant JavaScript API Documentation
What is the Seal Subscriptions Merchant JavaScript API?
JavaScript API documentation explains how to use various JavaScript events and methods in Shopify shops, which have the Seal Subscriptions app installed.When a subscription widget gets created
When a subscription widget is created by the Seal Subscriptions app, a custom JavaScript event called sealsubs:subscription_widget_created will be triggered.Here is how you can configure a listener for said event:
// This event will be fired for each subscription widget that gets created
document.addEventListener('sealsubs:subscription_widget_created', function(e) {
// Subscription widget was created
// Do your magic :)
});
When the price in auto-charging widget has changed
When a customer selects a different subscription option in auto-charging widget, an event will be triggered with the info about the newest product price.Here is how you can configure a listener for said event:
// This event will be fired whenever a different subscription option is selected
document.addEventListener('sealsubs:price_update', function(e) {
// e.detail will contain the following JSON object:
// {
// price : currentPrice, // Represents the current product price (including discounts)
// compareAtPrice : compareAtPrice, // Represents the "compare at price" for the product (without discounts)
// element : subscriptionWidgetElement, // Contains an HTML element of the widget where this change happened
// pricePerDelivery: pricePerDelivery // Represents the price per delivery (for prepaid subscriptions)
// pricePerUnit contains price per unit info for stores in some European countries (Germany, France, etc.). ->
// The widget has to be installed to allow the app to calculate these values. ->
// Will be empty if the shop is not eligible for this calculations.
// pricePerUnit : {
// pricePerUnit : (integer), // Represents the price per unit in cents (e.g. 5000)
// unit : (string), // Represents the unit (e.g. kg)
// pricePerUnitFormatted : (string) // Represents the formatted price per unit (e.g. 18,00€/kg)
// }
// }
});
When a different selling plan was selected in auto-charging widget
When a customer selects a different subscription option in auto-charging widget, an event will be triggered with the info about the selected selling plan.Here is how you can configure a listener for said event:
// This event will be fired whenever a different selling plan is selected
document.addEventListener('sealsubs:selling_plan_changed', function(e) {
// e.detail will contain the following JSON object:
// {
// selling_plan_id : sellingPlanId, // Represents the ID of the selected selling plan
// element : subscriptionWidgetElement // Contains an HTML element of the widget where this change happened
// }
});
Change the selected selling plan in auto-charging widget
You can use the "sealsubs:change_selected_selling_plan_id" event to trigger a selection of a different selling plan in an auto-charging subscription widget. The event has to be triggered on the subscription widget's HTML element. And you can use the same event to select the "one-time" purchase option in there, simply by passing an empty string through the selling_plan_id parameter.Here is how you can use this event:
var event = new CustomEvent("sealsubs:change_selected_selling_plan_id", {
detail: {
selling_plan_id: sellingPlanId // Pass the desired selling plan ID
}
});
widgetElement.dispatchEvent(event);
And here is a sample code on how to sync the subscription selection between multiple same widgets on the same page:
function updateWidgetSellingPlan(widgetElement, sellingPlanId) {
var event = new CustomEvent("sealsubs:change_selected_selling_plan_id", {
detail: { selling_plan_id: sellingPlanId }
});
widgetElement.dispatchEvent(event);
}
// Event listener for when a selling plan is changed in any widget
document.addEventListener('sealsubs:selling_plan_changed', function(e) {
const { selling_plan_id, element } = e.detail;
// Query all subscription widgets on the page
const allWidgets = document.querySelectorAll('.sealsubs-target-element');
allWidgets.forEach(widget => {
// Skip the widget where the change originated
if (widget !== element) {
updateWidgetSellingPlan(widget, selling_plan_id);
}
});
});
How to add subscription widget anywhere on the page
To add a subscription widget anywhere on the page (e.g. for integration with third party apps), you just have to add the following HTML snippet to the desired location:<!-- This is the bare minimum HTML snippet to show the widget -->
<div class="sealsubs-target-element" data-handle="{{ product.handle }}"></div>
<!-- The data-handle attribute should contain the product handle. The code here is prepared for Liquid processor, but you can set the value in any way you want (e.g. with JavaScript) --><!-- The recommended HTML snippet, as it also includes the data-product attribute -->
<div class="sealsubs-target-element" data-product="{{ product | json | escape }}" data-handle="{{ product.handle }}"></div>And then, if the app was already loaded, call the SealSubs.refresh() method:
if (typeof window.SealSubs !== 'undefined' && typeof window.SealSubs.refresh === 'function') {
window.SealSubs.refresh();
}The Seal Subscriptions app will then render the subscription widget for the product, if the product has any subscription rules configured. When you add the product to the cart, make sure to include values all input elements from the subscription widget in the request.
The input element for auto-charging rules will contain a selling_plan property, while the input elements for recurring invoice subscriptions will contain line item properties.