fix: replace Location inventory filtering with item availability

[igrigorik]

Follow-up to #589 and #765.

Replaces Location's inventory- and status-shaped filters.inventory objects with one cross-vertical discovery predicate:

{
  "filters": {
    "items": ["item_1", "item_2"]
  }
}

A candidate Location matches only when the Business can currently provide every referenced item at that Location. The same filter applies to Location Search and Lookup. Search discovers candidate Locations; Lookup resolves requested Location identifiers and then refines the resolved set using the same availability semantics.

How/why per-item status exposed the underlying problem

The previous request shape paired each opaque item identifier with an optional open status string:

{
  "filters": {
    "inventory": [
      {
        "id": "item_1",
        "availability_status": "in_stock"
      }
    ]
  }
}

Trying to make that status interoperable exposed several different concepts hiding behind one field:

• in_stock describes a retail inventory implementation;
• preorder and backorder describe order acceptance and timing policies rather than the same kind of stock state;
• fulfillment timing answers when or how an accepted item can be fulfilled, not whether a Location can currently provide it;
• unfamiliar status strings need explicit consumer behavior, not merely an open JSON Schema string.

The old filter could establish aggregate predicate truth: a returned Location implied that every requested item/status predicate matched. But the Location-shaped response could not report an authoritative current status for each item or identify which item caused an omitted Location to fail.

Why availability, not inventory

Availability is an existing and generic cross-vertical concept because it standardizes only that question—whether the Business can currently provide the referenced item at the Location—and leaves the computation to the Business. The identifiers remain opaque and Business-scoped, so the applicable item-owning domain determines whether a reference denotes a product variant, dish, appointment-based service, ticket, or another orderable item; Location does not standardize the item's internal model -- inventory is a more loaded term, by contrast.

Design

filters.items is a nonempty array of distinct, nonempty, opaque, Business-scoped item identifiers:

{
  "distance": {
    "center": {
      "latitude": 40.707,
      "longitude": -74.011
    },
    "max": 10000
  },
  "filters": {
    "items": [
      "item_id_phone_15_pro",
      "item_id_phone_15_pro_case_black"
    ]
  }
}

For each candidate Location:

within distance.max of distance.center
AND can currently provide item_id_phone_15_pro
AND can currently provide item_id_phone_15_pro_case_black

The contract is deliberately small:

• all item identifiers combine with AND;
• availability is evaluated from the Business's current data while processing the request;
• unknown, unavailable, and non-evaluable items make the candidate Location fail the filter;
• the Business must not ignore an item identifier and return broadened results;
• ordinary availability non-matches return an empty or refined Location result, not a request error;
• the Location response remains Location-shaped and does not echo per-item status or diagnostics;
• returned results are provisional and must be revalidated as the commerce flow acquires configuration, quantity, method, and transaction context.

Why this shape

The alternatives each introduced the wrong semantics or the wrong level of abstraction:

• filters.inventory exposes an implementation concept rather than the cross-vertical commerce fact.
• availability_status invites a shared status vocabulary that mixes stock, purchase policy, lifecycle, timing, and presentation without a corresponding item-result surface.
• filters.available states the predicate but is broad enough to read as applying to another Location fact, including whether an amenity is available.
• filters.availability: [id] names a data domain but gives it only a bare identifier array.
• a root availability: {"items": [...]} wrapper reserves a namespace whose likely future siblings—quantity, method, status, and time—belong to other capabilities and have no distinct Location processing or response contract.
• OR or configurable match modes would return a Location without revealing which items matched, recreating the missing item-result problem. The base filter therefore guarantees that every supplied identifier matches.

filters.items is intentionally operand-centric: the field supplies the item identifiers, while its normative schema and prose definition supply the current-availability predicate. This trades some local readability for a key that cannot be mistaken for availability of amenities or other Location facts. It does not weaken or broaden the availability contract.

The array shape is capability-local. Location binds candidate Locations, so the request supplies the item identifiers whose availability must hold at each candidate. An item-oriented capability binds candidate items and can express availability as a Boolean constraint over those candidates. This PR does not introduce or constrain a Catalog filter shape.

---

Capability boundaries contract

The filter establishes a staged discovery contract rather than transaction truth:

