This page exists in one language only. Some pages here are English, some Swedish.
The Consumer Locator
Overview
The Consumer Locator is the public "where to buy" page your shoppers see: a map and list of retailers near them that carry your products. It runs as a standalone app served per supplier, themed with your logo, colors and hero copy.
Every locator page is anonymous. A shopper sets a location, the locator searches your retailer network within a radius, and returns ranked retailer rows. One search response carries everything a row and a map pin need.
The locator ships in English, Swedish, Norwegian, Danish and Finnish. English is the default; other languages sit under a path prefix such as /sv.
How a locator is addressed
A locator resolves by slug or by custom domain:
- Subdomain:
yourbrand.stockisto.com, whereyourbrandis your brand slug. - Shared host:
find.stockisto.com/s/yourbrand. - Custom domain: for example
locator.yourbrand.com. TheHostheader resolves to your slug viaGET /api/v1/locator/resolve-host. DNS verification runs in a background job, never at request time.
See the Integrations & Embed guide to embed the widget on your own site.
Visibility modes
A Private locator returns HTTP 403 from every data endpoint. An Unlisted locator works normally but is not listed anywhere. See the Sharing + Groups guide for the full model.
Searching by location
Shoppers set a search center in two ways:
- Use my location: the browser geolocation prompt. The locator reverse-geocodes the result for a display name.
- Address input: a city, postcode or address. Suggestions come from the server-side geocoder, biased to
se,no,dkandfi.
Geocoding is proxied through GET /api/v1/locator/geocode, so the browser never calls the upstream provider.
The search itself is one call:
GET /api/v1/locator/search?supplierId={id}&lat=59.33&lng=18.07&radius=25
Coordinates are always dot-decimal
lat, lng and radius are parsed with invariant formatting, whatever the
server locale. They are short aliases for latitude, longitude and
radiusKm.
Search parameters
| Parameter | Type | Notes |
|---|---|---|
supplierId | GUID | Required; scopes the search to your retailer network |
lat / lng | number | Required search center |
radius | number | Search radius in km, 1 to 500, default 25 |
inStockOnly | bool | Keep only locations with in-stock or carries-the-line data |
showroomOnly | bool | Keep only showroom locations |
serviceTags | list | Keep locations that offer every listed tag |
authorizedOnly | bool | Keep only retailers with a tiered relationship |
skuId | GUID | Only locations that stock this SKU |
skuCode | string | Same, by SKU code |
skuCodes | list | Up to 50 SKU codes |
channel | string | online restricts to online channels |
groupId | GUID | Restrict to retailers in one group |
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, shoppers see three filter chips. One is active at a time:
- All retailers
- In stock only (hidden when no stock claim is licensed for the brand)
- Showroom
The sort order is set by the brand theme's default sort and shown as a label next to the result count: Best match first, Nearest first, In stock first or Showrooms first. The search radius comes from the URL and is capped by the theme's maximum radius.
Featured retailers sort first in every sort mode.
How results are ranked
best_match is a composite score computed server-side. The locator never re-derives it.
| Signal | Weight | Source |
|---|---|---|
| Distance | 0.40 | Closeness to the search center, relative to the radius |
| Assortment | 0.35 | How sure Stockisto is that the retailer carries the line |
| Freshness | 0.15 | How recently the stock data was verified |
| In stock | +0.10 | Confirmed stock at the location |
| Trusted-tier stock | +0.05 | Fresh stock from a trusted source (+0.02 when aging) |
| Sponsored placement | +0.15 | Active sponsored placement |
Freshness scores 1.0 for data verified today and decays linearly to 0 over 30 days.
Sponsored placements are flagged
A retailer with an active sponsored placement is boosted and flagged
isSponsored in the response. The embeddable widget shows a "Sponsored"
label on flagged rows.
Retailer rows and the detail panel
Each result is a row with the retailer name, address, distance, a stock status dot with its label, and Updated {date}. A SKU-scoped search also shows the retailer's price when one is known.
Selecting a row opens the detail panel:
- Directions, Website and Call actions. A live chat action appears when the retailer has chat enabled.
- Availability at this store, per product, with the note Confirm before travelling.
- View at retailer when the retailer lists the product online.
- Location with Open in Google Maps.
Outbound website links carry the UTM parameters the shopper arrived with. See the Analytics & Attribution guide.
Stock wording
Stock status uses four claims, so a shopper is never misled:
| Claim | Swedish | Meaning |
|---|---|---|
| In stock | I lager | Recently confirmed stock at this location |
| May carry: call ahead | Kan finnas. Ring först. | The retailer carries the line; current stock unconfirmed |
| Out of stock: call ahead | Slut i lager, ring i förväg | Recently reported out of stock |
| Authorised: stock unknown | Auktoriserad, lagerstatus okänd | An authorised retailer with no stock signal |
Stock confirmations age out: fresh for 7 days, aging to 30 days, then stale. A stale confirmation no longer counts as in stock. The wording rules are in the honesty grammar in docs/design/honesty-grammar.md.
The brands directory
For retailers that carry several of your brands, Stockisto serves a brands page: a shopper-facing directory of every brand the retailer is linked to.
GET /api/v1/locator/retailers/{slug}/brandsreturns the retailer page meta plus the brand list. The page shows one grid with a search box, a category filter and a grid or list layout toggle.GET /api/v1/locator/retailers/{retailerSlug}/brands/{brandId}returns one brand detail page: hero, description, key products, product categories, a website link, and a Find a brandName retailer near you button that opens that supplier's locator.
Only brands linked through an active supplier-retailer relationship appear.
Brand detail paths use IDs, not slugs
The front end routes brand detail under /brands/{brandId}.
Branding per supplier
The whole locator is themed from the brand theme, served by GET /api/v1/locator/brands/{slug} and applied during server-side rendering:
| Field | Purpose |
|---|---|
logoBlobPath | Brand logo |
heroBlobPath | Hero background image |
primaryColor / secondaryColor | Brand colors (hex), applied as CSS variables |
heroHeadline / heroSubheading | Hero copy |
layoutVariant | split, map_first, list_first or grid |
fontPairing | Typeface pairing |
defaultSort | Default sort order |
maxRadiusKm | Maximum search radius (default 100 km) |
featuredLocationIds | Locations pinned to the top of results |
hideCredit | Hides the Stockisto credit line |
Configure these from your dashboard's locator settings; see the Getting Started guide.
Performance and limits
- Caching: search results are cached 5 minutes per supplier. Brand theme responses are cached up to 10 minutes per slug. Visibility is checked live, so publish and unpublish take effect at once.
- Rate limits: search allows 100 requests per minute per tenant and 20 per minute per anonymous IP. The brand and embed config endpoint allows 500 per minute per tenant.
- Suspended tenants: every data endpoint returns HTTP 503.
- Private locators: every data endpoint returns HTTP 403.
What's next?
- Integrations & Embed guide: embed the widget and use the public endpoints
- Analytics & Attribution guide: what is tracked and how clicks are attributed
- Sharing + Groups guide: visibility modes, groups and featured tiers