Dev: JavaScript API
Method: getLocations()
Returns all store locations.
Parameters: none
Returns: Promise<{ locations: Array<Location> }>
Each location object contains: id , isActive , address , metafields , metafieldNodes .
Throws: Error if the network request fails or returns a non-OK status.
const data = await window.refactor_apps.store_locator.getLocations(); console.log(`This array has ${data.locations?.length} locations`);
Method: getVariantStoreAvailability(variantId, coords?)
Returns in-store availability for a given product variant. Pass coordinates to sort results by proximity.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
variantId |
string |
✅ | Numeric variant ID without the GID prefix (e.g. "41085200498821" ) |
coords |
{ latitude?: number, longitude?: number } |
❌ | Optional coordinates for proximity sorting |
Returns: Promise<{ variant: { variantId: string, storeAvailability: Array<StoreAvailability> } }>
Throws: Error if the network request fails or returns a non-OK status.
const data = await window.refactor_apps.store_locator.getVariantStoreAvailability("41085200498821", { latitude: 40.7128, longitude: -74.0060 });
Method: getFavoriteStores()
Returns the customer's saved favourite store IDs. Stores data in a Shopify Customer Metafield for authenticated customers, or localStorage for guests.
Parameters: none
Returns: Promise<Array<string>> — array of location IDs
const favorites = await window.refactor_apps.store_locator.getFavoriteStores(); console.log(favorites); // ['87448682746', '88759075066']
Method: setCustomerFavoriteLocation(locationId)
Adds a store to the customer's favourites. Stores data in a Shopify Customer Metafield for authenticated customers, or localStorage for guests.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
locationId |
string |
✅ | Numeric location ID without the GID prefix |
Returns: Promise<Array<string>> — updated array of favourite location IDs
const favorites = await window.refactor_apps.store_locator.setCustomerFavoriteLocation('47891250020602'); console.log(favorites); // ['47891250020602']
Method: unsetCustomerFavoriteLocation(locationId)
Removes a store from the customer's favourites. Stores data in a Shopify Customer Metafield for authenticated customers, or localStorage for guests.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
locationId |
string |
✅ | Numeric location ID without the GID prefix |
Returns: Promise<Array<string>> — updated array of favourite location IDs
const favorites = await window.refactor_apps.store_locator.unsetCustomerFavoriteLocation('47891250020602'); console.log(favorites); // []
Method: getApiKey()
Returns the Google Maps API key configured in the app admin panel. Use this method to initialize a custom map instance instead of the built-in extension block.
Parameters: none
Returns: Promise<string>
const apiKey = await window.refactor_apps.store_locator.getApiKey(); console.log(apiKey); // AIzaSyBKyZ1hAn8w2xa4BDANIud9flaMU6O
Method: saveSearchAnalytics(params)
Sends a search event to the built-in analytics route.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
city |
string |
❌ | City name from the search |
country |
string |
❌ | Country from the search |
latitude |
number |
❌ | Search coordinates |
longitude |
number |
❌ | Search coordinates |
storeId |
string |
❌ | ID of the closest or selected store |
Returns: Promise<void>
window.refactor_apps.store_locator.saveSearchAnalytics({ city, country, latitude, longitude, storeId: closestStoreId, }).catch((err) => console.error("[R+ Store Locator] Analytics error:", err));
Customer Metafield reference
Favourite locations for authenticated customers are stored in a Shopify Customer Metafield:
| Property | Value |
|---|---|
| Namespace | refactor_store_locator |
| Key | fav_store |
| Type | list.single_line_text_field |
The value is a JSON array of location GIDs:
["gid://shopify/Location/88759075066", "gid://shopify/Location/87448682746"]
This value can also be accessed directly in Liquid:
{% if customer %} {% assign customer_favorite_stores = customer.metafields.refactor_store_locator.fav_store.value | json | escape %} {% endif %}
Do you need help?
If you have any questions or run into issues, please contact us — we’re happy to help.