This page exists in one language only. Some pages here are English, some Swedish.

Integrations & Embed

This guide is for the developer who puts the Stockisto widget on a website. It covers the script tag, the attributes that configure it, the eight widgets, the public locator endpoints, and analytics consent. For getting retailer data into Stockisto, see the Data Import guide (CSV/XLSX), the Public imports API (NDJSON bundles) or the Public intake API (source-bound batches).

The widget script

The widget is a single, dependency-free script, widget.js, served from the Stockisto CDN. The widget.js address always serves the current deployed build, so your script tag never needs a version bump.

Open a saved embed in your admin and copy its Install snippet. The embed id identifies the widget you saved. This example uses a placeholder id; keep the id and origins your admin generates.

<script
  src="https://cdn.test.stockisto.com/widget.js"
  data-api-base="https://api.test.stockisto.com"
  data-embed="we_0123456789abcdef0123456789abcdef"
  async></script>

Save its type, view, language and settings in Supplier Admin, Retailer Admin or Installer Admin. The installed snippet reads those changes on the next page load. Add only the page keys the page supplies, such as data-sku="YOUR-PRODUCT-CODE". The script inserts its own host; no slot div is needed.

Snippets installed today keep working

Existing attribute snippets still work. Omitted settings come from the owner's default embed; a failed default lookup leaves the existing attribute behaviour intact.

<script
  src="https://cdn.test.stockisto.com/widget.js"
  data-api-base="https://api.test.stockisto.com"
  data-stockisto-slug="YOUR-BRAND-SLUG"
  data-widget-type="where-to-buy"
  async></script>

What the script does

• Finds its own <script> tag. Async loads are fine: it looks for document.currentScript, then script[data-stockisto-widget="true"], then any script whose src contains widget.js.
• Resolves data-embed through GET /api/v1/locator/widget-embeds/{publicId} before choosing language, slot, shape or data source. The request is anonymous and sends no cookies.
• Explicit page attributes override saved values. An empty data-sku suppresses product-dependent rendering.
• Caches only the loading shape (widgetType, view, settings) under stockisto-embed:<publicId>. A repeat visit can show that skeleton during resolve; cached settings never replace live results.
• Renders into <div id="stockisto-<data-view>"> when that div exists, else into <div id="stockisto-<data-widget-type>">. With neither, it injects its own host element right after the script tag, so the div is optional.
• Resolves the embed immediately. Store-result fetching waits until the widget scrolls into view. The asynchronous script does not block page loading.
• Fails closed. A missing brand, a refused search or an empty result renders an honest empty state or nothing at all. It never throws into your page; boot failures are stamped as data-stockisto-error on the script tag.
• Adds one <script type="application/ld+json"> block describing the visible store list as a schema.org ItemList of Store nodes. It never emits Product or Offer markup. Turn it off with data-jsonld="off".

Configuration attributes

Identity and placement

For new installs use data-embed, the we_ id copied from your saved widget, plus data-api-base. The following attributes describe page overrides and legacy installs. Saved settings fill omitted values; an explicit attribute takes precedence. A named embed does not need a brand slug on the page.

Products

Without a declared scheme the code is tried as rsk, then sku, then gtin. A declared scheme is only ever looked up as that scheme. Classification and certificate codes such as etim, bk04 or va are refused: they are not product keys.

Location and list

Keys for retailer and installer widgets

A non-GUID id is dropped and the widget hides itself rather than looping on a 404.

Styling

Every styling attribute is optional. Absent means the Heritage default look.

Anything off these lists is dropped. A hex accent with poor contrast against the card is replaced by the default.

Widget list

Exactly eight widgets ship. Select one with data-widget-type; an omitted value defaults to where-to-buy, and an explicit empty, unknown or retired value renders nothing. The Supplier Admin Install → Advanced builder generates snippets for the four supplier/brand widgets; Retailer Admin Widgets generates the three retailer widgets; an installer's detail page in Supplier Admin generates the installer widget.

On a supplier's product pages

