Dev: Troubleshooting

How the functionality works

The script initializes the window.refactor_apps.back_in_stock  object, which exposes the core methods: checking subscription status, subscribing/unsubscribing, retrieving subscribers and subscribed products, and automatically merging guest subscriptions with a customer account on login.

Once the script loads, it dispatches an apps:back-in-stock:ready  event. After the guest-to-customer merge step completes, it dispatches apps:back-in-stock:merge-complete .

Issue: The subscribe button doesn't appear, or the widget doesn't initialize

Possible causes:

• The theme tries to access window.refactor_apps.back_in_stock  before the script has finished loading.
• The isReady  flag is still false  at the time it's accessed.

Solution: Wait for the apps:back-in-stock:ready  event, or check the isReady  flag, before calling any widget methods. Calling methods before initialization will throw an error or silently fail.

Issue: checkIsSubscribed  returns success: false

Possible causes:

• Incorrect or missing email  or variantId  passed to the request.
• The /apps/refactor-back-in-stock/api/check  endpoint returns a server-side error (e.g., the product or shop can't be found).
• Network or proxy issues — for example, if a tunneling service like ngrok is in use, the ngrok-skip-browser-warning  header is already set in the request, but additional middleware could still interfere.

Solution: Check the message.errors  object returned on failure — it contains a description of the specific error. Also confirm email  and variantId  are valid strings, not undefined  or null .

Issue: subscribeOnTheProduct  doesn't work, or the subscription isn't saved

Possible causes:

• A required parameter (productId , variantId , or email ) is missing.
• The server rejects the request due to validation (e.g., invalid email format).
• customerId  was passed but the customer isn't found in the system, so the subscription is only saved as a guest subscription.

Solution:

1. Check the request body — all IDs should be coerced to strings (this is already handled via String() ).
2. Confirm window.Shopify.locale  and window.Shopify.country  are defined on the page — if missing, the payload will send null  for these, which isn't fatal but may affect notification localization.
3. On success, the apps:back-in-stock:subscribed  event should fire. If it doesn't, the request didn't complete successfully — check the browser console for network errors.

Issue: unsubscribeFromTheProduct  returns an error

Possible causes:

• No subscription exists matching the given email /variantId /productId .
• customerId  was used when subscribing but not when unsubscribing (or vice versa), so the system can't locate the matching record.

Solution: Use the same identifiers that were used when subscribing. For logged-in customers, prefer unsubscribeFromTheProductByCustomerId  to avoid mismatches between email-based and customer-based records.

Issue: Guest subscriptions don't merge with the account after login

Possible causes:

• window.refactor_apps.__customerData  is missing id  or email  at the time the script runs.
• The merge (mergeCustomer ) already ran previously, and there are no remaining unlinked records to merge — this is expected behavior, not an error.

Solution: Confirm that __customerData  is correctly populated by the theme and available before the script runs. If there's nothing to merge, the apps:back-in-stock:merge-complete  event will still fire — this is normal, and you shouldn't expect merged: true  on every occurrence.

• Dev: Overview
• Dev: JavaScript API
• Flow Integration

Do you need help?

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