Capability	Responsibility
Location	Find or refine places where the Business can currently provide every referenced item.
Catalog	Identify and describe the items. With Fulfillment active and a shortlisted Location supplied in context.location, evaluate item-level fulfillment methods for that Location.
Cart	Add the Buyer's concrete item configurations and quantities.
Checkout + Fulfillment	Revalidate the actual basket, including grouping and splits, destination, method, windows and options, prices, eligibility, and terms.

These boundaries have concrete consequences:

• Operating hours are independent. A closed Location may still report that it can currently provide an item. A Platform that needs both facts supplies both filters.items and filters.hours; hours.open_at does not change the availability evaluation instant.
• Fulfillment methods are independent. Item availability at a Location does not establish pickup, delivery, dine-in, or another mode.
• Amenities do not create item-method correlation. Combining filters.items with a pickup amenity means that the items are available at the Location and that the Location generally supports pickup. It does not prove that those items are available through pickup.
• Quantity is cart/checkout responsibility. Location does not evaluate a Platform-selected quantity or assert that all requested items and quantities can be transacted together.
• Selection is out of scope. A matching Location is not a reservation, destination selection, fulfillment-method selection, or guarantee of checkout success.

End-to-end examples

Retail store finder

A Platform starts with two Catalog variant identifiers for a phone and case.

1. It calls Location Search with distance and filters.items: ["phone_variant", "case_variant"] to shortlist nearby stores that can currently provide both items.
2. If the Buyer needs a store that is open on arrival, it separately adds filters.hours.open_at. If it adds a pickup amenity, that proves only that the store generally supports pickup.
3. For a shortlisted Location, Catalog with Fulfillment active and that Location in context.location identifies the variants and evaluates their item-level fulfillment methods there.
4. Cart captures the selected configurations and quantities.
5. Checkout with Fulfillment revalidates whether the complete basket can be grouped or split, whether pickup is actually available for those lines at the selected Location, the applicable window or option, and the final price and terms.

A Location Search match keeps the first step fast and cross-vertical without pretending to answer steps three through five.

Restaurant branch discovery

A Platform has opaque menu-item identifiers for a dish and side.

1. It calls Location Search with filters.items: ["dish_id", "side_id"] and either distance or serves to find branches that can currently provide both offerings.
2. The Business may compute that answer from menu state, ingredients, equipment, and kitchen capacity; none of those implementation details become protocol vocabulary.
3. Catalog identifies and describes the dish, side, and available option choices. Cart carries the Buyer's selected size, substitutions, add-ons, and quantities.
4. Checkout with Fulfillment determines whether the configured basket can actually be accepted together and whether pickup, delivery, or another applicable method is available on the final terms.

The same Location predicate therefore works for a store stocking products and a kitchen preparing dishes while preserving domain-specific item and transaction logic downstream.

[jingyli]

nit: Revert it back to the older "explicit spatial relations (distance, serves)" so it matches more with filters?

[jingyli]

Similar concern as the one raised in #755, this feels like we are referencing a lot of Shopping specific capabilities in the overarching documentation for Location.

Instead, can we simplify this to just:

2. **Separation of Discovery Concerns**: Each capability answers one narrow question,
and later stages revalidate earlier signals. Location answers which places can currently
provide a set of referenced items (the [`items` filter](search.md#item-availability-filter)).

[jingyli]

see Spatial Relations and Search Filters, including the Item Availability Filter.

wording nit:

see [Spatial Relations](search.md#spatial-relations),
[Search Filters](search.md#search-filters), and
[Item Availability Filter](search.md#item-availability-filter).

[jingyli]

nit: explicit spatial relations instead of explicit relations?

[jingyli]

nit: Remove standard from the bullet here?

[jingyli]

I don't think this paragraph should be updated - the original paragraph outlines the principle on when a dimension should be placed into filters vs. nested flat in the request and the edits removed that principled explanation.

[jingyli]

Related to the comment above - given we want to ensure the scope limits to Location capability and not over-reference Shopping specific capabilities, can we remove for how Catalog, Cart, and Checkout divide that work here?

[jingyli]

Standard filters are hours, amenities, and items.

Probably should remove this sentence in case the standard filters list grows in the future?

[jingyli]

structured filters.hours and filters.amenities predicates, and the filters.items current item-availability predicate.

Same here - probably don't want to explicitly list out the filter fields in the description in case it grows in the future. Same comment to the other reference below on line 69 and in rest.openapi.json