---
title: >-
  Discover a merchant's retail stores with UCP location search and lookup -
  Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/posts/discover-a-merchant-s-retail-stores-with-ucp-location-search-and-lookup
  md: >-
    https://shopify.dev/changelog/posts/discover-a-merchant-s-retail-stores-with-ucp-location-search-and-lookup.md
metadata:
  effectiveApiVersion: '2026-08-25'
  affectedApi: []
  primaryTag:
    displayName: UCP
    handle: ucp
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2026-10-16T19:59:50-04:00'
  postedAt: '2026-10-22T14:00:00-04:00'
  updatedAt: '2026-10-22T13:57:37-04:00'
  effectiveAt: '2026-10-21T11:00:00-04:00'
---

October 22, 2026

# Discover a merchant's retail stores with UCP location search and lookup

DateOctober 22, 2026

Version[2026-08-25](https://shopify.dev/changelog?api_version=2026-08-25)

FlagsNew

SurfacesUCP

Shopify storefronts now support the [UCP location capability](https://shopify.dev/docs/agents/catalog/storefront-catalog#search_locations), `dev.ucp.common.location.search` and `dev.ucp.common.location.lookup`, starting with UCP `2026-08-25`. When you negotiate these capabilities over the storefront MCP endpoint, your agent can find a merchant's physical stores, narrow them by name, city, or distance, and check which stores carry the items a buyer wants. This is an optional new capability and doesn't require changes if you don't use locations today.

## What changed

Storefronts with at least one retail location now list both location capabilities in their discovery profiles at `/.well-known/ucp`. A retail location is an active, merchant-managed location that the merchant set up to sell in person and enabled as a Physical storefront.

If your agent profile negotiates these capabilities, the storefront MCP endpoint at `https://{storedomain}/api/ucp/mcp` exposes two tools:

* `search_locations` lists the shop's retail locations. An empty `location` object returns the first page. You can narrow results with a `query` that matches store names and cities, a `distance` relation with an explicit `center` and a `max` radius in meters, and `filters.items`.
* `lookup_locations` returns locations by ID, such as `gid://shopify/Location/123`. It processes the first 10 distinct IDs. If you send more, the response includes a `batch_limit_applied` message, and you can send the rest in another request.

Each location includes its `id`, `name`, `address`, and `geo` coordinates when the merchant has set them. Search returns 10 locations by default, and up to 250 when you set `pagination.limit`. To get the next page, pass the `pagination.cursor` from the response.

`filters.items` accepts up to 10 product variant IDs. A location matches only when every variant is available there. Availability follows Shopify's existing store availability rules. It isn't a stock count, a pickup promise, or a reservation.

Shopify doesn't support the `hours` and `amenities` filters, custom filters, or the `serves` relation. Requests that include them return an `invalid_input` error instead of ignoring them. Pickup checkout for a selected location isn't supported.

## How to set it up

Platforms and agents that use Shopify's storefront MCP endpoint with UCP `2026-08-25` and negotiate either location capability are affected.

Shops without a retail location don't advertise these capabilities or tools. Integrations that don't declare them, or that negotiate an earlier UCP version, aren't affected.

## What to do

1. Declare `dev.ucp.common.location.search` and `dev.ucp.common.location.lookup` at version `2026-08-25` in your agent profile.
2. Call the location tools only when the shop's profile lists them.
3. Send `distance.center` only from a location that the buyer chose to share. Shopify never infers a center from context or IP address.
4. Treat item matches as provisional. Confirm availability and fulfillment options in cart and checkout before you tell the buyer that an item is ready.

## Related docs

* [Configure agent profiles and UCP negotiation](https://shopify.dev/docs/agents/profiles)
* [Review the UCP location specification](https://ucp.dev/2026-08-25/specification/common/location/)