Skip to main content

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

Shopify storefronts now support the UCP location capability, 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

Was this page helpful?