Dev: JavaScript API

All methods are asynchronous and should be called with await or .then(). Every method returns an object with at least a success boolean. On failure, a message.errors object is included with details.

checkIsSubscribed({ email, variantId })

Checks whether a user is subscribed to a product variant by email.

Parameters:

email — string, user email
variantId — string, product variant ID

Returns: { success: Boolean, isSubscribed?: Boolean, message?: Object }

success — true if the request succeeded
isSubscribed — whether the user is currently subscribed
message — present only on failure, contains error details

const res = await window.refactor_apps.back_in_stock.checkIsSubscribed({ 
  email: "user@mail.com",
  variantId: "47891249692922" 
});

const isSubscribed = res?.isSubscribed; // true or false

checkIsSubscribedByCustomerId({ customerId, variantId })

Checks whether a customer is subscribed to a product variant by their Shopify customer ID.

Parameters:

customerId — string, Shopify customer ID
variantId — string, product variant ID

Returns: { success: Boolean, isSubscribed?: Boolean, message?: Object }

success — true if the request succeeded
isSubscribed — whether the customer is currently subscribed
message — present only on failure, contains error details

const res = await window.refactor_apps.back_in_stock.checkIsSubscribedByCustomerId({ 
 customerId: "8780630393082",
 variantId: "47891249692922"
});

const isSubscribed = res?.isSubscribed; // true or false

subscribeOnTheProduct({ productId, variantId, email, customerId? })

Subscribes a user to back-in-stock notifications for a product variant. Passing customerId additionally saves the subscription to the customer's metafield.

Parameters:

productId — string, product ID
variantId — string, product variant ID
email — string, email address to subscribe
customerId — string, optional Shopify customer ID

Returns: { success: Boolean, message?: Object }

success — true if the subscription was created
message — present only on failure, contains error details

const res = await window.refactor_apps.back_in_stock.subscribeOnTheProduct({ 
  productId: "8983368728753",
  variantId: "47891249692922",
  email: "user@mail.com",
  customerId: "87806393082" 
});

const ok = res?.success;

unsubscribeFromTheProduct({ productId, variantId, email, customerId? })

Unsubscribes a user from notifications by email. Passing customerId also removes the entry from the customer's metafield.

Parameters:

productId — string, product ID
variantId — string, product variant ID
email — string, email address to unsubscribe
customerId — string, optional Shopify customer ID

Returns: { success: Boolean, message?: Object }

success — true if the unsubscription was successful
message — present only on failure, contains error details

const res = await window.refactor_apps.back_in_stock.unsubscribeFromTheProduct({ 
  productId: "8983368728753",
  variantId: "47891249692922", 
  email: "user@mail.com" 
});

unsubscribeFromTheProductByCustomerId({ productId, variantId, customerId })

Unsubscribes a customer from notifications by customer ID, without needing their email.

Parameters:

productId — string, product ID
variantId — string, product variant ID
customerId — string, Shopify customer ID

Returns: { success: Boolean, message?: Object }

success — true if the unsubscription was successful
message — present only on failure, contains error details

const res = await window.refactor_apps.back_in_stock.unsubscribeFromTheProductByCustomerId({ 
  productId: "8983368728753",
  variantId: "47891249758458", 
  customerId: "8780630393082" 
});

getSubscribers({ variantId })

Returns all subscribers for a given product variant as an object keyed by email address.

Parameters:

variantId — string, product variant ID

Returns: { success: Boolean, subscribers?: Object, message?: Object }

success — true if the request succeeded
subscribers — object where each key is an email address and the value is { customerId, locale, country }
message — present only on failure, contains error details

const res = await window.refactor_apps.back_in_stock.getSubscribers({
 variantId: "47891249692922" 
});

console.log(res.subscribers);

// {
//   "user@mail.com": { customerId: "8780630393082", locale: "en", country: "US",
//   "guest@mail.com": { customerId: null, locale: null, country: null }
// }

getSubscribedProducts({ customerId })

Returns all variant IDs that a specific customer is subscribed to.

Parameters:

customerId — string, Shopify customer ID

Returns: { success: Boolean, variantIds?: Array, message?: Object }

success — true if the request succeeded
variantIds — array of variant ID strings the customer is subscribed to
message — present only on failure, contains error details

const res = await window.refactor_apps.back_in_stock.getSubscribedProducts({
  customerId: "8780630393082" 
});  

console.log(res.variantIds); // ["47891249692922"]

Events

You can listen for subscribe and unsubscribe events on document to react to state changes in your theme.

apps:back-in-stock:subscribed — fires after a successful subscription. The event detail includes { productId, variantId, email, customer } .

apps:back-in-stock:unsubscribed — fires after a successful unsubscription. The event detail includes { productId, variantId, email, customerId } .

apps:back-in-stock:ready — fires when the helper has fully loaded. Use this if you need to run code as soon as the API becomes available.

document.addEventListener("apps:back-in-stock:subscribed", (e) => {
  const { productId, variantId, email, customerId } = e.detail;
});

document.addEventListener("apps:back-in-stock:unsubscribed", (e) => {
  const { productId, variantId, email, customerId } = e.detail;
});

document.addEventListener("apps:back-in-stock:ready", () => {
  // API is ready
});

Alternatively, check window.refactor_apps.back_in_stock.isReady as a boolean property instead of listening for the event.

Dev: Requirements — Refactor Back in Stock

The JavaScript helper is only available in themes where the App Embed Extension has been activated. Without this step, the window.refactor_apps object will not exist on the page.

Activating the App Embed

In your Shopify Admin, go to Online Store → Themes.
Find the theme you want to use and click Customise.
In the left sidebar of the theme editor, click the App embeds icon (it looks like a puzzle piece).
Find Back in Stock in the list.
Toggle it on.
Click Save in the top right corner.

This only needs to be done once per theme. If you publish a new theme or switch themes, repeat these steps for the new one.

Verifying the setup

After saving, open the browser console on any storefront page and run:

window.refactor_apps.back_in_stock.isReady; // → true

If you get true , the helper is active and all API methods are available. If the property is undefined, the embed is not activated in the current theme.

Do you need help?

If you have any questions or run into issues, please contact us — we’re happy to help.