feat!: [DRAFT] fulfillment methods on catalog

[igrigorik]

WIP / RFC — schemas validate and docs render, but naming and scope are open. See #375 for related context.

Currently fulfillment extension (dev.ucp.shopping.fulfillment) describes how an order is fulfilled at checkout. This PR extends it to also compose onto catalog capability (catalog.search, catalog.lookup, get_product), so a catalog variant can advertise how it can be received — shipping, pickup, etc. It's the same extension applied to a second surface. On a variant it exposes fulfillment.methods[], the same shape as checkout.fulfillment.methods[], so a fulfillment method is one concept a buyer/agent can reason about at discovery time and at checkout time.

---

Proposed shape follows the method-first direction discussed in RFC #375: catalog answers "how can I receive this product?" with methods as peers, and buyer-visible destinations as details of location-bound methods.

One notable departure: #375 sketched polymorphic destinations -- distinct destination types as peers. This PR instead treats the kind of place as a property of the method type, leaving the destination a single (monomorphic) shape. tl;dr: a polymorphic destination union is ambiguous under open (additionalProperties: true) schemas, and moving place-kind onto the method dissolves that rather than patching it. Same goal, but via different / simpler mechanism.

Request — context and filters.fulfills_to are distinct

{
  "query": "electric kettle",
  "context": {
    "address_country": "CA",
    "address_region": "ON"
  },
  "filters": {
    "fulfills_to": {
      "address_country": "CA",
      "address_region": "ON",
      "postal_code": "M5B 2H1"
    }
  }
}

• context (coarse locale) is a non-binding hint: the business uses it to report availability — "given roughly where I am, what's available?" — and never removes results.
• filters.fulfills_to (a postal address) is a filter: it restricts results to what the business can fulfill to that destination.
• When both are present, fulfills_to is authoritative and wins; context is the fallback. fulfills_to takes an address, not a store id — discovering a specific store is a separate capability (see Direction).

Response — fulfillment.methods[] on the variant

{
  "products": [
    {
      "id": "prod_kettle",
      "title": "Electric Kettle",
      "variants": [
        {
          "id": "var_ss",
          "availability": { "available": true, "status": "in_stock" },
          "fulfillment": {
            "methods": [
              {
                "type": "shipping",
                "description": { "plain": "Ships to your address" },
                "destinations": [
                  {
                    "id": "address",
                    "availability": { "available": true, "status": "in_stock" }
                  }
                ]
              },
              {
                "type": "pickup",
                "description": { "plain": "Pickup today at Downtown Store" },
                "destinations": [
                  {
                    "id": "loc_downtown",
                    "name": "Downtown Store",
                    "address": { "address_country": "CA", "postal_code": "M5B 2H1" },
                    "availability": { "available": true, "status": "in_stock" }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

Key design decisions

• Method-first, symmetric with checkout. fulfillment.methods[] lists peer methods; the same shape appears on checkout, so a method is one concept across both surfaces.
• Place-kind on type; the destination is monomorphic. The kind of place a method delivers to (a store, a locker, the buyer's address) is part of the receive experience — the method type — not a property of the destination. So every destination is one shape, { id, name?, address?, availability }, and a new place-kind is a new type value, not a new schema. This avoids a polymorphic destination oneOf, which is ambiguous under additionalProperties: true (a store also validates as a bare shipping address). For shipping, id is the reserved value address; for pickup it's the store/location id.
• type is an open string with documented well-known values (shipping, pickup). New methods are added additively via the spec; consumers ignore values they don't recognize. (Checkout's type, previously a closed enum, opens to the same vocabulary.)
• Advisory; selection at checkout. Catalog advertises statelessly. A destination id discovered here can be carried into cart/checkout as selected_destination_id; checkout can also present its own destinations.

[maximenajim]

The one area where I think this gets a little constrained is that the “how” of fulfillment — the method — and the “where-kind” of fulfillment — store, locker, partner counter, or the buyer’s own address — can vary independently.

One possible lightweight option is to add a single optional destination_type field:

"destination_type": {
  "type": "string",
  "description": "Kind of place this destination is. Open enum; well-known values: `store`, `locker`, `pickup_point`, `address`. Consumers MAY ignore unknown values.",
  "enum": ["store", "locker", "pickup_point", "address"]
}

The nice thing about this is that simpler platforms can ignore it and continue to work with a single destination shape. At the same time, it gives us a clean way to distinguish a locker handoff from a store counter or partner pickup point, which is important for flows like Drive Up, in-store pickup, and partner pickup.

As a bonus, this could let us retire the id == "address" sentinel, since destination_type: "address" would carry the meaning currently being overloaded into the magic ID.

[maximenajim]

One concrete use case I want to make sure this design still supports is the Target.com experience today, where Pickup and Drive Up are search filters. A guest can narrow the entire result set to items they can collect this afternoon. I think there are two gaps in the current shape that make that hard to express on this surface.

First, fulfills_to filters by where — an address — but we don’t currently have a way to filter by how. In other words, there isn’t a server-side way to ask for “only items available for pickup.” The response does advertise fulfillment methods per variant, so a platform could theoretically over-fetch and post-filter client-side. But at search scale, that is not really a substitute for letting the business restrict and rank the result set server-side.

Second, Drive Up is effectively curbside fulfillment, and curbside is not currently part of the well-known vocabulary. Under the “consumers may ignore unknown values” rule, if we mint that value ourselves, it may disappear on platforms that don’t recognize it. That would make one of our highest-volume fulfillment methods invisible at discovery time.

I think the fix can be small and consistent with the pattern this PR already establishes: add an optional method_types[] array to fulfillment_search_filters, next to fulfills_to. That, combined with promoting curbside to a well-known value through the RFC path, would make today’s Target.com filter rail expressible end to end. Happy to bring the exact schema text if helpful.