The Consumer Locator
Overview
The Consumer Locator is the public, branded "where to buy" experience your shoppers see — a map and list of retailers that carry your products, near them. It runs as a standalone Next.js app served per supplier and is fully themed with your logo, colors, and hero copy.
Every locator page is anonymous: no login, no account. A consumer enters a location, the locator searches your retailer network within a radius, and returns scored, sorted retailer cards with availability and trust badges. All the data needed to render a card and a map pin arrives in a single search response.
This guide covers what consumers can do, how results are ranked, the badges they see, the brands directory, and how the whole experience is branded per supplier.
How a locator is addressed
A locator is resolved by slug or by custom domain:
- Subdomain —
yourbrand.stockisto.com, whereyourbrandis your brand slug. - Custom domain — e.g.
locator.yourbrand.com. The incomingHostheader is resolved to your brand slug viaGET /api/v1/locator/resolve-host. DNS verification is handled by a background job, never at request time. See the Integrations & Embed guide for embedding the widget on your own site.
Visibility modes
A Private locator returns HTTP 403 from every data endpoint — it serves no
results to consumers. Unlisted locators work normally but should carry a
noindex meta tag. See the Sharing + Groups guide for the full
visibility model.
Searching by location
Consumers set a search center in two ways:
- Use my location — the browser geolocation prompt. On approval, the locator reverse-geocodes the coordinates for a display name.
- Address input — type a city, postcode, or address. Suggestions come from the
server-side geocoder, biased to the Nordic countries (
se,no,dk,fi).
Geocoding is proxied through GET /api/v1/locator/geocode so the browser never calls
the upstream provider directly (avoiding CORS and rate-limit issues).
The search itself is a single call:
GET /api/v1/locator/search?supplierId={id}&lat=59.33&lng=18.07&radius=25
Coordinates are always dot-decimal
Latitude, longitude, and radius in the URL are always parsed with invariant
(dot-decimal) formatting — independent of the server locale. lat/lng/radius
are accepted as short aliases for latitude/longitude/radiusKm.
Search parameters
| Parameter | Type | Notes |
|---|---|---|
supplierId | GUID | Required — scopes the search to your retailer network |
lat / lng | number | Required search center (−90..90 / −180..180) |
radius | number | Search radius in km, 1–500, default 25 |
inStockOnly | bool | Keep only locations with In stock or Carries-the-line data |
showroomOnly | bool | Keep only showroom-enabled locations |
serviceTags | list | Match locations offering all listed tags |
authorizedOnly | bool | Keep only retailers with an authorized/tiered relationship |
skuId | GUID | Only locations that stock this specific SKU |
groupId | GUID | Restrict to retailers in a specific group (SHARE-03) |
sort | string | best_match, closest, in_stock_first, showroom_first |
page / pageSize | int | Pagination; default page size 50, max 100 |
Filters and sorting
Above the results, consumers see a filter chip row plus a filters drawer for the advanced options.
Filter chips
- In stock — toggle for
inStockOnly. - Showroom — toggle for
showroomOnly. - Authorized — toggle for
authorizedOnly. - Distance — dropdown with radius options of 10, 25, 50, and 100 km.
- Sort — dropdown with the four sort modes below.
- All filters — opens the drawer; shows a count badge when advanced filters are active.
The filters drawer
The drawer holds the Services offered checklist (service tags such as Installation,
Repair, Consultation, Delivery, Assembly). Selecting tags applies a serviceTags
filter — a location must offer all selected tags to remain in results.
Sort modes
| Sort | Behavior |
|---|---|
best_match | Weighted composite score (default) |
closest | Nearest first by distance |
in_stock_first | In stock, then carries-the-line, then the rest; ties by distance |
showroom_first | Showroom locations first, then by distance |
Featured retailers always sort first within every sort mode (SHARE-04).
Which filters appear is configurable
The brand theme controls which filters are shown, the default sort, whether the distance filter appears, and the maximum radius. See Branding per supplier below.
How results are ranked
best_match is a weighted composite score (0–1) computed entirely server-side. The
widget never re-derives it. The weights are:
| Signal | Weight | Source |
|---|---|---|
| Distance | 0.30 | Distance from the search center |
| In stock | 0.30 | Confirmed stock at the location |
| Showroom | 0.15 | Location is a showroom |
| Services | 0.10 | Number of matching service tags |
| Authorized | 0.10 | Active authorized/tiered supplier relationship |
| Freshness | 0.05 | How recently the data was verified |
Freshness scores 1.0 for data verified today and decays linearly to 0 over 30 days.
Sponsored placements are always labeled
A retailer with an active sponsored placement is boosted in ranking and flagged server-side. When that flag is set, the widget must display a "Sponsored" label — no API parameter or config can suppress it.
Retailer cards and the detail view
Each result renders as a card with everything a consumer needs to decide:
- Name plus trust badges (Verified, Authorized).
- Status strip — stock and showroom badges.
- Distance and city.
- Service tags — up to three, with a "+N more" overflow.
- Actions — Directions, Website, and Call. Directions and Website links are wrapped with Stockisto attribution parameters so outbound clicks are tracked back to your locator. See the Analytics & Attribution guide.
Selecting a card opens the detail panel, which adds full address, availability with a freshness line ("Last updated: today / yesterday / N days ago"), services, visit info (opening hours, by-appointment note), and a map link.
Stale availability warning
If stock data is older than 7 days, the detail panel shows an amber "Confirm availability before visiting" warning rather than hiding the result — consumers still see the retailer, with the right expectation.
The badges
Badges are how consumers read availability and trust at a glance.
Stock
- In stock (green dot) — confirmed stock at this location.
- Contact to confirm (grey dot) — the retailer carries the line but stock is not confirmed.
- Out of stock (red dot) — shown but muted.
- No badge at all when there is no stock data for the location.
Showroom
- Showroom — the location is a physical showroom.
- Showroom (by appt.) — showroom visits are by appointment only.
Trust
- Verified — the retailer completed its profile checklist (claim verified).
- Authorized partner — top-tier relationship (gold / platinum).
- Authorized — an active authorized relationship without a top tier.
The brands directory
For retailers who carry multiple of your brands, Stockisto serves an "Our Brands" page — a consumer-facing directory of every brand that retailer is associated with.
GET /api/v1/locator/retailers/{slug}/brandsreturns the directory: retailer page meta plus the list of associated brands, split into Featured and All Brands grids.GET /api/v1/locator/retailers/{retailerSlug}/brands/{brandId}returns a single brand detail page with hero, description, key products, product categories, a website link, and a "Find a brandName retailer near you" call to action that links straight to that supplier's locator.
Only brands linked via an active supplier–retailer relationship appear in the directory.
Brand detail paths use IDs, not slugs
Brand detail is addressed by brand ID, e.g.
/api/v1/locator/retailers/{retailerSlug}/brands/{brandId}. The front-end routes
to these under /brands/{brandId}.
Branding per supplier
The whole locator is themed from one place — the brand theme, served by
GET /api/v1/locator/brands/{slug} and applied during server-side rendering. The theme
carries both visual branding and locator configuration:
| Field | Purpose |
|---|---|
logoBlobPath | Brand logo |
heroBlobPath | Hero background image |
primaryColor / secondaryColor | Brand colors (hex), applied as CSS vars |
heroHeadline / heroSubheading | Hero copy |
filtersEnabled | Which filter controls to display |
defaultSort | Default sort order |
showDistanceFilter | Whether the distance/radius filter appears |
maxRadiusKm | Maximum search radius offered (default 100 km) |
Configure these from your dashboard's locator settings; see the Getting Started guide for the first-time setup walkthrough.
Performance and limits
- Caching — search results are cached 5 minutes per supplier; brand theme data is cached 10 minutes per slug. Visibility is always checked live so publish/unpublish takes effect immediately.
- Rate limits — search is limited to 100 req/min per tenant (20 req/min per anonymous IP); the brand/embed config endpoint allows 500 req/min per tenant.
- Suspended tenants — every data endpoint returns HTTP 503 for a suspended supplier.
- Private locators — return HTTP 403 from every data endpoint.
What's next?
- Integrations & Embed guide — embed the locator widget and use the public endpoints.
- Analytics & Attribution guide — what's tracked and how consumer clicks are attributed.
- Sharing + Groups guide — visibility modes, groups, and featured tiers.