UCP / Storefront MCP / New feature

UCP Location Search & Lookup
Let AI agents find nearby physical stores and stores that have items in stock

Starting with UCP 2026-08-25, Shopify storefront MCP endpoints offer search_locations / lookup_locations two tools. Agents can filter a merchant's physical stores by name, city, distance, and products carried. This is an optional new feature, so no action is needed if you don't use it.

What's on this page
  1. What's changing (30-second overview)
  2. How it works: discovery → negotiation → tool calls
  3. Two tools: search and lookup
  4. Parameters and limits at a glance
  5. What's not supported and who's affected
  6. How to adopt it (4 steps)
  7. 5 key points for developers
  8. 3 business use cases
  9. One-line summary for proposals

1What's changing

Starting with UCP 2026-08-25, Shopify storefronts support the UCP location capability(dev.ucp.common.location.search / dev.ucp.common.location.lookup).
Once an agent negotiates this capability, it canfind the merchant's physical stores, filter them by name, city, and distance, and check which stores carry the products a buyer wants.
?

Before: physical stores weren't visible

These two tools weren't available, so agents using UCP couldn't look up a merchant's physical store information.

Now: stores can be searched and looked up

The storefront MCP endpoint now exposes search_locations and lookup_locations . This is an optional new feature, so no changes are needed if you don't use it.

2How it works: discovery → negotiation → tool calls

Store setup An active, merchant-managed location with in-person selling + Physical storefront enabled = at least one retail location Discovery In /.well-known/ucp, location search / lookup Both are listed Not listed if there are no stores Agent In the agent profile, declare version 2026-08-25 to negotiate No impact if not declared /api/ucp/mcp search_locations List and filter lookup_locations Fetch by ID Two tools are exposed
Definition of a retail location : active, merchant-managed, configured for in-person sales, andPhysical storefront enabled as a location.
The MCP endpoint is https://{storedomain}/api/ucp/mcp.

3Two tools: search and lookup

search_locations

List and filter the shop's physical stores

  • Empty location object → returns the first page
  • query : matches store name and city
  • distance : explicit center point + maximum radius (meters)
  • filters.items : filter by products carried
  • Defaults to 10;pagination.limit allows up to 250
  • For the next page, pass the response's pagination.cursor value
gid lookup_locations

Fetch stores by ID

  • Example ID: gid://shopify/Location/123
  • Processes only the first 10 unique IDs at most
  • If exceeded, the response includes a batch_limit_applied message
  • Send the rest in a separate request

Information included for each location

ID
id
name
Store name
address
Address
geo
Coordinates (only if set)

4Parameters and limits at a glance

ItemSpecNotes
Search result count Default 10 pagination.limit , up to 250 via Next page via pagination.cursor
Lookup ID count Max 10(after deduplication) If exceeded, batch_limit_applied is returned, so split into multiple requests
filters.items Max 10 Product variant IDs Stores that carry all variantsare the only ones that match (AND condition)
distance Explicit center + maximum radius (meters) The center point must be a location shared by the buyer. Shopify does not infer it from context or IP.
query Matches store name and city —
What a product match means Follows the existing store availability rules Not inventory quantity Not a pickup guarantee or reservation either

5Unsupported features and impact

Not supported by Shopify (sending them returns an invalid_input error)

Unsupported

hours filter

Filtering by business hours.

Unsupported

amenities filter

Filtering by store amenities.

Unsupported

Custom filters

Your own filter criteria.

Unsupported

serves relation

Relations other than distance.

These arenot ignored; invalid_input they return an error. Also,pickup checkout at the selected store is not supported.

Affected / not affected

Affected

Who's in scope

Platforms/agents that use the Storefront MCP endpoint with UCP 2026-08-25 and negotiate either location capability.

Not affected

Out of scope

Shops without retail locations (neither the capability nor the tools are listed). Integrations that don't declare the capability, or that negotiate on an earlier UCP version.

6How to adopt (4 steps)

1

Declare in your agent profile

dev.ucp.common.location.search and .lookup declared at version 2026-08-25.

2

Check the profile

Only call the location tools when they're listed in the shop's profile.

3

Location is consent-based

distance.center is sent only from a location the buyer chose to share.

4

Re-verify in cart/checkout

Treat product matches as provisional. Confirm inventory and delivery method before telling buyers an item is "ready."

Integrations that don't currently use locations need no changes.Fully opt-in: behavior doesn't change unless you declare it.

75 key points for engineers

.well-known

1. Branch calls based on capabilities

Shops without retail locations expose neither the capability nor the tools./.well-known/ucp — check that profile and call the tools only when they're listed.

2. Unsupported parameters return errors

hours / amenities / custom filters / serves arenot ignored—they cause an error invalid_inputIf you reuse a generic UCP client, strip these before sending requests to Shopify.

3. Design around paging and batch limits

search defaults to 10 results (max 250), with cursors for further pages. lookup accepts up to 10 IDs after deduplication; for overflow, check batch_limit_applied and resend in smaller batches.

4. Location only from explicit buyer sharing

distance.center comes only from a location the buyer chose to share. Shopify also doesn't infer a center point from context or IP. Treat this as a baseline privacy-design assumption.

? ✓

5. filters.items is only a "provisional match"

It's an AND condition across up to 10 variants and follows existing store inventory display rules.It is not an inventory count, a pickup guarantee, or a reservation. Pickup checkout at the selected store also isn't supported, so keep agent responses to "stores likely to have it in stock" and confirm in cart/checkout.

83 practical use cases

USE CASE 1

"Nearby stores" guidance in a shopping agent

Challenge
Brands with physical stores can't direct buyers arriving via AI agents to store locations, leaving online and offline journeys disconnected.
Approach
Once the buyer consents to share their location search_locations , pass distance (a center point plus a radius in meters) to surface nearby stores with names and addresses.
Impact
Creates a path from an agent conversation to an in-person store visit.
Tech notes
Without shared location, skip distance and fall back to searching by query (store name or city).
Product A Product B Product C
USE CASE 2

Find a store that carries everything the buyer wants to buy together

Challenge
Point buyers who want to see multiple items in person, such as a complete outfit or a gift set, to a store that carries all of them.
Approach
Put the variant IDs the buyer selected (up to 10) into filters.items and search. Only stores that carry every variant are returned.
Impact
Lets you suggest stores in a way that cuts down on "I went, but they didn't have it."
Tech notes
Results don't reflect inventory counts or reservations, so keep the wording to "stores that carry this item" and confirm at cart or checkout.
gid://.../Location/1 gid://.../Location/2 gid://.../Location/3 cursor →
USE CASE 3

Store data sync for agent integration platforms

Challenge
Platforms serving multiple merchants need a way to fetch and refresh each shop's list of physical stores.
Approach
Target only shops whose profile includes the location capability, and usesearch_locations with pagination.limit 250 plus a cursor to fetch everything. After that, re-fetch saved IDs with lookup_locations .
Impact
Handle store information (name, address, coordinates) in bulk through a standard UCP mechanism.
Tech notes
Batch lookups in groups of 10 IDs, and resend the remainder when you detectbatch_limit_applied . geo is only present if the merchant has set it, so tolerate missing values.

9One-line summary for proposals

"With UCP 2026-08-25, AI agents can search and look up Shopify merchants'physical stores and narrow them down to ones that carry the products buyers want.
It's opt-in, so existing integrations are unaffected. Location is based on buyer consent, and product matches are provisional, to be confirmed at checkout."