Dev: Troubleshooting
HTTP errors from API methods
All async methods (getLocations , getVariantStoreAvailability , setCustomerFavoriteLocation , unsetCustomerFavoriteLocation , getApiKey , saveSearchAnalytics ) throw a standard Error on any non-2xx response. The error message includes the HTTP status code and status text:
Error: HTTP 404: Not Found Error: HTTP 400: Bad Request Error: HTTP 402: Payment Required
Always wrap calls in try/catch or chain .catch() to handle errors appropriately.
Subscription inactive — 402 Payment Required
Affected methods: getLocations , getVariantStoreAvailability , setCustomerFavoriteLocation , unsetCustomerFavoriteLocation
If the store's R+ subscription is not active, all proxy endpoints return:
{ "error": "Subscription is not active" }
with HTTP status 402 . The app will stop returning location data until the subscription is renewed in the R+ admin panel.
variant_id missing — 400 Bad Request
Affected method: getVariantStoreAvailability
If variant_Id is not provided or is empty, the endpoint returns:
{ "error": "variant_id query parameter is required" }
Make sure you're passing the numeric ID only, without the gid://shopify/ProductVariant/ prefix.
Customer ID or location IDs missing — 400 Bad Request
Affected methods: setCustomerFavoriteLocation , unsetCustomerFavoriteLocation
If the POST body is missing customerId or locationIds , the endpoint returns:
{ "error": "Customer id or location ids is missing." }
This can happen if the App Embed Extension script element is missing its data-customer-id attribute, which means the customer session wasn't injected correctly. Verify the embed is activated and the customer is logged in.
Metafield mutation errors — 400 Bad Request
Affected methods: setCustomerFavoriteLocation , unsetCustomerFavoriteLocation
If the Shopify GraphQL mutation for updating the customer metafield fails, the endpoint returns:
{ "error": "Error in customerUpdate GraphQL mutation.", "errors": [ ...Shopify userErrors ] }
The errors array contains the raw Shopify userErrors objects with field and message properties. Check these for permission or validation issues on the metafield.
Guest customers — no server-side persistence
Affected methods: setCustomerFavoriteLocation , unsetCustomerFavoriteLocation
If the customer is not logged in, the helper still updates localStorage but logs a warning and skips the server-side request:
Customer ID is missing. Favorite location will not be saved server-side.
This is expected behavior for guest sessions. Favorites will persist in the browser but won't be tied to the customer account.
window.refactor_apps is undefined
The App Embed Extension is not activated in the current theme. Follow the steps in Dev: Requirements to enable it. After saving, reload the page and verify the object exists:
console.log(typeof window.refactor_apps?.store_locator); // should print "object"
General network failures
All methods that perform fetch requests will throw an Error and log to the console if the network request fails (e.g. DNS failure, timeout, CORS issue). Check the Network tab in your browser DevTools to inspect the actual request to /apps/refactor-store-locator/... and look for the response status and body.
Do you need help?
If you have any questions or run into issues, please contact us — we’re happy to help.