Skip to main content
Answers “where are my products actually being sold?” Combines the brand’s product catalog with the offer graph (who stocks what) to report coverage, stock signals, and distribution gaps.

​
When to use

  • Brand owner asks “which stores carry my products?”
  • Merchandising: “where do I have distribution gaps?”
  • Combined with brand-search-demand to identify demand/supply mismatch.

​
Auth

OAuth token with scope brands:read and membership in the owning organization.

​
Endpoint

GET /dashboard/api/v1/brand-analytics/retail-footprint
  ?organization_id=<org_id>        # optional
  &brand_id=<brand_id>             # optional
  &region=<ISO 3166 region>        # optional; e.g. "US-TX"
  &stock_status=in_stock|any       # default: any
  &group_by=store|city|region      # default: store
  &top=<int>                       # default: 50

​
Response (group_by=store)

{
  "brand_id": "...",
  "total_stores_carrying": 412,
  "total_skus_distributed": 38,
  "unique_stores_by_region": {"US-TX": 68, "US-CA": 112, "CA-BC": 32},
  "stores": [
    {
      "store": {
        "name": "Whole Foods – Austin Domain",
        "address": "11920 Domain Dr, Austin, TX 78758",
        "coordinates": {"lat": 30.402, "lon": -97.726}
      },
      "retailer": "Whole Foods Market",
      "skus_carried": 14,
      "skus_in_stock": 12,
      "last_inventory_sync": "2026-04-17T06:12:00Z",
      "stale_inventory": false
    }
  ]
}

​
Response (group_by=region)

{
  "by_region": [
    {
      "region": "US-TX",
      "stores": 68,
      "skus_distributed": 28,
      "coverage_ratio": 0.74,
      "top_cities": ["Austin", "Houston", "Dallas"]
    }
  ]
}

​
Data sources

  • InStoreOffer — physical retail offers, with FK to product, location, organization (the retailer), status, quantity_on_hand, updated
  • OnlineOffer — online retailers’ offers (optional in response via include=online)
  • Location — PostGIS Point for store coordinates
  • Brand → Product → Offer — brand ownership joined in via Product.brand.organization == <caller's org>

​
Dimensions available today

  • Store-level distribution — one row per location × product
  • Stock state — from InStoreOffer.status and quantity_on_hand
  • Freshness — last_inventory_sync flags stale data (>48h stale)
  • Geographic aggregation — region / city via Location fields

​
Not yet available

  • Sell-through velocity — we track inventory snapshots but not POS throughput. Planned via integrations API.
  • Distribution gap alerts — auto-detect where brand-search-demand is high but footprint is zero. Planned as a dedicated skill.

​
Guidance for agents

  • Start with group_by=region for a high-level picture; drill into stores only if the user asks.
  • Stale inventory flags — any store with last_inventory_sync > 48h ago should be marked; don’t let brand owners overreact to ghost data.
  • Online + offline: by default this skill reports physical retail only. If the user asks about total distribution, call with include=online (planned parameter).
  • brand-scan-summary — engagement by product
  • brand-search-demand — where demand lives; cross-reference for gaps