> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Brand Retail Footprint

> Map a brand's retail distribution — which stores carry their products, stock signals, and distribution gaps.

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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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).

## Related skills

* `brand-scan-summary` — engagement by product
* `brand-search-demand` — where demand lives; cross-reference for gaps