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 these gracefully.

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 variantId  is not passed 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 make fetch requests will throw an Error  and log to the console if the network request itself fails (e.g. DNS failure, timeout, CORS issue). Check the browser DevTools Network tab 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. Contact support.