UCP location search is a protocol capability that lets an AI agent find a merchant’s physical stores, check their hours and pickup features, and ask which ones currently stock an item. On October 22, 2026, Shopify’s developer changelog listed an entry titled “Discover a merchant’s retail stores with UCP location search and lookup”. This note reads what the capability actually specifies, from the spec repository.

We could only read the changelog headline, not the entry body. Everything below about behaviour comes from the UCP specification, not from Shopify’s implementation.

What the Location capability is

The UCP specification defines two location capabilities: dev.ucp.common.location.search and dev.ucp.common.location.lookup. Search finds locations by free text, spatial relation and filters. Lookup returns full details for locations you already have identifiers for.

It was added in the v2026-08-25 release, per the commit that introduced it (tagged in v2026-08-25). The spec names its first use case as local pickup discovery: finding nearby stores that support buyer pickup, checking operating hours, and seeing where selected items are currently available.

What an agent can ask a store

A search request combines these inputs, and every explicit constraint must match:

  • distance: a center point and an inclusive radius.
  • serves: whether a location can serve one explicit target, such as an address. The business, not the agent, is authoritative for that answer.
  • filters.hours: open at a given instant.
  • filters.amenities: exact reverse-DNS identifiers. The spec lists dev.ucp.amenity.shopping.in_store_pickup and dev.ucp.amenity.shopping.curbside_pickup among well-known values.
  • filters.items: a list of item identifiers; a location matches only if every item is currently available there.

Free text never overrides these. The spec says a business must not treat “near me” in the query as a distance or filter.

Where the data stays provisional

The spec is explicit that discovery answers are not commitments. Hours, amenities and item availability are “provisional signals”, and final pickup terms must be negotiated at checkout.

Two details matter for merchants:

  • Unknown is not the same as available. An item identifier that is unknown, unavailable or cannot be evaluated at a location makes that location fail the item filter. The business must not ignore it to return broader results.
  • Missing hours mean unknown, not closed. The spec says absent hours means the regular schedule is unknown. A temporary closure is expressed as an exception_hours entry with dates and no opening times.

The items filter plus a pickup amenity does not prove an item is available for pickup. The spec says the two predicates stay independent and that method-qualified store finding needs another capability.

What it means for a store with physical locations

If you run stores or lockers, the fields an agent can filter on are fields you should be able to answer cleanly:

  • Opening hours per location, with a timezone and dated exceptions for holidays.
  • Which locations offer in-store or curbside pickup.
  • Per-location stock at the variant level, since item identifiers are variants or menu items.
  • A stable location identifier that survives into checkout. The fulfillment extension has the agent select a location by its Business-scoped ID rather than typing an address.

The spec does not say how many agents call location search today, and the changelog headline does not say which stores expose it by default. Check your own profile before assuming.

FAQ

What is UCP location search?

It is a Universal Commerce Protocol capability, dev.ucp.common.location.search, that lets an AI agent search a merchant’s physical locations by distance, serviceability, opening hours, amenities and current item availability. A companion lookup capability returns full details for known location identifiers.

Does a location search result mean the item is reserved for pickup?

No. The UCP spec calls the result a coarse, provisional assertion. It does not reserve an item, check quantities or select a fulfillment method, and the business must revalidate availability and terms later in checkout.

What happens if my store does not publish opening hours?

The spec treats absent hours as an unknown regular schedule, not as closed. An agent filtering on opening time may therefore not be able to match that location, so publish hours and dated exceptions where you can.

Sources

A pickup flow only works if hours, stock and location IDs are answerable by a machine, which is the transaction-level readiness AgentReady measures.