Shopify merchants with brick‑and‑mortar locations can now expose those stores to custom agents through the Unified Commerce Platform (UCP). Starting with UCP version 2026‑08‑25, two optional capabilities—dev.ucp.common.location.search and dev.ucp.common.location.lookup—are available on the storefront MCP endpoint. This post breaks down the change, who needs to act, and provides ready‑to‑copy code examples.
What’s New
• search_locations – Returns a paginated list of retail locations. You can filter by name, city, distance (center + radius) and by product variant availability (filters.items).
• lookup_locations – Retrieves specific locations by their global ID (e.g., gid://shopify/Location/123). Up to 10 IDs are processed per request; excess IDs trigger a batch_limit_applied message.
Who Is Affected?
How to Enable the Capabilities
{
"ucpVersion": "2026-08-25",
"capabilities": [
"dev.ucp.common.location.search",
"dev.ucp.common.location.lookup"
]
}
bash
curl https://myshop.myshopify.com/.well-known/ucp | jq '.capabilities'
If the response includes "dev.ucp.common.location.search" or "dev.ucp.common.location.lookup", you can safely call the corresponding MCP endpoints.
Sample Requests
Search locations – basic (first 10 stores):
POST https://myshop.myshopify.com/api/ucp/mcp
Content-Type: application/json
{
"search_locations": {
"pagination": { "limit": 10 }
}
}
Search with filters – find stores within 5 km of the buyer’s chosen point that carry two specific variants:
POST https://myshop.myshopify.com/api/ucp/mcp
Content-Type: application/json
{
"search_locations": {
"filters": {
"items": ["gid://shopify/ProductVariant/111", "gid://shopify/ProductVariant/222"]
},
"distance": {
"center": { "lat": 37.7749, "lon": -122.4194 },
"max": 5000
},
"pagination": { "limit": 20 }
}
}
Lookup specific locations – retrieve details for three known IDs:
POST https://myshop.myshopify.com/api/ucp/mcp
Content-Type: application/json
{
"lookup_locations": {
"ids": [
"gid://shopify/Location/123",
"gid://shopify/Location/456",
"gid://shopify/Location/789"
]
}
}
Best Practices & Gotchas
Conclusion & Next Steps
The new UCP location search and lookup capabilities give developers a powerful way to surface in‑store inventory and guide shoppers to the nearest store that actually has the product. By updating your agent profile, checking the shop’s discovery capabilities, and following the request patterns above, you can start building richer omnichannel experiences today. Keep an eye on Shopify’s official UCP location specification for any future enhancements, and consider adding UI cues that let buyers share their location safely.
Ready to bring your customers back to the storefront? Update your integration now and let shoppers see exactly where they can pick up their favorites!
