# Find physical stores

Search one merchant's physical-store directory by place, known coordinates or returned variant IDs, then look up stores by their location IDs.

Find a merchant's physical stores by place or distance, or pass an item ID from the Catalog to find nearby stores that carry it. Use `search_locations` to search and `lookup_locations` to retrieve stores by returned location IDs. Both work without sign-in.

Start with a merchant selected from [product search](search.md). Pass its offer's `seller.domain` unchanged as `shop`, with no scheme or path. Keep every returned location ID tied to that same merchant.

## Search a merchant's stores

These examples show tool arguments. Replace `<returned seller.domain>` with the actual hostname from the selected offer; it isn't a usable merchant name:

```json
{
  "shop": "<returned seller.domain>",
  "location": { "query": "New York" }
}
```

From the CLI:

```sh
shop location search 'New York' --shop '<returned seller.domain>'
```

Use the shopper's literal city, neighborhood, street or postal words, not an invented abbreviation. Both `shop` and the outer `location` object are required. Omit `query` to list the merchant's directory. Search also accepts `location.pagination` with `limit` and `cursor`; pass a returned cursor unchanged with the same search requirements.

## Look up returned locations

Use `lookup_locations` for location IDs already returned by that merchant, up to 10 per call. Substitute an actual returned location ID and the same `seller.domain` in both examples:

```json
{
  "shop": "<same seller.domain>",
  "location": { "ids": ["<returned location id>"] }
}
```

```sh
shop location lookup '<returned location id>' --shop '<same seller.domain>'
```

Treat IDs as opaque. A location ID identifies a physical store; it isn't a product or variant ID and can't be used as a checkout line item.

## Filter by items or distance

Both tools accept `location.filters.items`, a list of up to 10 actual variant IDs from catalog results. The CLI takes them with `--item '<returned variant id>'`. These are **variant IDs**, not location IDs. Item filters ask for stores that report all those items available; a directory listing alone doesn't establish stock, reserve an item, guarantee pickup eligibility or make a checkout ready. Show the returned evidence and messages, and verify current merchant availability and checkout terms before buying.

For example, search the merchant's New York stores for these selected variants. Replace the placeholders with the selected seller's domain and returned variant IDs:

```json
{
  "shop": "<returned seller.domain>",
  "location": {
    "query": "New York",
    "filters": {
      "items": ["<returned variant id 1>", "<returned variant id 2>"]
    }
  }
}
```

```sh
shop location search 'New York' --shop '<returned seller.domain>' \
  --item '<returned variant id 1>' \
  --item '<returned variant id 2>'
```

For a radius, set `location.distance` to `{center:{latitude,longitude},max}`. Coordinates are WGS 84 decimal degrees and `max` is the inclusive radius in meters. Use only coordinates supplied by the user or host: never geocode or guess a center, or widen or clamp the requested radius. The CLI requires all three flags together: `--center-latitude`, `--center-longitude` and `--distance-max`.

`location.context` supplies soft relevance and localization hints, not a proximity filter. `location.serves` asks whether a store can serve a target, not whether it is nearby; it takes exactly one of `point` or `address`. `filters` are hard requirements and combine with AND. A merchant that can't evaluate one returns `invalid_input` rather than silently ignoring it. Shopify stores evaluate item filters, not arbitrary amenities, hours or serviceability filters.

For the full schemas, including `context`, `filters`, `serves` and observed platform `signals`:

```sh
shop location search --schema
shop location lookup --schema
```

Use complete `--arguments` for fields the shorthand flags don't cover. The [CLI reference](cli.md#flags-and-full-arguments) explains both forms.

## Read the directory result

The document has `locations`, optional `pagination`, and may include `messages` and `next`. Keep these cases separate:

| Result | What it means |
| --- | --- |
| Empty `locations` with info code `location_discovery_unavailable` | The merchant doesn't publish the relevant directory capability through Shop. This is a successful fallback, not proof no physical stores exist. Tell the shopper and continue the task; don't retry, re-query or switch location tools for that merchant. |
| An advertised directory returns no matches | No locations matched this request. Read its messages and suggestions before refining; don't claim the merchant has no stores. |
| `isError: true` | The call failed. Follow [Errors and retries](errors.md); don't reinterpret failure as an empty directory. |

A returned store is directory evidence, not a stock or pickup guarantee. Preserve the merchant's facts, show warnings, and don't invent missing addresses, hours, coordinates or availability.