• where-to-buy (default): nearby authorized retailers, confirmed stock ranked first. Runs brand-wide, or scoped to one product with data-sku. Five views (data-view): full (the whole list, default), inline (a compact panel in the page's own flow), button (opens an overlay), pill (a compact count pill, "Stocked by N stores near you", degrading to a count-less "Find where to buy" CTA with zero nearby stores, never "0 stores"), corner (a pinned corner pill that opens the list over the page). data-guided, data-sold-out and data-reserve layer optional guided questions, a sold-out-online banner and a reserve action over any view.
• guided-handoff: a three-step flow. Pick a retailer, optionally pick an approved installer, then give explicit consent before an installer lead is sent.

On a supplier's brand pages

• store-locator: the whole network as a map, or as a server-rendered directory with data-view="list". Visitors can switch inside the frame.
• installer-finder: your approved installers with coverage areas, service filters and an in-frame callback request. It never asks for browser location.

On a retailer's own site

All three need data-retailer.

• store-availability: the retailer's own branches near the shopper with the stock signal for data-sku, and the retailer's published price where the server releases one. Needs data-stockisto-slug, data-retailer and data-sku.
• store-card: one store's address, opening hours, the brands it carries and its aggregate rating, stacked in that order. Each part hides on its own (data-show-visit / -brands / -rating); with every part off, empty or failed the card hides. Needs data-store-id and data-retailer.
• stock-alert: a back-in-stock email form for one product at one store. Needs data-stockisto-slug, data-store-id and data-sku. Sign-up is double opt-in.

On an installer's own site

• installer-card: the installer's registry credential and service-area coverage check, stacked in that order; each section hides on its own (data-show-credential / -coverage). Needs data-installer and the supplier's data-stockisto-slug. The public wire carries a bare certified flag with no supplier, category or date, so it cannot say which brand approved what.

Content Security Policy

Allow https://cdn.test.stockisto.com in script-src and https://api.test.stockisto.com in connect-src on TEST. For a production snippet, allow https://cdn.stockisto.com and https://api.stockisto.com respectively. Use the origins from your generated snippet. The API origin must be allowed for the embed resolve. The map and installer-finder frames also need frame-src https://find.test.stockisto.com on TEST.

A refused connect-src prevents a named embed from resolving. It shows a load-failed state with Retry; it never renders cached results. A deleted or unknown id renders nothing.

Public locator endpoints

The widget reads from anonymous endpoints under https://api.test.stockisto.com/api/v1/locator. No token or cookie is needed, and any origin may call them. You can call them yourself for a custom integration.

GET /api/v1/locator/search

The widget's main read. It needs the supplier GUID and a search centre:

GET /api/v1/locator/search?supplierId=SUPPLIER_GUID&latitude=59.33&longitude=18.06&radiusKm=50&pageSize=12

Each retailer row carries id, retailerId, slug, name, address, city, postalCode, country, latitude, longitude, distanceKm, isShowroom, phone, email, website, openingHours, displaySignal, rankingScore, isSponsored, isSample and a stockStatus object (freshness, lastVerifiedAt, confidenceTier). The envelope adds totalCount and hasMore. displaySignal is InStock, MayCarry or ContactRetailer. Results are cached for five minutes per supplier.

Other routes the widget uses

Status codes to handle

Analytics events

With data-analytics-consent="true" the widget posts events to POST https://api.test.stockisto.com/api/v1/analytics/events. It uses fetch with keepalive and no credentials, so no cookie ever travels with an event.

The body carries schemaVersion: 1, sessionId, correlationId, eventType and a payload. The server resolves your tenant from the brand slug and ignores any tenant id in the body. It answers 202 Accepted without waiting for the write. Anonymous callers may only send known event types; an unknown type returns 400.

Events are credited to your account only when the page's origin is on your Allowed origins list (Supplier Admin → Install → Embed script). Add every domain that hosts the widget, one per line, such as https://www.yourbrand.com. The same list gates lead attribution for the guided handoff.

Installing through a tag manager or a CMS

• GTM install guide: paste the snippet as a Custom HTML tag.
• Shopify install guide: a Custom Liquid section, or the Stockisto app block.
• WordPress & WooCommerce install guide: the plugin shortcode or a Custom HTML block.

What's next?

• Data Import guide: the CSV template, geocoding and the review queue
• Getting Started: trial, onboarding and publishing your locator
• Searches, clicks and reports guide: what the events show in your dashboard
• MCP assistant guide: connect an assistant for read-only access first, then authorize writes separately.