Subi JavaScript SDK

Put the subscription widget where your theme does not, and follow what the shopper picks.

  • Objectwindow.subifySdk
  • Version5
  • Runs inthe shopper's browser
  • Keynone needed
JavaScript SDK

Overview

The Subi JavaScript SDK draws the Subi subscription widget on a storefront and tells your code what the shopper picks in it. Use it to show the widget where a theme does not put it by itself: a landing or collection page, a featured product, a quick-buy window.

On any page other than a product page, the widget appears only when Display subscription widget on home page and other pages is turned on in Subi's widget display settings. With it off, renderWidget draws nothing there. A headless mount is not affected.

It runs in the shopper's browser and needs no key. Once loaded it puts one object on the page, window.subifySdk, and sends its events on window.

Why the code says subify. The names in the code keep subify, the app's earlier name. They stay as they are, so code already written against them keeps working.

On a headless storefront such as Hydrogen or Next.js, start with Headless storefronts.

Quick start
function whenSubiReady(run) {
  if (window.subifySdk) return run(window.subifySdk);
  window.addEventListener("subify:sdkLoaded",
    () => run(window.subifySdk), { once: true });
}

whenSubiReady((sdk) => {
  sdk.renderWidget("classic-blue-jeans", {
    renderPosition: { wrapper: ".widget-wrapper" }
  });
});

window.addEventListener("subify:sellingPlanChange", (event) => {
  // null when the shopper picks a one-time purchase
  console.log(event.detail.sellingPlanGid);
});
Getting started

Loading the SDK

The SDK loads by itself when Subi's app embed is turned on in your theme (Online Store, Themes, Customize, App embeds). You add nothing.

On a headless storefront, or with the app embed turned off, load it with the script tag in the first example.

The subify:sdkLoaded event is sent only once. If your code may run after the SDK has already loaded, check window.subifySdk first and listen for the event only when it is not there yet, as the second example does.

Script tag
<script
  src="https://cdn.subi.co/subify/v5/subify-sdk.js"
  defer
></script>
Wait for the SDK
function whenSubiReady(run) {
  if (window.subifySdk) return run(window.subifySdk);
  window.addEventListener("subify:sdkLoaded",
    () => run(window.subifySdk), { once: true });
}
Method

renderWidget

window.subifySdk.renderWidget(product, configs)

Draws the subscription widget for one product inside an element of the page you choose. Outside a product page it draws only when Display subscription widget on home page and other pages is on in Subi's widget display settings.

Parameters

productstring | objectrequired
The product's handle, the short name in its address (a product called Classic Blue Jeans usually has the handle classic-blue-jeans), or a Shopify product object with its details.
configsobjectoptional
Where the widget goes and how it works with your page. Every key is optional.
renderPositionobjectoptional
Where the widget is drawn.
wrapperstring
The CSS selector of the element that holds the widget.
position"APPEND" | "PREPEND"default "APPEND"
Last in that element with APPEND, first with PREPEND.
sellingPlanInputobjectoptional
Where the SDK places the hidden input that carries the chosen subscription option into your add-to-cart form, such as <input type="hidden" name="selling_plan" value="692456128832">.
wrapperstring
The selector of the element the input goes in.
idstringoptional
An id of your own for the input.
useCartApibooleanoptional
On a Shopify theme storefront, set it to true when your page adds to the cart with a script (a fetch or XMLHttpRequest call to Shopify's /cart/add) instead of submitting a form, and the SDK adds the chosen selling_plan to that call for you. It does nothing on a headless storefront, where your own code puts the plan on the cart line.
Check your site after turning on useCartApi. To add the plan to your own cart calls, the SDK wraps the browser's fetch and XMLHttpRequest. Test that everything else on your site still works.
Render the widget
window.subifySdk.renderWidget("classic-blue-jeans", {
  renderPosition: {
    wrapper: ".widget-wrapper",
    position: "APPEND"
  }
});
configs
{
  renderPosition?: {
    wrapper: string;
    position?: "APPEND" | "PREPEND";
  };
  sellingPlanInput?: {
    wrapper: string;
    id?: string;
  };
  useCartApi?: boolean;
}
Method

changeVariant

window.subifySdk.changeVariant(targetProductId, selectedVariantId)

Tells the widget that a different variant is selected. Call it when your page picks variants in a way the SDK does not follow by itself, or when you change the variant from your own code.

Parameters

targetProductIdnumber | stringrequired
The product's ID: a number, or on a headless storefront its Storefront API ID such as gid://shopify/Product/123.
selectedVariantIdnumber | stringrequired
The ID of the variant to select, in the same two forms.
Select a variant
window.subifySdk.changeVariant(12345, 1234567);
Event

subify:sdkLoaded

Sent once on window, when the SDK has finished loading and window.subifySdk is ready.

Because it is sent only once, code that may run later should check window.subifySdk first (see Loading the SDK).

Listen
window.addEventListener("subify:sdkLoaded", () => {
  // window.subifySdk is ready
});
Event

subify:variantChange

Sent on window when the SDK sees a new variant selected.

event.detail

targetProductIdnumber
The product whose variant changed.
selectedVariantIdnumber
The variant now selected.
Listen
window.addEventListener("subify:variantChange", (event) => {
  const { targetProductId, selectedVariantId } = event.detail;
});
Event

subify:sellingPlanChange

Sent on window when the widget first shows its selected option, and again each time the shopper picks a different one, a subscription or a one-time purchase.

event.detail

targetProductIdnumber
The product whose option changed.
selectedSellingPlanobject | null
The chosen Shopify selling plan object, or null when the shopper picks the one-time purchase.
sellingPlanGidstring | null
The same plan as a Shopify ID, such as gid://shopify/SellingPlan/692456128832, or null for a one-time purchase.
Listen
window.addEventListener("subify:sellingPlanChange", (event) => {
  const {
    targetProductId,
    selectedSellingPlan,
    sellingPlanGid,
  } = event.detail;
});
Guide

Headless storefronts

On a headless storefront such as Hydrogen or Next.js, the widget mounts with window.subifySdk.mountHeadlessWidget instead of renderWidget, and your own code puts the chosen plan on the cart line.

Follow Adding the Subi widget to a Hydrogen or headless storefront for the step-by-step recipe. changeVariant and the events on this page work there too.

Support

Help

Stuck? Write to [email protected] with your store's address and the page where the widget should appear.