Discover a merchant's retail stores with UCP location search and lookup
Shopify developer change
MerchantDiff detected this entry in Shopify's official developer changelog on October 22, 2026.
This Shopify update is categorized as UCP, New, 2026-08-25.
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.
Who is affected
Shopify app developers using the API or platform feature named in this update should review the official change.
What action may be needed
Declare dev.ucp.common.location.search and dev.ucp.common.location.lookup at version 2026-08-25 in your agent profile. Call the location tools only when the shop's profile lists them. Send distance.center only from a location that the buyer chose to share. Shopify never infers a center from context or IP address.
Use the official Shopify entry below as the source of truth for technical implementation details, affected APIs, migration instructions and deadlines.
Want the actionable version?
MerchantDiff monitors Shopify API changes, deprecations, deadlines and ecosystem updates, then turns them into developer-focused release intelligence: what changed, who is affected and what action may be needed.
Get MerchantDiff →