[RFC] Store-Based Local Inventory & Fulfillment Options

[maximenajim]

RFC: Store-Based Local Inventory & Fulfillment Options

New capability: dev.ucp.shopping.locations
Extended capabilities: dev.ucp.shopping.fulfillment, dev.ucp.shopping.catalog.search, dev.ucp.shopping.catalog.lookup, dev.ucp.shopping.order
Staged rollout: 3 PRs — Foundation → Methods → Locations & Availability (see Appendix A)

---

Summary

This RFC proposes extensions to the Unified Commerce Protocol (UCP) to support
store-based local inventory visibility and expanded fulfillment options
beyond the current shipping and pickup method types. Today, UCP treats
product availability as a single global boolean and limits fulfillment to two
method types. This is insufficient for retailers that operate thousands of
physical locations, each with independent inventory, and offer fulfillment
modes such as same-day delivery, curbside pickup, and buy-online-pickup-in-store
(BOPIS).

This proposal introduces:

1. A per-location, per-method inventory availability model, with a business
   opt-in for disclosure (retailers with competitively sensitive per-SKU
   per-store inventory can participate in pickup without disclosing it)
2. An enriched retail location entity with first-class holiday/exception hours
3. Distinct types for customer-visible fulfillment origins vs. internal
   fulfillment nodes (with structural, not prose, enforcement of the
   visibility boundary)
4. Two new fulfillment method types (curbside, local_delivery) with
   qualifiers for origin and transfer scenarios, plus a documented criterion
   for what promotes a method to top-level status
5. Quantity-aware line_item_ids[] so a single line item can split across
   fulfillment methods (e.g., 2 pickup + 3 shipped)
6. Location-aware catalog search and lookup (the canonical place for
   per-variant per-location availability)
7. A standalone Locations capability (locations-only, no per-variant
   inventory — that lives in catalog)
8. Post-purchase lifecycle events for pickup and local delivery flows, with
   corrected tracking_number semantics
9. A first-class Fulfillment Option Eligibility model so membership-gated
   options (e.g., "Circle 360 members get free same-day delivery") have a
   concrete resolution story
10. MUST-level privacy rules for buyer geo, with platform-derived coarse geo
    routed through the signals mechanism

Scope boundary: This RFC explicitly defers digital (already handled by
UCP via omitting fulfillment), in_store_only (modeled as an availability
restriction, not a checkout method), and treats ship_from_store /
ship_to_store as qualifiers on existing methods rather than new top-level
types. See Design Rationale.

---

Motivation

The Problem

Modern omnichannel retailers maintain inventory across thousands of stores and
distribution centers. Customers increasingly expect to:

• See what's available nearby — "Is this in stock at my local store?"
• Choose how they get it — Ship to home, pick up in store, curbside,
  same-day delivery from a nearby store
• Get it fast — Same-day or next-day fulfillment from local inventory

UCP's current model cannot express these scenarios:

1. Variant availability is global — variant.availability is a single
   { available: boolean, status: string } with no per-location granularity.
   A platform cannot tell a buyer "in stock at Store A, out of stock at
   Store B," nor can it express that an item is available for pickup but not
   for local delivery at the same location.

2. Fulfillment method types are limited — The fulfillment_method.type
   enum only includes "shipping" and "pickup". There is no way to represent
   local_delivery or curbside as first-class method types with distinct
   buyer experiences.

3. Retail location is underspecified — retail_location.json only has id,
   name, and optional address. There are no fields for geo-coordinates,
   operating hours, store type/format, distance from buyer, phone number,
   capabilities, or services offered.

4. No location context from buyer — context.json has postal_code and
   address_region but no latitude/longitude for proximity-based experiences.
   The existing eligibility array can signal membership claims via
   reverse-domain names, but there is no structured mechanism for fulfillment
   eligibility decisions beyond opaque string claims.

5. Catalog search and lookup are location-unaware — There is no mechanism
   to filter or rank catalog results by store-level availability.
   catalog_search.json has no location filter, and catalog_lookup.json
   (where PDP-style "is this in stock near me?" queries occur) has no way to
   request per-location availability.

6. No location-finding capability — There is no API to discover nearby
   stores, check which stores carry a product, or find the closest store
   with inventory.

7. No fulfillment origin — Post-purchase, there is no way to communicate
   which store or warehouse is fulfilling an order. fulfillment_group.json,
   expectation.json, and fulfillment_event.json all lack an origin field.

8. Post-purchase events are shipment-centric — fulfillment_event.type
   covers processing, shipped, in_transit, delivered, etc. There are no
   event types for pickup readiness (ready_for_pickup), curbside arrival
   (arrived), local delivery dispatch (out_for_local_delivery), or store
   transfer arrival (arrived_at_store). The existing schema also says
   tracking_number is "required if type != processing" — which is incorrect
   for in-store events.

9. No structured unavailability reasons — When a fulfillment method is
   unavailable, there is no machine-readable reason — only a human-readable
   description. Platforms cannot programmatically suggest alternatives.

10. No pickup windows, hold durations, or order cutoffs — There is no way
    to express when an order will be ready for pickup, how long a store will
    hold it, or the deadline to place an order for a given fulfillment option.

11. No quantity-aware split fulfillment — fulfillment_method.line_item_ids
    is string[], meaning each line item belongs to exactly one method.
    Retailers routinely satisfy one quantity locally and others from a DC
    (e.g., "2 ready for pickup, 3 ship tomorrow"). UCP cannot express this.

12. No first-class membership-gated fulfillment eligibility — Many
    retailers offer member-only fulfillment (e.g., Circle 360 → free Shipt
    same-day delivery, Walmart+ → free grocery delivery). context.eligibility
    provides claims but there is no protocol-level binding between a claim
    and a fulfillment option.

Who Benefits

• Platforms (agents): Can present location-aware availability, show nearby
  store options, and offer richer fulfillment choices without custom
  integrations per retailer.
• Businesses (retailers): Can expose their omnichannel capabilities through
  UCP rather than requiring buyers to fall back to continue_url for
  store-specific flows. Retailers with sensitive per-store inventory can
  opt out of disclosure while still supporting pickup.
• Buyers: Get faster, more transparent fulfillment with visibility into
  local availability and options.

Goals

• Enable per-location, per-method inventory availability queries through UCP
  (with business opt-in to per-store inventory disclosure)
• Extend the fulfillment method type enum with two new buyer-facing primitives:
  curbside and local_delivery
• Model ship_from_store and ship_to_store as qualifiers (origin on groups
  and transfer flag on groups) rather than top-level method types
• Enrich the retail_location entity with geo-coordinates, weekly hours,
  first-class exception_hours (for holidays/remodels/temporary hours),
  capabilities, distance, contact information, store format, and status
• Introduce separate customer_visible_origin and internal_origin types
  (unified by a fulfillment_origin oneOf) so internal fulfillment nodes
  structurally cannot carry rendered fields
• Add buyer location context (lat/lng) to context.json with MUST-level
  privacy rules; route platform-derived coarse geo through the existing
  signals mechanism
• Add structured unavailability reasons (closed enum) distinct from
  availability status
• Add pickup windows, hold durations, order cutoff times, and minimum order
  quantities to fulfillment options
• Add post-purchase event types for pickup and local delivery lifecycle,
  with corrected tracking_number semantics
• Enable location-aware catalog search and lookup (the canonical home for
  per-variant per-location availability)
• Define a standalone dev.ucp.shopping.locations capability (locations-only;
  inventory queries are catalog operations)
• Introduce quantity-aware line_item_ids[] so split-quantity fulfillment
  across methods is expressible
• Define a first-class eligibility-option binding for membership-gated
  fulfillment
• Maintain backward compatibility — existing shipping and pickup flows
  remain unchanged

Non-Goals

• Internal order routing/allocation logic — UCP does not dictate how a
  business decides which store fulfills an order; it only provides the
  interface to expose options and status to platforms.
• Real-time inventory count exposure — UCP will express availability
  status per location per method, not exact stock quantities (which are
  operationally sensitive).
• Store operations workflows — Pick lists, hold bins, employee handhelds,
  and internal store processes are out of scope.
• Delivery zone management UI — Businesses define their service areas
  internally; UCP provides the interface to express availability per method
  per location.
• Third-party delivery provider integration — UCP models the fulfillment
  option; the business manages its relationship with delivery providers.
• Digital fulfillment — UCP already handles digital goods by allowing
  checkout fulfillment to be omitted and by including digital in
  expectation.method_type. This RFC does not add digital as a new
  fulfillment method type.
• In-store-only as a checkout method — Items only purchasable in-store are
  modeled as availability restrictions (method_availability with
  unavailability_reason: "in_store_only" on all non-store methods), not as
  a selectable fulfillment method in the checkout flow.
• Age-verification / prescription workflows — Regulated items (alcohol,
  pharmacy) are flagged via unavailability_reason: "restricted" or
  "in_store_only", but the identity-verification workflow is out of scope
  and expected to land in a separate RFC coordinated with the identity-linking
  mechanism registry.

---

Protocol Integration Model

This RFC follows UCP's existing extension pattern as documented in the
fulfillment specification's "Adding New Methods" section, with a small
governance clarification:

1. New method types (curbside, local_delivery) are
   protocol-blessed additions to the base fulfillment_method.type enum,
   not retailer-specific extensions. §12
   updates fulfillment.md's "Adding New Methods" section to distinguish
   two paths:

   • Protocol-blessed methods (like these): added to the base enum via
     an RFC and a dev.ucp.shopping.fulfillment capability version bump.
   • Vendor-defined methods: still require an extension schema and
     reverse-domain naming.

2. Enriched retail_location, new types (customer_visible_origin,
   internal_origin, fulfillment_origin, location_availability,
   method_availability, availability_summary), and new fields on existing
   types are additive schema changes.

3. dev.ucp.shopping.locations is a new standalone capability, declared
   via capability negotiation in the business profile. Platforms that don't
   support it simply don't call it.

4. Location-aware catalog extends catalog_search.json and
   catalog_lookup.json with optional location_filter. Per-variant,
   per-location availability is returned via catalog, not via the locations
   capability (see §10 for the rationale).

Proposed staged rollout

This RFC lands as three sequenced PRs to make review tractable:

1. Foundation PR — retail_location (enriched with geo, hours, exception
   hours, capabilities, etc.), customer_visible_origin, internal_origin,
   fulfillment_origin (oneOf), origin on fulfillment_group,
   expectation, and fulfillment_event, context.geo privacy rules, and
   the new signals["dev.ucp.shopping.geo"] signal.
2. Methods PR — New method types (curbside, local_delivery),
   fulfillment_option enhancements (windows, hold, cutoff, eligibility
   depend-on), transfer_origin on fulfillment_group, fulfillment_event
   new event types + corrected tracking_number semantics, quantity-aware
   line_item_ids[], business_fulfillment_config four-way matrices and
   disclosure toggles, and cleanup of the merchant_fulfillment_config.json
   duplicate.
3. Locations & Availability PR — dev.ucp.shopping.locations capability,
   location_availability and method_availability types,
   availability_summary, location_filter on catalog,
   business_fulfillment_config.discloses_location_availability.

[maximenajim]

Detailed Design

1. Enriched Retail Location Entity

File: source/schemas/shopping/types/retail_location.json (Foundation PR)

Extend the current minimal model with rich metadata, including first-class
exception_hours. retail_location is the customer-visible destination
type — stores, lockers, and other locations that buyers can select for
pickup. Internal inventory nodes that should never be buyer-selectable use
the separate internal_origin type (§2).

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/retail_location.json",
  "title": "Retail Location",
  "description": "A customer-visible retail location (store, locker, etc.) that can serve as a fulfillment destination.",
  "type": "object",
  "required": ["id", "name"],
  "additionalProperties": true,
  "properties": {
    "id": { "type": "string", "description": "Unique location identifier." },
    "name": { "type": "string", "description": "Location display name (e.g., 'Acme Retail Downtown')." },
    "address": { "$ref": "postal_address.json", "description": "Physical address of the location." },
    "geo": {
      "type": "object",
      "description": "Geographic coordinates for proximity search and map display.",
      "required": ["latitude", "longitude"],
      "properties": {
        "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude in decimal degrees (WGS 84)." },
        "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude in decimal degrees (WGS 84)." },
        "geofence_radius": {
          "type": "number",
          "description": "Geofence radius in meters. Used for proximity detection (e.g., 'buyer has arrived' for curbside pickup)."
        }
      }
    },
    "distance": {
      "type": "object",
      "description": "Distance from the buyer's location (computed by business based on context).",
      "properties": {
        "value": { "type": "number" },
        "unit": { "type": "string", "enum": ["mi", "km"] }
      }
    },
    "location_type": {
      "type": "string",
      "enum": ["store", "locker", "pop_up"],
      "description": "Type of location. Extended values MAY be added via capability version bump."
    },
    "format": {
      "type": "string",
      "description": "Store format classification. Well-known values: 'superstore', 'express', 'outlet', 'standard', 'urban_small'. Businesses MAY define additional values using reverse-domain naming (e.g., 'com.example.mini_mart')."
    },
    "status": {
      "type": "string",
      "enum": ["open", "temporarily_closed", "closed", "coming_soon"],
      "description": "Current operational status."
    },
    "phone": { "type": "string", "description": "Contact phone number (E.164 format recommended)." },
    "hours": {
      "type": "array",
      "description": "Regular weekly operating hours by day of week. Use exception_hours to override specific dates.",
      "items": {
        "type": "object",
        "required": ["day"],
        "properties": {
          "day": { "type": "string", "enum": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"] },
          "is_closed": { "type": "boolean", "description": "If true, the location is closed on this day. When true, intervals MUST be omitted." },
          "is_24_hours": { "type": "boolean", "description": "If true, open 24 hours on this day. When true, intervals MUST be omitted." },
          "intervals": {
            "type": "array",
            "description": "One or more open intervals for this day. Supports split shifts. For overnight hours, use two entries across two days.",
            "items": {
              "type": "object",
              "required": ["open", "close"],
              "properties": {
                "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" },
                "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }
              }
            }
          }
        }
      }
    },
    "exception_hours": {
      "type": "array",
      "description": "Exception hours for specific dates (holidays, remodels, temporary closures, special events). Exception_hours entries override the weekly schedule for the given date. Platforms computing 'is this store open now?' MUST check exception_hours first, then fall through to weekly hours.",
      "items": {
        "type": "object",
        "required": ["date"],
        "properties": {
          "date": { "type": "string", "format": "date", "description": "Date in YYYY-MM-DD (local to the location's timezone)." },
          "label": { "type": "string", "description": "Reason for the exception (e.g., 'Thanksgiving', 'Store Remodel'). Optional but strongly recommended for buyer-facing messaging." },
          "is_closed": { "type": "boolean" },
          "is_24_hours": { "type": "boolean" },
          "intervals": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["open", "close"],
              "properties": {
                "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" },
                "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }
              }
            }
          }
        }
      }
    },
    "timezone": { "type": "string", "description": "IANA timezone identifier (e.g., 'America/Chicago'). Required for correct interpretation of hours and exception_hours." },
    "fulfillment_capabilities": {
      "type": "array",
      "description": "Fulfillment method types this location supports.",
      "items": { "type": "string", "enum": ["pickup", "curbside", "local_delivery", "shipping"] }
    },
    "capabilities": {
      "type": "array",
      "description": "Business-defined capabilities or services offered at this location (e.g., pharmacy, fresh grocery).",
      "items": {
        "type": "object",
        "required": ["code", "name"],
        "properties": {
          "code": { "type": "string", "description": "Machine-readable capability code (e.g., 'FRESH_GROCERY', 'PHARMACY')." },
          "name": { "type": "string", "description": "Human-readable capability name." },
          "effective_date": { "type": "string", "format": "date" },
          "hours": {
            "type": "array",
            "description": "Per-capability hours when they differ from main store hours. Uses the same day/intervals structure as the top-level hours field.",
            "items": {
              "type": "object",
              "required": ["day"],
              "properties": {
                "day": { "type": "string", "enum": ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"] },
                "is_closed": { "type": "boolean" },
                "intervals": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": ["open", "close"],
                    "properties": {
                      "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" },
                      "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "metadata": { "type": "object", "description": "Business-defined custom data extending the location model." }
  }
}

location_type and status are closed enums — extensions require a
capability version bump. format is an open string with well-known values
because format classifications legitimately vary by retailer vertical.

2. Fulfillment Origin Types (New)

Files (Foundation PR):

• source/schemas/shopping/types/customer_visible_origin.json
• source/schemas/shopping/types/internal_origin.json
• source/schemas/shopping/types/fulfillment_origin.json

Origin data splits into two distinct types unified by a oneOf wrapper.
Internal origins structurally cannot carry name, address, or distance,
so even a platform that mis-handles a visibility flag cannot leak meaningful
origin metadata — the fields simply do not exist on the internal type.

customer_visible_origin.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/customer_visible_origin.json",
  "title": "Customer-Visible Fulfillment Origin",
  "description": "A fulfillment origin that MAY be rendered to the buyer — typically a retail store when shipping from store or transferring to store. Use internal_origin for origins that MUST NOT be rendered.",
  "type": "object",
  "required": ["id", "name", "visibility"],
  "additionalProperties": true,
  "properties": {
    "id": { "type": "string", "description": "Unique origin identifier." },
    "visibility": { "type": "string", "const": "customer_visible" },
    "name": { "type": "string", "description": "Display name. MUST be provided." },
    "origin_type": {
      "type": "string",
      "enum": ["store", "locker"],
      "description": "Type of customer-visible origin. Distribution centers and warehouses are not customer-visible."
    },
    "address": { "$ref": "postal_address.json" },
    "distance": {
      "type": "object",
      "properties": {
        "value": { "type": "number" },
        "unit": { "type": "string", "enum": ["mi", "km"] }
      }
    }
  }
}

internal_origin.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/internal_origin.json",
  "title": "Internal Fulfillment Origin",
  "description": "An origin that MUST NOT be rendered to the buyer — typically a warehouse, dark store, or distribution center. Carries only an opaque identifier and an operational type. Intentionally omits name, address, and distance so that even if a platform mis-handles the visibility boundary, operationally sensitive metadata cannot leak.",
  "type": "object",
  "required": ["id", "visibility"],
  "additionalProperties": false,
  "properties": {
    "id": { "type": "string", "description": "Opaque origin identifier. Platforms MUST NOT derive or display any meaning from the value of this identifier." },
    "visibility": { "type": "string", "const": "internal" },
    "origin_type": {
      "type": "string",
      "enum": ["warehouse", "dark_store", "distribution_center", "other"],
      "description": "Operational origin type. For platform analytics only; MUST NOT be rendered to the buyer."
    }
  }
}

fulfillment_origin.json (the type referenced from group/expectation/event):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/fulfillment_origin.json",
  "title": "Fulfillment Origin",
  "description": "The facility fulfilling an order or group. Either a customer-visible origin (renderable; carries name, address, distance) or an internal origin (opaque; never rendered). Discriminated by the 'visibility' field.",
  "oneOf": [
    { "$ref": "customer_visible_origin.json" },
    { "$ref": "internal_origin.json" }
  ]
}

Design rationale: Origin data is competitively sensitive — DC locations,
routing strategy, replenishment patterns. A single-type-with-flag shape
would place the entire burden of the visibility boundary on platform
correctness. Shape-level separation enforces it structurally: a misbehaving
platform cannot render what isn't there. Businesses SHOULD use
customer_visible_origin only when the buyer-facing experience genuinely
benefits from knowing the origin (e.g., "ships from your local store").

3. Per-Location, Per-Method Inventory Availability

New types (Locations & Availability PR):

• source/schemas/shopping/types/location_availability.json
• source/schemas/shopping/types/method_availability.json
• source/schemas/shopping/types/availability_summary.json

Business opt-in: Retailers with competitively sensitive per-SKU per-store
inventory can opt out of disclosure via
business_fulfillment_config.discloses_location_availability
(see §4). When false, businesses
MUST NOT return location_availability[] on variants or per-variant
availability in locations responses, but MAY still return location metadata
(name, address, hours, fulfillment_capabilities) and an aggregate
availability_summary without per-location breakdown.

method_availability.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/method_availability.json",
  "title": "Method Availability",
  "description": "Availability of a specific fulfillment method for a variant at a location.",
  "type": "object",
  "required": ["type", "available", "status"],
  "additionalProperties": true,
  "properties": {
    "type": {
      "type": "string",
      "enum": ["pickup", "curbside", "local_delivery", "shipping"],
      "description": "Fulfillment method type."
    },
    "available": { "type": "boolean", "description": "Whether this variant can be fulfilled via this method from this location." },
    "status": {
      "type": "string",
      "enum": ["in_stock", "low_stock", "out_of_stock", "limited_stock", "backorder", "preorder", "discontinued"],
      "description": "Availability status."
    },
    "unavailability_reason": {
      "type": "string",
      "enum": [
        "out_of_stock",
        "ineligible",
        "restricted",
        "regulatory_restriction",
        "capacity_full",
        "outside_service_area",
        "in_store_only",
        "item_too_large",
        "cutoff_passed"
      ],
      "description": "Machine-readable reason when available is false or constrained. MUST be omitted when available is true and status is 'in_stock'. New values require a capability version bump; businesses needing a non-standard reason SHOULD use the 'description' field for human-readable context."
    },
    "fulfillable_on": {
      "type": "string",
      "description": "When this method becomes available. Value MUST be either the literal string 'now' or an RFC 3339 date-time (e.g., '2026-04-25T10:00:00-05:00'). Future times indicate transfer, restock, or preorder dates."
    },
    "next_pickup_window": {
      "type": "object",
      "description": "Illustrative next-available pickup window (for pickup and curbside methods). This is an availability-side promise that a window of this shape is available — the specific window bound to a chosen option is expressed separately via fulfillment_option.pickup_window.",
      "required": ["start_time"],
      "properties": {
        "start_time": { "type": "string", "format": "date-time" },
        "end_time": { "type": "string", "format": "date-time" }
      }
    },
    "hold_duration": {
      "type": "string",
      "description": "How long the store will hold the order for pickup, as an ISO 8601 duration (e.g., 'P3D' for 3 days, 'PT4H' for 4 hours)."
    },
    "order_cutoff_time": {
      "type": "string",
      "format": "date-time",
      "description": "Deadline to place an order for this fulfillment option (RFC 3339). For example, 'order by 2pm for same-day delivery'."
    },
    "minimum_order_quantity": { "type": "integer", "minimum": 1 },
    "description": { "type": "string", "description": "Human-readable availability message (e.g., 'Ready for curbside in 2 hours')." }
  }
}

location_availability.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/location_availability.json",
  "title": "Location Availability",
  "description": "Inventory availability for a variant at a specific retail location, broken down by fulfillment method. MUST NOT be returned when business_fulfillment_config.discloses_location_availability is false.",
  "type": "object",
  "required": ["location_id", "method_availability"],
  "additionalProperties": true,
  "properties": {
    "location_id": { "type": "string", "description": "Reference to a retail_location.id." },
    "location": { "$ref": "retail_location.json", "description": "Inline location details (optional, for convenience when location data is co-returned)." },
    "method_availability": {
      "type": "array",
      "description": "Per-method availability at this location.",
      "items": { "$ref": "method_availability.json" }
    },
    "quantity_hint": {
      "type": "string",
      "enum": ["many", "few", "last_one", "none"],
      "description": "Coarse quantity indicator for the location overall. 'many' = 10+ units, 'few' = 2-9 units, 'last_one' = 1 unit, 'none' = 0 units. MAY be omitted when the business prefers not to disclose. A future RFC MAY extend the enum via capability version bump."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "When this availability was last updated (RFC 3339). Helps platforms assess freshness and caching decisions."
    }
  }
}

availability_summary.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/types/availability_summary.json",
  "title": "Availability Summary",
  "description": "Summary of location availability for a variant, scoped to the search that produced it.",
  "type": "object",
  "required": ["scope"],
  "additionalProperties": true,
  "properties": {
    "scope": {
      "type": "string",
      "enum": ["all", "nearby", "selected"],
      "description": "'all': all known locations were checked. 'nearby': locations within the search radius were checked. 'selected': only specific requested locations were checked."
    },
    "locations_searched": { "type": "integer" },
    "locations_available": { "type": "integer" },
    "nearest_available": {
      "type": "object",
      "description": "The nearest location with availability (when scope is 'nearby' or 'all' and buyer location is known). MUST be omitted when business_fulfillment_config.discloses_location_availability is false.",
      "properties": {
        "location_id": { "type": "string" },
        "distance": {
          "type": "object",
          "properties": {
            "value": { "type": "number" },
            "unit": { "type": "string", "enum": ["mi", "km"] }
          }
        }
      }
    }
  }
}

Extension to variant.json (Locations & Availability PR) — add
additionalProperties: true, and add optional location_availability array
and availability_summary. Example payload:

{
  "availability": { "available": true, "status": "in_stock" },
  "availability_summary": {
    "scope": "nearby",
    "locations_searched": 25,
    "locations_available": 3
  },
  "location_availability": [
    {
      "location_id": "loc_001",
      "method_availability": [
        { "type": "pickup", "available": true, "status": "in_stock", "fulfillable_on": "now" }
      ],
      "quantity_hint": "many",
      "updated_at": "2026-04-17T12:00:00Z"
    }
  ]
}

4. Extended Fulfillment Method Types

File: source/schemas/shopping/types/fulfillment_method.json (Methods PR)

Extend the type enum with two new buyer-facing primitives:

{
  "type": {
    "type": "string",
    "enum": ["shipping", "pickup", "curbside", "local_delivery"],
    "description": "Fulfillment method type."
  }
}

Design Rationale: Narrowed Method Types

Top-level method types represent stable buyer-facing primitives with
fundamentally different experiences, not operational details.

Criterion for promotion to top-level method type

A variant is promoted to a top-level fulfillment_method.type when all
three of the following hold:

1. Buyer interaction shape differs. The buyer-facing flow (tap targets,
   required inputs, UX affordances) is meaningfully different from existing
   types — not just different branding on the same flow.
2. Required/forbidden field shape differs. The per-method destination
   requirements or required option fields differ in ways that matter for
   validation (see §B3).
3. Post-purchase lifecycle differs. The event sequence produces
   buyer-observable state transitions that don't map cleanly onto another
   type's lifecycle.

Variants that satisfy fewer than all three are modeled as qualifiers on an
existing type (e.g., ship_from_store via origin, ship_to_store via
transfer_origin, in_store_only via unavailability_reason).

Applying this criterion:

Variant	(1) Interaction	(2) Shape	(3) Lifecycle	Top-level?
curbside	Yes (stay in car, "I'm here" button, geofence trigger)	Yes (geofence_radius, arrived event applicable)	Yes (arrived between ready_for_pickup and picked_up)	Yes
local_delivery	Yes (same-day/next-day expectation, cutoff time is primary UI element)	Yes (no carrier tracking, delivery window instead)	Yes (out_for_local_delivery vs. carrier events)	Yes
ship_from_store	No (buyer still sees "shipping")	No (same shape as shipping)	No (same event lifecycle)	No — qualifier via origin
ship_to_store	No (buyer still sees "pickup")	No	No (same base events, extended with arrived_at_store)	No — qualifier via transfer_origin
locker	No (same buyer flow as pickup)	No	No	No — modeled via retail_location.location_type: locker

Deferred / remodeled

Proposed type	Resolution	Rationale
ship_from_store	Qualifier — origin on fulfillment_group	Criterion fails (1), (2), (3)
ship_to_store	Qualifier — transfer_origin on fulfillment_group	Criterion fails (1), (2)
in_store_only	Availability restriction — unavailability_reason: "in_store_only"	Not a checkout method at all
digital	Already handled by existing UCP	N/A

Per-method destination semantics

Method Type	Destination Type	Required Fields
shipping	shipping_destination (postal address)	street_address, address_locality, address_country
pickup	retail_location	id, name
curbside	retail_location	id, name (SHOULD include geo with geofence_radius)
local_delivery	shipping_destination (postal address)	street_address, address_locality, address_country

Extension to fulfillment_available_method.json (Methods PR):

{
  "type": {
    "type": "string",
    "enum": ["shipping", "pickup", "curbside", "local_delivery"]
  },
  "unavailability_reason": {
    "type": "string",
    "enum": [
      "out_of_stock", "ineligible", "restricted", "regulatory_restriction",
      "capacity_full", "outside_service_area", "in_store_only",
      "item_too_large", "cutoff_passed"
    ],
    "description": "Machine-readable reason when this method is unavailable for the given line items. MUST be omitted when the method is available."
  }
}

Extension to business_fulfillment_config.json (Methods PR):

{
  "allows_multi_destination": {
    "type": "object",
    "properties": {
      "shipping": { "type": "boolean" },
      "pickup": { "type": "boolean" },
      "curbside": { "type": "boolean" },
      "local_delivery": { "type": "boolean" }
    }
  },
  "allows_method_combinations": {
    "type": "array",
    "items": {
      "type": "array",
      "items": { "type": "string", "enum": ["shipping", "pickup", "curbside", "local_delivery"] }
    }
  },
  "discloses_location_availability": {
    "type": "boolean",
    "description": "When false, business MUST NOT return location_availability[] on variants or per-variant availability in locations-capability responses. Platforms MUST NOT infer availability from the presence or absence of locations in responses. Business MAY still return location metadata (name, address, hours, fulfillment_capabilities) and aggregate availability_summary without per-location breakdown. Default: false. Businesses opting in to disclosure take on the operational commitment described in §B2 (freshness, updated_at).",
    "default": false
  },
  "supports_curbside_arrival": {
    "type": "boolean",
    "description": "When true, business accepts the 'arrived' event for curbside orders (geofence- or manual-triggered). Platforms SHOULD render arrival UX (e.g., 'I'm here' button) when this is true and the selected method is curbside.",
    "default": false
  }
}

5. Fulfillment Origin and Destination on Expectations, Groups, Events

Add an optional origin field using the fulfillment_origin type
(§2) to three schemas. This section
defines where origin lives and precedence when multiple levels carry
origin data.

fulfillment_group.json additions (Foundation PR for origin, Methods PR for transfer_origin):

{
  "origin": {
    "$ref": "fulfillment_origin.json",
    "description": "The facility fulfilling this group. Enables 'ships from your local store' messaging when a customer_visible_origin is used. Businesses SHOULD set this when the fulfillment source is known at checkout time."
  },
  "transfer_origin": {
    "$ref": "fulfillment_origin.json",
    "description": "For pickup/curbside groups where items are being transferred from another facility to the destination store (the 'ship to store' scenario). When present, indicates items are not currently at the destination and will be transferred — the selected option's fulfillable_on indicates the expected arrival date. MUST NOT be set for shipping or local_delivery groups."
  }
}

transfer_origin is placed on the group (not on individual options) because
transfer is a property of the whole pickup choice, not a per-option detail.
If multiple pickup options on the same group need different transfer paths,
the correct modeling is to split into separate groups.

expectation.json changes (Foundation PR for origin; Methods PR for destination oneOf + method_type extension):

{
  "origin": {
    "$ref": "fulfillment_origin.json",
    "description": "The facility fulfilling this expectation. SHOULD be set post-order when the fulfillment source is confirmed."
  },
  "destination": {
    "oneOf": [
      { "$ref": "postal_address.json" },
      { "$ref": "retail_location.json" }
    ],
    "description": "Delivery destination. For shipping and local_delivery: postal address. For pickup and curbside: retail location."
  },
  "method_type": {
    "type": "string",
    "enum": ["shipping", "pickup", "curbside", "local_delivery", "digital"]
  }
}

5.1 Handling the destination breaking change

expectation.destination changing from $ref postal_address to
oneOf [postal_address, retail_location] is a type-shape change, not an
additive-property change. Strict validators that accepted only postal_address
today will reject retail_location tomorrow. This is not covered by the
additionalProperties: true permissiveness argument (and in any case
expectation.json does not currently declare additionalProperties: true).

Mitigation — two-phase migration:

1. Methods PR (initial landing) — add retail_location to the oneOf,
   add additionalProperties: true to expectation.json, and bump the
   dev.ucp.shopping.order capability version. Commit message uses feat!:
   per the repo's breaking-change convention.
2. Deprecation window — existing consumers that only handle
   postal_address see no change for shipping/local_delivery expectations
   (the response shape for those is still postal_address). Consumers
   encountering curbside/pickup expectations during the transition will need
   to be updated to handle the retail_location arm.

For consumers that cannot update quickly, the business MAY continue to send
postal_address as the destination on curbside/pickup expectations (the
address of the store) as an interim compatibility mode, using the
retail_location.id carried in the top-level origin to preserve
round-tripping. This is not the long-term shape, but is an available
escape valve.

fulfillment_event.json additions (Foundation PR for origin, Methods PR for event types + tracking_number rewrite):

See §7 for the tracking_number
description rewrite. origin addition:

{
  "origin": {
    "$ref": "fulfillment_origin.json",
    "description": "The facility that originated this fulfillment event. Allows event-level origin when items are split across facilities."
  }
}

Precedence: When origin appears at multiple levels, more specific wins:
fulfillment_event.origin > expectation.origin > fulfillment_group.origin.
Platforms SHOULD display the most specific customer-visible origin available;
internal origins MUST NOT be displayed regardless of level.

6. Fulfillment Option Enhancements

File: source/schemas/shopping/types/fulfillment_option.json (Methods PR)

{
  "unavailability_reason": {
    "type": "string",
    "enum": [
      "out_of_stock", "ineligible", "restricted", "regulatory_restriction",
      "capacity_full", "outside_service_area", "in_store_only",
      "item_too_large", "cutoff_passed"
    ],
    "description": "Machine-readable reason when this option is unavailable. MUST be omitted when the option is selectable."
  },
  "minimum_order_quantity": { "type": "integer", "minimum": 1 },
  "pickup_window": {
    "type": "object",
    "description": "When this specific order will be ready for pickup (for pickup and curbside methods). This binds the option to a window; contrast with method_availability.next_pickup_window which is an illustrative availability hint.",
    "required": ["start_time"],
    "properties": {
      "start_time": { "type": "string", "format": "date-time" },
      "end_time": { "type": "string", "format": "date-time" }
    }
  },
  "hold_duration": {
    "type": "string",
    "description": "How long the store will hold the order, as an ISO 8601 duration (e.g., 'P3D' for 3 days)."
  },
  "order_cutoff_time": {
    "type": "string",
    "format": "date-time",
    "description": "Deadline to place an order for this option (RFC 3339)."
  },
  "depends_on_eligibility": {
    "type": "array",
    "description": "Eligibility claims (from context.eligibility) this option depends on. When present, the option is provisional until the claims are verified at checkout per the eligibility verification contract. See §13 for resolution semantics.",
    "items": { "$ref": "reverse_domain_name.json" }
  }
}

pickup_window on option is distinct in semantics from
method_availability.next_pickup_window:

• method_availability.next_pickup_window — illustrative "a window of
  this shape is available"; advisory, informs store/option selection.
• fulfillment_option.pickup_window — "if you pick this option, your
  pickup window is this"; binding once the option is selected.

7. Post-Purchase Lifecycle Events

Extension to fulfillment_event.json (Methods PR)

{
  "type": {
    "type": "string",
    "description": "Event type. UCP-defined well-known values are listed below; business-specific extension values MUST use reverse-domain naming (e.g., 'com.example.drive_up.prep_started'). Platforms MUST ignore unrecognized values or render the description field.",
    "examples": [
      "processing", "shipped", "in_transit", "delivered",
      "ready_for_pickup", "arrived", "picked_up", "arrived_at_store",
      "out_for_local_delivery", "hold_expiring", "hold_expired",
      "failed_attempt", "canceled", "undeliverable", "returned_to_sender"
    ]
  },
  "tracking_number": {
    "type": "string",
    "description": "Carrier tracking number. Required for shipping events when type is one of: shipped, in_transit, delivered, failed_attempt, returned_to_sender, undeliverable. Optional for local_delivery events (third-party delivery providers may issue tracking). MUST be omitted for pickup and curbside events."
  },
  "tracking_url": {
    "type": "string",
    "format": "uri",
    "description": "URL to track this shipment. Same presence rules as tracking_number."
  },
  "carrier": {
    "type": "string",
    "description": "Carrier name (e.g., 'FedEx', 'USPS'). Same presence rules as tracking_number. For local_delivery fulfilled by a third-party provider, the business MAY use this field for the provider name."
  }
}

Well-known event types

Event Type	Applicable Methods	Description
processing	all	Preparing the order
shipped	shipping	Handed to carrier
in_transit	shipping	In delivery network
delivered	shipping, local_delivery	Received by buyer
ready_for_pickup	pickup, curbside	Order is ready at the store
arrived	curbside	Buyer has arrived (geofence or manual trigger)
picked_up	pickup, curbside	Buyer has collected the order
arrived_at_store	pickup, curbside	Item has arrived at destination store (for transfer scenarios)
out_for_local_delivery	local_delivery	Order dispatched for local delivery
hold_expiring	pickup, curbside	Hold period is about to expire
hold_expired	pickup, curbside	Hold period has expired; order may be restocked
failed_attempt	shipping, local_delivery	Delivery attempt failed
canceled	all	Fulfillment canceled
undeliverable	shipping	Cannot be delivered
returned_to_sender	shipping	Returned to merchant

8. Buyer Location Context & Platform-Derived Geo Signal

Files (Foundation PR):

• source/schemas/shopping/types/context.json
• source/schemas/shopping/types/signals.json (new signal registration)

Geo data splits along the same axis as the rest of UCP's provenance model:

• context.geo — buyer-granted precise location (explicit consent,
  coarse by default, MUST-level privacy rules).
• signals["dev.ucp.shopping.geo"] — platform-derived coarse geo from
  IP, subject to the existing signal retention rules.

Splitting along this axis matters because the two have fundamentally
different provenance and retention classes: platforms routinely derive
coarse geo from IP and send it on every request, whereas a user who has
explicitly tapped "use my location" has a stronger consent relationship
with the platform and may grant finer precision.

8.1 context.geo — buyer-granted

{
  "geo": {
    "type": "object",
    "description": "Buyer-granted geographic location for proximity-based store finding and local availability. This field is a buyer-consent-gated hint. Businesses MUST NOT persist context.geo values beyond request processing. If retention is needed for reconciliation, businesses MUST truncate latitude and longitude to at most 2 decimal places (~1.1 km resolution). Businesses MUST NOT use context.geo for authorization, fraud prevention, or pricing decisions. Platforms SHOULD truncate lat/lng to at most 2 decimal places unless the buyer has explicitly granted precise location to the platform/business relationship.",
    "properties": {
      "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
      "longitude": { "type": "number", "minimum": -180, "maximum": 180 },
      "accuracy": {
        "type": "number",
        "minimum": 100,
        "description": "Accuracy radius in meters. Minimum 100 (street-block level). An accuracy of 100 is the default for non-consented location; smaller values (precise) require explicit buyer consent."
      }
    }
  },
  "preferred_location_id": {
    "type": "string",
    "description": "Buyer's preferred retail location ID (e.g., 'my store'). Businesses SHOULD prioritize this location in availability and fulfillment responses."
  }
}

8.2 signals["dev.ucp.shopping.geo"] — platform-derived

A new signal definition for platform-derived coarse geolocation (typically
from IP geolocation):

{
  "dev.ucp.shopping.geo": {
    "description": "Platform-derived coarse geographic location (typically from IP geolocation). Subject to signal retention rules: businesses SHOULD NOT persist signal data beyond the operational needs of the transaction. Not suitable for authorization or precise location decisions.",
    "shape": {
      "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
      "longitude": { "type": "number", "minimum": -180, "maximum": 180 },
      "accuracy": { "type": "number", "minimum": 1000, "description": "Accuracy radius in meters. Minimum 1000 (city-level) for platform-derived geo." }
    }
  }
}

When both are present, context.geo supersedes
signals["dev.ucp.shopping.geo"] for proximity computation, because
consent-granted data has stronger provenance. When only the signal is
present, the business MAY use it for coarse store preselection but MUST NOT
use it to gate access to products or prices.

9. Location-Aware Catalog Search and Lookup

Files: source/schemas/shopping/catalog_search.json,
source/schemas/shopping/catalog_lookup.json (Locations & Availability PR)

Add additionalProperties: true to each schema root (currently missing), and
add location_filter to the search request:

{
  "location_filter": {
    "type": "object",
    "description": "Filter and rank results by store-level availability.",
    "properties": {
      "location_ids": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Only return products available at these specific location IDs."
      },
      "radius": {
        "type": "object",
        "description": "Return products available within a radius of a point.",
        "required": ["latitude", "longitude", "distance", "unit"],
        "properties": {
          "latitude": { "type": "number" },
          "longitude": { "type": "number" },
          "distance": { "type": "number" },
          "unit": { "type": "string", "enum": ["mi", "km"] }
        }
      },
      "fulfillment_methods": {
        "type": "array",
        "items": { "type": "string", "enum": ["pickup", "curbside", "local_delivery", "shipping"] },
        "description": "Only return products available via these fulfillment methods."
      },
      "include_location_availability": {
        "type": "boolean",
        "description": "If true, response variants SHOULD include location_availability for matched locations. Default false to minimize payload size. Businesses with discloses_location_availability: false MUST return availability_summary only and omit location_availability[] even when this is requested true.",
        "default": false
      }
    }
  }
}

catalog_lookup adds location_filter to both lookup_request and
get_product_request. Same schema as catalog_search.

This is the canonical home for per-variant per-location availability
queries. The locations capability (§10)
returns location-level data and filtering (hours, distance, capabilities)
but does not duplicate per-variant availability — see the rationale in §10.

Input Precedence Rules

When multiple location-related inputs are provided, businesses MUST apply them
in the following precedence order:

1. location_filter.location_ids — most specific; only these locations
   are checked. When present, radius and context.geo are ignored for
   filtering (but MAY be used for sorting by distance).
2. location_filter.radius — defines an explicit search area. Overrides
   context.geo and signals["dev.ucp.shopping.geo"] for filtering.
3. context.preferred_location_id — does not filter, but businesses
   SHOULD return the preferred location first in results and SHOULD include
   it even if it falls outside the search radius.
4. context.geo — used only when no location_filter is provided.
5. signals["dev.ucp.shopping.geo"] — coarsest hint, used only when no
   location_filter and no context.geo is provided.

10. Locations Capability (New)

New capability: dev.ucp.shopping.locations
New file: source/schemas/shopping/locations.json (Locations & Availability PR)

A standalone capability for discovering retail locations. The name parallels
the catalog.search/catalog.lookup naming convention (object-led rather
than function-led) and leaves room for future sub-operations
(e.g., locations.reserve).

Scope narrowing: this capability returns only location data —
metadata, hours, fulfillment capabilities, distance. Per-variant availability
at specific stores is a catalog operation, handled by catalog.lookup with
location_filter (§9). There is no need for two places to get per-variant
per-location availability.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/locations.json",
  "title": "Locations",
  "description": "Capability for discovering retail locations and finding stores near a point or within filters. Per-variant per-location availability is a catalog operation — use catalog.lookup or catalog.search with location_filter.",
  "type": "object",
  "$defs": {
    "locations_request": {
      "type": "object",
      "description": "Request to find retail locations.",
      "additionalProperties": true,
      "properties": {
        "geo": {
          "type": "object",
          "description": "Center point for proximity search.",
          "required": ["latitude", "longitude"],
          "properties": {
            "latitude": { "type": "number" },
            "longitude": { "type": "number" }
          }
        },
        "radius": {
          "type": "object",
          "description": "Search radius.",
          "properties": {
            "distance": { "type": "number", "default": 25 },
            "unit": { "type": "string", "enum": ["mi", "km"], "default": "mi" }
          }
        },
        "postal_code": {
          "type": "string",
          "description": "Alternative to geo — search by postal/ZIP code."
        },
        "fulfillment_methods": {
          "type": "array",
          "items": { "type": "string", "enum": ["pickup", "curbside", "local_delivery", "shipping"] },
          "description": "Filter locations by the fulfillment methods they support."
        },
        "location_types": {
          "type": "array",
          "items": { "type": "string", "enum": ["store", "locker", "pop_up"] }
        },
        "capabilities": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Filter by capability codes (e.g., ['FRESH_GROCERY', 'PHARMACY'])."
        },
        "pagination": { "$ref": "types/pagination.json#/$defs/request" }
      }
    },
    "locations_response": {
      "type": "object",
      "required": ["ucp", "locations"],
      "additionalProperties": true,
      "properties": {
        "ucp": { "$ref": "../ucp.json#/$defs/response_catalog_schema" },
        "locations": {
          "type": "array",
          "description": "Matching locations, ordered by distance (nearest first). When preferred_location_id is in context, that location MUST appear first regardless of distance.",
          "items": {
            "type": "object",
            "required": ["location"],
            "properties": {
              "location": { "$ref": "types/retail_location.json" },
              "preferred": { "type": "boolean", "description": "True when this is the buyer's preferred location from context." }
            }
          }
        },
        "pagination": { "$ref": "types/pagination.json#/$defs/response" }
      }
    }
  }
}

Capability version is managed via the business profile (per
/.well-known/ucp), not inline in the schema — matching the convention of
checkout.json, cart.json, catalog_search.json, etc.

Default behavior:

• Businesses SHOULD return at most 25 locations per page by default.
• Results MUST be ordered by distance (nearest first).
• When context.preferred_location_id is provided, the preferred location
  MUST appear first in results with "preferred": true, even if it falls
  outside the search radius.

Example request:

{
  "geo": { "latitude": 39.7817, "longitude": -89.6501 },
  "radius": { "distance": 15, "unit": "mi" },
  "fulfillment_methods": ["pickup", "curbside"]
}

For per-variant availability at those stores, the platform follows up with
catalog.lookup using location_filter.location_ids populated from the
locations response.

11. Quantity-Aware Split Fulfillment

File: source/schemas/shopping/types/fulfillment_method.json (Methods PR)

For retailers with per-store inventory, split-quantity fulfillment is the
common case, not the edge case: a buyer orders 5 units, 2 are available for
pickup locally, 3 will ship from a DC. Current UCP cannot express this
because fulfillment_method.line_item_ids: string[] is line-item-based.

Additive change to line_item_ids: accept both legacy string and
new { id, quantity }:

{
  "line_item_ids": {
    "type": "array",
    "description": "Line item IDs fulfilled via this method. Entries MAY be bare line-item IDs (legacy shape: full quantity of the line item is fulfilled via this method) or {id, quantity} objects (new: partial quantity is fulfilled via this method). When the same line item ID appears in multiple methods with {id, quantity} entries, the quantities MUST sum to the total quantity on the line item.",
    "items": {
      "oneOf": [
        { "type": "string", "description": "Legacy bare ID — full quantity of the line item is fulfilled via this method." },
        {
          "type": "object",
          "required": ["id", "quantity"],
          "additionalProperties": false,
          "properties": {
            "id": { "type": "string" },
            "quantity": { "type": "integer", "minimum": 1 }
          }
        }
      ]
    }
  }
}

Business semantics:

• Businesses that do not support split-quantity fulfillment continue using
  the bare-string form; nothing changes.
• Businesses that support split-quantity list the same line item ID in
  multiple methods, each with a partial quantity that sums to the total.
• Mixing bare strings and {id, quantity} objects for the same line item
  ID in different methods is a protocol error — a business MUST pick one
  representation per line item.
• fulfillment_method.line_item_ids interpretation flows to
  fulfillment_group.line_item_ids (which is also string[] today and
  becomes bi-format under the same rule).

Example — 2 pickup + 3 shipped:

{
  "fulfillment": {
    "methods": [
      {
        "id": "method_pickup",
        "type": "pickup",
        "line_item_ids": [{ "id": "shirt_blue_lg", "quantity": 2 }],
        "selected_destination_id": "loc_001"
      },
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [{ "id": "shirt_blue_lg", "quantity": 3 }],
        "selected_destination_id": "home_addr"
      }
    ]
  }
}

Scope boundary: Split-quantity applies at the fulfillment-method level,
not at the item level within a single event. A single fulfillment_event
still references whole quantity units atomically.

12. Spec Governance Update

File: docs/specification/fulfillment.md (Methods PR)

The current "Adding New Methods" section says new method types MUST be
extensions (retailer-specific, via extension schema, reverse-domain-named).
That rule does not accommodate curbside and local_delivery, which this
RFC adds as protocol-blessed additions to the base enum.

Proposed update to fulfillment.md "Adding New Methods":

UCP distinguishes two paths for new method types:

1. Protocol-blessed methods — universal, buyer-facing primitives that
   satisfy all three promotion criteria
   (§4 of this RFC). These are added
   to the base fulfillment_method.type enum via the RFC process and
   coordinated with a dev.ucp.shopping.fulfillment capability version
   bump.
2. Vendor-defined methods — retailer- or category-specific variants
   that don't warrant protocol-wide blessing. These MUST be added via
   extension schemas with reverse-domain-named values (e.g.,
   com.example.drone_delivery).

When in doubt, propose as vendor-defined first. Promotion to protocol-blessed
status follows adoption evidence across multiple retailers and platforms.

13. Fulfillment Option Eligibility (Membership-Gated Fulfillment)

File (Methods PR): source/schemas/shopping/types/fulfillment_option.json

Many retailers offer member-only fulfillment options — free same-day delivery
for premium subscribers, free grocery delivery for loyalty tiers, $0 fees for
paid-membership ecosystems. This section defines a concrete binding between
a fulfillment option and the eligibility claims it depends on.

Mechanism

1. Business declares eligibility dependency on an option via the new
   depends_on_eligibility array on fulfillment_option
   (§6):

   {
     "id": "sameday_free",
     "title": "Free Same-Day Delivery",
     "description": "Free same-day delivery for members",
     "depends_on_eligibility": ["com.example.premium_membership"],
     "totals": [{ "type": "total", "amount": 0 }]
   }

2. Platform surfaces the option when the buyer's context.eligibility
   includes the required claim, understanding the option is provisional
   until verified at checkout.

3. Verification at checkout uses the existing eligibility verification
   contract (the per-mechanism auth flow established by the Identity Linking
   RFC). If verification succeeds, the option remains as offered. If it
   fails, the business MUST either:

   • (a) Remove the option from groups[].options[], clear any
     selected_option_id that referenced it, and emit a message of type
     warning per §B4.
   • (b) Update the option to reflect non-member pricing (for
     variable-cost benefits), clearing depends_on_eligibility in the
     process.

4. Authoritative identity supersedes claims. When the identity-linking
   mechanism produces authoritative member status (from the OAuth/credential
   flow), the business MUST use authoritative status for verification —
   claim-based eligibility is provisional and subordinate.

Interaction with §B4 (cart-update invalidation)

When eligibility verification fails, the invalidation rules in §B4 apply:
business clears selected_option_id, updates available_methods, returns a
warning message, and the platform re-renders.

14. [Deferred to future RFC] Pharmacy / Age-Verified Fulfillment

Some fulfillment options (alcohol, pharmacy, firearms) require identity
verification at handoff. This RFC flags such items via
unavailability_reason: "restricted" or "regulatory_restriction" but does
not model the verification workflow. A follow-up RFC will extend the pickup
and local_delivery event lifecycle with verification events (e.g.,
id_checked, rx_confirmed) and hook into the identity-linking mechanism
registry.

[maximenajim]

Behavioral Specification

This section defines required platform and business behaviors for scenarios
that would otherwise be underspecified.

B1. Location filter input precedence

See §9 Input Precedence Rules. Summary:
location_filter.location_ids > location_filter.radius >
context.preferred_location_id (sort bias, not filter) > context.geo >
signals["dev.ucp.shopping.geo"].

B2. Location availability: advisory vs. authoritative

location_availability on catalog responses is advisory. It reflects
the business's best-known inventory state at updated_at time. It is NOT
authoritative for checkout — checkout-time available_methods on the
fulfillment extension is the binding contract.

Platforms SHOULD:

• Display location_availability for browsing and store selection
• Re-validate availability at checkout time via the fulfillment extension
• Display updated_at age when it exceeds 15 minutes (business-configurable)
• Treat location_availability as stale if updated_at is more than 1 hour
  old and display appropriate warnings

Businesses SHOULD (when discloses_location_availability: true):

• Update location_availability at least every 15 minutes for high-traffic
  locations
• Return updated_at on every location_availability entry

B3. Required, optional, and forbidden fields per fulfillment type

Field	shipping	pickup	curbside	local_delivery
destinations[] (type)	shipping_destination (required)	retail_location (required)	retail_location (required)	shipping_destination (required)
groups[].origin	optional	forbidden	forbidden	optional
groups[].transfer_origin	forbidden	optional	optional	forbidden
groups[].options[].carrier	optional	forbidden	forbidden	optional (for 3P providers)
groups[].options[].tracking_number (events)	optional	forbidden	forbidden	optional
groups[].options[].tracking_url (events)	optional	forbidden	forbidden	optional
groups[].options[].pickup_window	forbidden	optional	optional	forbidden
groups[].options[].hold_duration	forbidden	optional	optional	forbidden
groups[].options[].order_cutoff_time	optional	optional	optional	optional
groups[].options[].depends_on_eligibility	optional	optional	optional	optional

"forbidden" means the field MUST NOT be present — its presence is a protocol
error. "optional" means the business MAY include it. "required" means the
business MUST include it.

B4. Invalidation after cart update, address resolution, or eligibility failure

When a previously selected store, fulfillment option, or membership-gated
eligibility becomes invalid:

• Business MUST clear selected_option_id on affected groups and set it to
  null.
• Business MUST update available_methods to reflect current state.
• Business SHOULD return a message with type: "warning" explaining what
  changed.
• Platform SHOULD re-render fulfillment options and prompt the buyer to
  reselect.

Triggering events:

• Cart item added / removed / quantity changed
• Address resolution (shipping address entered or changed)
• Eligibility verification failure at checkout (§13)
• Location hours change making a previously-selected store unavailable in the
  current window

B5. Default location count and ordering

• Locations capability: at most 25 locations per page, nearest first
  (§10)
• location_availability on catalog/lookup responses: businesses SHOULD
  return availability for at most 10 locations nearest to the buyer by
  default. Businesses MAY return fewer.
• When context.preferred_location_id is set, the preferred location MUST
  appear first in any location list, even if not the nearest.

B6. Conflict between location_id and inline location

When both location_id and inline location are present on a
location_availability entry and they refer to different locations:

• location_id is authoritative for identity.
• The inline location object is supplementary display data.
• If location.id differs from location_id, platforms MUST use location_id
  and SHOULD log a warning.
• Businesses MUST NOT return entries where location.id and location_id
  disagree — this is a protocol error.

B7. Ordering of post-purchase events

Platforms MUST NOT assume strict monotonic ordering of occurred_at across
events (events may arrive out of order from distributed systems). Platforms
SHOULD order events by occurred_at for display. The lifecycle state machine
is idempotent — repeated ready_for_pickup events for the same group SHOULD
be treated as duplicates, not state regressions.

---

Fulfillment Flow Examples

Example 1: Mixed Cart — Curbside Pickup + Same-Day Delivery

A buyer has a shirt and a TV. Shirt is curbside at the local store; TV is
same-day delivery from the same store.

{
  "fulfillment": {
    "methods": [
      {
        "id": "method_curbside",
        "type": "curbside",
        "line_item_ids": ["shirt"],
        "selected_destination_id": "loc_001",
        "destinations": [
          {
            "id": "loc_001",
            "name": "Acme Retail Downtown",
            "address": { "street_address": "123 Main St", "address_locality": "Springfield", "address_region": "IL", "postal_code": "62701", "address_country": "US" },
            "geo": { "latitude": 39.7990, "longitude": -89.6440, "geofence_radius": 150 }
          }
        ],
        "groups": [
          {
            "id": "group_curbside_1",
            "line_item_ids": ["shirt"],
            "selected_option_id": "curbside_2hr",
            "options": [
              {
                "id": "curbside_2hr",
                "title": "Curbside Pickup",
                "description": "Ready in 2 hours — we'll bring it to your car",
                "pickup_window": {
                  "start_time": "2026-04-17T14:00:00-05:00",
                  "end_time": "2026-04-17T22:00:00-05:00"
                },
                "hold_duration": "P3D",
                "totals": [{ "type": "total", "amount": 0 }]
              }
            ]
          }
        ]
      },
      {
        "id": "method_local_delivery",
        "type": "local_delivery",
        "line_item_ids": ["tv"],
        "selected_destination_id": "home_addr",
        "destinations": [
          {
            "id": "home_addr",
            "street_address": "456 Oak Ave", "address_locality": "Springfield", "address_region": "IL", "postal_code": "62704", "address_country": "US"
          }
        ],
        "groups": [
          {
            "id": "group_delivery_1",
            "line_item_ids": ["tv"],
            "origin": {
              "visibility": "customer_visible",
              "id": "loc_001",
              "name": "Acme Retail Downtown",
              "origin_type": "store",
              "distance": { "value": 0.8, "unit": "mi" }
            },
            "selected_option_id": "sameday",
            "options": [
              {
                "id": "sameday",
                "title": "Same-Day Delivery",
                "description": "Delivered today by 9pm from Acme Downtown",
                "order_cutoff_time": "2026-04-17T14:00:00-05:00",
                "totals": [{ "type": "total", "amount": 999 }]
              }
            ]
          }
        ]
      }
    ]
  }
}

Example 2: Ship from Store (origin on group)

{
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["pants"],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["pants"],
            "origin": {
              "visibility": "customer_visible",
              "id": "loc_001",
              "name": "Acme Retail Downtown",
              "origin_type": "store",
              "distance": { "value": 8.3, "unit": "mi" }
            },
            "selected_option_id": "sfs_express",
            "options": [
              {
                "id": "sfs_express",
                "title": "Express — Ships from Local Store",
                "description": "Ships from Acme Downtown — arrives tomorrow",
                "carrier": "UPS",
                "totals": [{ "type": "total", "amount": 899 }]
              }
            ]
          }
        ]
      }
    ]
  }
}

Example 3: Ship to Store (transfer_origin on group)

{
  "fulfillment": {
    "methods": [
      {
        "id": "method_pickup",
        "type": "pickup",
        "line_item_ids": ["jacket"],
        "selected_destination_id": "loc_001",
        "destinations": [
          { "id": "loc_001", "name": "Acme Retail Downtown" }
        ],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["jacket"],
            "transfer_origin": {
              "visibility": "internal",
              "id": "wh_east",
              "origin_type": "distribution_center"
            },
            "selected_option_id": "transfer_pickup",
            "options": [
              {
                "id": "transfer_pickup",
                "title": "Transfer to Store for Pickup",
                "description": "Transfers from warehouse — ready for pickup Apr 22-24",
                "earliest_fulfillment_time": "2026-04-22T00:00:00-05:00",
                "latest_fulfillment_time": "2026-04-24T23:59:00-05:00",
                "hold_duration": "P7D",
                "totals": [{ "type": "total", "amount": 0 }]
              }
            ]
          }
        ]
      }
    ]
  }
}

transfer_origin uses internal_origin (no name, no address) because
platforms MUST NOT display the source DC. Contrast with Example 2's origin,
which uses customer_visible_origin.

Example 4: Split-Quantity Fulfillment

A buyer orders 5 units. 2 are picked up locally, 3 ship from DC.

{
  "fulfillment": {
    "methods": [
      {
        "id": "method_pickup",
        "type": "pickup",
        "line_item_ids": [{ "id": "shirt_blue_lg", "quantity": 2 }],
        "selected_destination_id": "loc_001",
        "groups": [
          {
            "id": "group_pickup_1",
            "line_item_ids": [{ "id": "shirt_blue_lg", "quantity": 2 }],
            "selected_option_id": "pickup_today",
            "options": [
              {
                "id": "pickup_today",
                "title": "Pickup Today",
                "pickup_window": { "start_time": "2026-04-17T14:00:00-05:00", "end_time": "2026-04-17T22:00:00-05:00" },
                "totals": [{ "type": "total", "amount": 0 }]
              }
            ]
          }
        ]
      },
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [{ "id": "shirt_blue_lg", "quantity": 3 }],
        "selected_destination_id": "home_addr",
        "groups": [
          {
            "id": "group_ship_1",
            "line_item_ids": [{ "id": "shirt_blue_lg", "quantity": 3 }],
            "selected_option_id": "std_ship",
            "options": [
              {
                "id": "std_ship",
                "title": "Standard Shipping",
                "carrier": "UPS",
                "totals": [{ "type": "total", "amount": 599 }]
              }
            ]
          }
        ]
      }
    ]
  }
}

Example 5: Membership-Gated Local Delivery

Buyer has a premium membership claim. Free same-day delivery is offered,
provisional on eligibility verification:

{
  "fulfillment": {
    "methods": [
      {
        "id": "method_local_delivery",
        "type": "local_delivery",
        "line_item_ids": ["tv"],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["tv"],
            "selected_option_id": "sameday_member",
            "options": [
              {
                "id": "sameday_member",
                "title": "Free Same-Day Delivery",
                "description": "Free with premium membership",
                "depends_on_eligibility": ["com.example.premium_membership"],
                "order_cutoff_time": "2026-04-17T14:00:00-05:00",
                "totals": [{ "type": "total", "amount": 0 }]
              },
              {
                "id": "sameday_paid",
                "title": "Same-Day Delivery",
                "description": "$9.99 delivery",
                "order_cutoff_time": "2026-04-17T14:00:00-05:00",
                "totals": [{ "type": "total", "amount": 999 }]
              }
            ]
          }
        ]
      }
    ]
  }
}

If membership verification fails at checkout, the business removes
sameday_member from options, clears selected_option_id, and returns a
warning message prompting re-selection.

Example 6: Post-Purchase Curbside Lifecycle

{
  "expectations": [
    {
      "id": "exp_1",
      "line_items": [{ "id": "shirt", "quantity": 1 }],
      "method_type": "curbside",
      "destination": { "id": "loc_001", "name": "Acme Retail Downtown" },
      "origin": {
        "visibility": "customer_visible",
        "id": "loc_001",
        "name": "Acme Retail Downtown",
        "origin_type": "store"
      },
      "description": "Ready for curbside pickup today by 2pm"
    }
  ],
  "fulfillment_events": [
    { "id": "evt_1", "occurred_at": "2026-04-17T12:30:00-05:00", "type": "processing", "line_items": [{ "id": "shirt", "quantity": 1 }] },
    { "id": "evt_2", "occurred_at": "2026-04-17T13:45:00-05:00", "type": "ready_for_pickup", "line_items": [{ "id": "shirt", "quantity": 1 }], "description": "Ready for curbside pickup at Acme Downtown" },
    { "id": "evt_3", "occurred_at": "2026-04-17T15:10:00-05:00", "type": "arrived", "line_items": [{ "id": "shirt", "quantity": 1 }], "description": "We see you've arrived — bringing your order out now" },
    { "id": "evt_4", "occurred_at": "2026-04-17T15:15:00-05:00", "type": "picked_up", "line_items": [{ "id": "shirt", "quantity": 1 }] }
  ]
}

No tracking_number on any of these events — per the tracking_number
description, tracking is forbidden for pickup/curbside events.

Example 7: Retailer that does NOT disclose per-location inventory

Catalog response for a retailer with discloses_location_availability: false:

{
  "variant": {
    "id": "shirt_blue_lg",
    "availability": { "available": true, "status": "in_stock" },
    "availability_summary": {
      "scope": "all",
      "locations_available": 47
    }
  }
}

No location_availability[] array, no nearest_available. The platform gets
"available at 47 locations in the region" without per-store disclosure. At
checkout, available_methods still binds authoritatively.

[maximenajim]

Appendix A: Schema Change Summary

Column legend:

• Phase: F = Foundation PR, M = Methods PR, L = Locations & Availability PR
• Breaking?: Y = breaking (needs version bump + feat!:), N = additive, A = additive but adds additionalProperties: true

File	Change Type	Breaking?	Phase	Description
types/retail_location.json	Modify	N	F	Add geo/geofence_radius, distance, location_type (enum), format, status (enum), phone, hours (interval-based), exception_hours, timezone, fulfillment_capabilities (enum), capabilities, metadata
types/customer_visible_origin.json	New	N	F	Origin renderable to buyer; name MUST
types/internal_origin.json	New	N	F	Origin MUST NOT be rendered; additionalProperties: false; no name/address/distance
types/fulfillment_origin.json	New	N	F	oneOf wrapper for customer_visible_origin and internal_origin
types/context.json	Extend	N	F	Add geo (min accuracy 100m) and preferred_location_id; MUST-level privacy rules
types/signals.json (or signal registration)	New signal	N	F	Register dev.ucp.shopping.geo with min accuracy 1000m
types/fulfillment_group.json	Extend	N	F	Add optional origin
types/expectation.json	Modify	A + Y	F(origin) / M(destination oneOf)	Add additionalProperties: true; add origin; change destination to oneOf [postal_address, retail_location]; extend method_type enum. Breaking: destination oneOf — bump dev.ucp.shopping.order
types/fulfillment_event.json	Modify	A	F(origin) / M(events + tracking)	Add additionalProperties: true; add origin; rewrite tracking_number/tracking_url/carrier descriptions; document well-known event types; reverse-domain extension convention
types/fulfillment_method.json	Modify	N	M	Extend type enum to 4 values; line_item_ids accepts bare string OR {id, quantity}
types/fulfillment_available_method.json	Modify	N	M	Extend type enum; add unavailability_reason (enum)
types/business_fulfillment_config.json	Modify	N	M	Four-way method matrices; add discloses_location_availability, supports_curbside_arrival
types/merchant_fulfillment_config.json	Delete	N	M	Byte-identical duplicate of business_fulfillment_config.json; update fulfillment.md references
docs/specification/fulfillment.md	Modify	N	M	"Adding New Methods" governance update (protocol-blessed vs vendor-defined)
types/fulfillment_group.json	Extend (2nd change)	N	M	Add transfer_origin
types/fulfillment_option.json	Extend	N	M	Add unavailability_reason (enum), minimum_order_quantity, pickup_window, hold_duration, order_cutoff_time, depends_on_eligibility
types/location_availability.json	New	N	L	Per-location availability with method_availability[], quantity_hint (enum), updated_at
types/method_availability.json	New	N	L	Per-method availability; unavailability_reason enum; next_pickup_window
types/availability_summary.json	New	N	L	Scoped summary with scope enum, counts, nearest_available
types/variant.json	Extend	A	L	Add additionalProperties: true; add optional location_availability[] and availability_summary
catalog_search.json	Extend	A	L	Add additionalProperties: true; add location_filter
catalog_lookup.json	Extend	A	L	Add additionalProperties: true; add location_filter to lookup_request and get_product_request
locations.json	New	N	L	New dev.ucp.shopping.locations capability

Capability version bumps required:

• dev.ucp.shopping.fulfillment (Methods PR — enum additions, option additions, config additions, event types, tracking description)
• dev.ucp.shopping.order (Methods PR — expectation.destination oneOf is breaking)
• dev.ucp.shopping.catalog.search (Locations & Availability PR — location_filter addition)
• dev.ucp.shopping.catalog.lookup (Locations & Availability PR — location_filter addition)
• dev.ucp.shopping.locations (Locations & Availability PR — new)

---

Appendix B: Open Questions

The following items remain open for TC discussion. None block the design
direction.

1. Selectable delivery slot model — Should local_delivery support a
   selectable_slots[] on the option for retailers offering 2-hour pickup
   windows (e.g., "between 2-4pm")? Current earliest_fulfillment_time /
   latest_fulfillment_time can express a single window per option but
   doesn't express "pick one of these three 2-hour slots." Leaning toward a
   future RFC when retailer demand is demonstrated.

2. Event correlation fields — Should arrived events REQUIRE a geo
   coordinate for geofence confirmation? Should picked_up events carry a
   customer identity reference? Left as SHOULD pending operational feedback.

3. Regulated-item verification workflow — Alcohol, pharmacy, firearms.
   Flagged via unavailability_reason: "restricted" /
   "regulatory_restriction" but the identity-verification handoff (age
   gate, Rx confirmation) is out of scope. Expected in a follow-up RFC
   coordinated with the identity-linking mechanism registry.

4. Signal registration conventions — This RFC registers
   dev.ucp.shopping.geo as a new signal. If signals becomes a growing
   registry, a meta-spec for signal registration (shape, retention class,
   consent requirements) might be warranted — but that's a cross-cutting
   item for a separate RFC.

5. Split-quantity across methods with different eligibility gates — If
   one quantity has member pricing and another doesn't, does
   depends_on_eligibility need to live on the method or the quantity?
   Current design places it on the option, and businesses split into separate
   methods if the gating differs. Edge cases may emerge.

[drewolson-google]

Thanks @maximenajim, very comprehensive. There's a lot to digest here, but here are my initial thoughts and questions after my first pass:

1. Capability Nesting: Should the new locations capability be nested under shopping (dev.ucp.shopping.locations) or be standalone at the top level? I can see it being used across shopping and other future capabilities.
2. Enum Flexibility: Given that location_type and status are closed enums, should we model this more flexibly in the future, such that additions do not require a new capability version?
3. Exposure of Origins/Destinations: Why do fulfillment origins and destinations need to be exposed in the protocol at all? Should these be internal details for determining the appropriate fulfillment mechanisms given a user's location and the product they want to buy?
4. Event Namespacing: Should post-purchase lifecycle events be named using dot-notation (e.g., category.event) to convey namespacing? This proposal adds a lot of top-level lifecycle events.

Note: None of the links styled as §4 actually link to anything.

Overall, though, this proposal seems to be moving in the right direction.

[maximenajim]

Thanks @drewolson-google, for the thorough first pass — these are exactly the right questions to be asking. Here are my thoughts, but I'd love to hear where others land on these too.

---

Capability Nesting: Should the new locations capability be nested under shopping (dev.ucp.shopping.locations) or be standalone at the top level? I can see it being used across shopping and other future capabilities.

Great question, and I went back and forth on this one. The reason it landed under shopping is that the current schema is pretty tightly coupled to shopping constructs — fulfillment_capabilities references shopping method types, the response wraps retail_location.json from the shopping types directory, and the primary consumers today are catalog and checkout flows.
But I think you're right to flag the cross-vertical potential. A few things that might ease the concern:

• UCP already supports multi-parent extensions, so a future vertical could extend or share the locations capability without a full redesign.
• If we did need to promote it to dev.ucp.common.locations later, that's a namespace change + deprecation cycle — the schema shape itself wouldn't need to change much.
  Does it feel reasonable to start under shopping and extract to common when a second vertical actually needs it? Or do folks think the cost of moving later is high enough that we should go top-level now? I could see it either way — curious what others think.

---

Enum Flexibility: Given that location_type and status are closed enums, should we model this more flexibly in the future, such that additions do not require a new capability version?

This is a fair concern. The RFC currently models both as closed enums, meaning any new value (say, kiosk or seasonal) requires a capability version bump. The thinking was that these values have direct implications for platform rendering and validation — a platform needs to know what a locker is vs. a store to render the right UX — so keeping them closed felt like it provided stronger contracts.
That said, would it be worth exploring a hybrid approach? Something like:

• Keep a set of well-known values that platforms MUST understand (store, locker, open, closed, etc.)
• Allow extension values via reverse-domain naming (e.g., com.example.kiosk) that platforms can gracefully degrade on — similar to how format is already modeled as an open string with well-known values
  The format field in this RFC actually uses that pattern already. The tradeoff is weaker validation guarantees — platforms would need to handle unknown values gracefully. Do we think the tighter contract is worth the version-bump friction?

---

Exposure of Origins/Destinations: Why do fulfillment origins and destinations need to be exposed in the protocol at all? Should these be internal details for determining the appropriate fulfillment mechanisms given a user's location and the product they want to buy?

Really appreciate this pushback. The motivating use cases are things like:

• "Ships from your local store — arrives tomorrow" — the buyer experience is meaningfully different when they know the origin is 2 miles away vs. a DC in another state
• "Your order is being transferred to Store X for pickup" — the buyer needs to know which store to go to, and that it's coming from somewhere else (hence the longer wait)
  For origins that shouldn't be exposed (DCs, dark stores, warehouses), the RFC uses internal_origin with additionalProperties: false — so the fields literally don't exist on the type. The idea is that even a misbehaving platform can't leak what isn't there.
  But I want to make sure this doesn't feel like over-exposure. Would it help to:
• Make origin on fulfillment_group default to omitted (it's already optional) and add stronger guidance that businesses SHOULD only populate it when the buyer experience benefits?
• Add a discloses_origin toggle to business_fulfillment_config (similar to discloses_location_availability) so businesses can opt out entirely?
  Or does the concern go deeper — like, should origins never appear in the protocol at all, even for ship-from-store scenarios? If so, how would we handle the "ships from your local store" messaging that retailers surface today?

---

Event Namespacing: Should post-purchase lifecycle events be named using dot-notation (e.g., category.event) to convey namespacing? This proposal adds a lot of top-level lifecycle events.

This is a good observation — the RFC does add a lot of top-level event types (ready_for_pickup, arrived, picked_up, out_for_local_delivery, hold_expiring, hold_expired, arrived_at_store, etc.). Dot-notation namespacing like pickup.ready, pickup.arrived, curbside.arrived, delivery.dispatched would definitely convey structure better.
A couple of things I'd want to think through together:

• Backward compatibility — the existing events (processing, shipped, in_transit, delivered) are flat strings today. Moving to dot-notation would either mean a mixed convention (old flat + new dotted) or migrating the existing ones too (e.g., shipping.shipped, shipping.in_transit). The mixed approach feels messy — would we want to bite the bullet and migrate everything?
• Parsing expectations — dot-notation implies hierarchy, which is great for humans reading the spec, but do we want platforms to actually parse the dots (e.g., "anything starting with pickup.* is a pickup event")? Or is it purely cosmetic namespacing? If it's semantic, we'd want to spec the parsing rules.
• Extension events — the RFC already proposes reverse-domain naming for business-specific events (e.g., com.example.drive_up.prep_started). Dot-notation for well-known events would align nicely with that pattern.
  I'm leaning toward this being a good idea, but I'd want to make sure we're aligned on whether it's a cosmetic convention or a semantic one.

[maximenajim]

Adding appendix on adjacent requirements for additional discussions....

Appendix C: Grocery & Local Fulfillment Adjacent Requirements

The following requirements have been identified as critical adjacent concerns
for grocery and store-level local fulfillment. They are not in scope for
this RFC but are documented here to acknowledge them as known gaps and to
inform follow-up work. Feedback from omnichannel retail operators (notably
Target) confirms that these are operational realities that surface the moment
fulfillment moves from deep-inventory warehouses to shallow-inventory stores
with human pickers.

Key question for the group: Are any of these hard blockers for adopting
the local fulfillment capability as proposed in this RFC? Or can retailers
implement pickup/curbside/local delivery today and layer in substitution,
variable pricing, and over-authorization when follow-up RFCs land?

C1. Substitution / Backup Items

Problem: When a store associate picks an order and the requested item is
out of stock, the standard practice is to offer a substitute. This is
especially common in grocery (produce, dairy, packaged goods) but applies to
general merchandise as well. Today, substitution flows are handled entirely
inside retailer-specific apps (Shipt, Target Drive Up, Walmart, Instacart)
with no interoperability.

Why it matters for local fulfillment: Store-level inventory is shallow
and volatile — out-of-stocks at pick time are routine, not exceptional. A
local fulfillment protocol that cannot express substitution forces platforms
to fall back to continue_url for the entire post-checkout pick flow,
undermining the value of protocol-level local fulfillment.

Minimum viable protocol surface (strawman for discussion):

• Checkout-time preferences per line item — a mechanism for buyers to
  express substitution intent:

  • "allow_substitution": true (accept business-selected substitute)
  • "allow_substitution": false (refund if unavailable)
  • "preferred_substitute_id": "sku_xyz" (buyer-specified backup)
  • "substitution_preference": "similar_item" | "same_brand" | "none"

• Substitute candidate declaration — a way for businesses to declare
  valid substitutes per line item, either as explicit SKU references or via
  category/attribute-based matching hints. This likely lives in catalog
  (substitute relationships are product data, not fulfillment data).

• Post-purchase substitution events — new lifecycle events:

  • substitution_proposed — associate proposes a substitute; payload
    includes original item, proposed substitute, price difference
  • substitution_accepted / substitution_rejected — buyer response
  • substitution_applied — substitute confirmed and order updated
  • item_removed — item removed from order (no substitute available or
    buyer declined)

• Price difference handling — does the buyer pay the substitute price or
  the original price? This is business policy, but the protocol needs to
  express the delta (e.g., price_adjustment on the substitution event).

• Eligibility interaction — some membership tiers offer free substitution
  upgrades (e.g., "we'll give you the name brand at the store brand price").
  This could hook into the depends_on_eligibility pattern from §13.

Proposed vehicle: A dedicated dev.ucp.shopping.substitution capability
or extension, scoped in a follow-up RFC. Substitution touches catalog (what
are valid substitutes?), checkout (buyer preferences), and post-purchase
(notification, approval/rejection, price adjustment) — bundling it into this
RFC would significantly expand scope.

Open question: Does substitution belong as an extension of fulfillment,
or as a standalone capability? It feels cross-cutting — it's triggered by
fulfillment but affects line items, pricing, and the order lifecycle.

C2. Price Range / Random Weight / Min-Max Pricing

Problem: Many grocery and fresh items are sold by weight — meat, deli,
produce, bulk goods. The price at checkout is an estimate based on an
average or requested weight. The actual price is not known until the item is
picked and weighed at the store. This creates a gap in UCP's current pricing
model, where line_item.totals is a fixed amount.

Why it matters for local fulfillment: Variable-weight pricing is
universal in grocery. A local fulfillment protocol that cannot express
estimated vs. actual pricing forces grocery retailers to either round up
(overcharging buyers) or handle the adjustment entirely outside the protocol.

Minimum viable protocol surface (strawman for discussion):

• Price type indicator on line items:

  {
    "price_type": "fixed | estimated | per_unit_weight",
    "estimated_range": {
      "min_amount": 450,
      "max_amount": 680
    },
    "unit_pricing": {
      "price_per_unit": 899,
      "unit": "lb | kg | oz",
      "estimated_quantity": 1.5
    }
  }

• Price resolution event — a post-checkout lifecycle event when the
  actual weight/price is confirmed:

  • price_adjusted — actual weight confirmed; payload includes original
    estimate, actual amount, and delta
  • This event would update the order total and trigger a payment adjustment

• Catalog representation — variant pricing would need to express
  per-unit pricing and estimated ranges, not just a single price amount.
  This affects catalog_search and catalog_lookup responses.

• Interaction with location_availability — a store might have
  "approximately 2.3 lbs of chicken breast available," but this is likely
  too granular for the protocol. Availability probably stays boolean/coarse;
  weight variability is handled at the line item pricing level.

Proposed vehicle: A dev.ucp.shopping.variable_pricing extension or
similar, scoped in a follow-up RFC. This cuts across catalog (displaying
estimated prices), checkout (estimated totals), and order (price adjustments
post-pick).

Open question: Is variable-weight pricing grocery-specific enough to
warrant its own extension, or should it be part of a broader "estimated
pricing" model that also covers things like custom configurations, made-to-
order items, and quote-based pricing?

C3. Over-Authorization for Substitutions and Weight Differences

Problem: Retailers routinely authorize payment for 10-15% above the cart
total to cover substitutions that cost more than the original item, weight-
based items that come in heavier than estimated, and (rarely) last-minute
picker additions. This is standard practice for Instacart, Shipt, Walmart
Grocery, Target Drive Up, and essentially every grocery delivery/pickup
service.

Why it matters for local fulfillment: Without over-authorization, any
price increase from substitution or weight variance would require a second
authorization — adding friction, risking declines, and degrading the buyer
experience. The payment must be authorized for enough to cover reasonable
variance at checkout time.

Minimum viable protocol surface (strawman for discussion):

• Authorization buffer declaration — where does the over-auth percentage
  or amount live?

  • Business-level: business_fulfillment_config.authorization_buffer_percent: 15
  • Per-method: local delivery and pickup might have different buffers than
    shipping (shipping rarely needs over-auth)
  • Per-line-item: variable-weight items might carry a higher buffer than
    fixed-price items

• Checkout totals distinction:

  • display_total — what the buyer sees ("estimated total: $47.50")
  • authorization_total — what the PSP authorizes ("authorized: $54.63")
  • settlement_total — what the buyer actually pays post-pick ("charged:
    $49.12")
  • Or: is this purely a business-side concern where the business authorizes
    more than the displayed total and settles for the actual amount, with no
    protocol representation needed?

• Buyer transparency — some jurisdictions require disclosure of over-
  authorization. Should the protocol carry a signal like "your card may be
  authorized for up to X% more than the displayed total"? Or is that
  business-side messaging via the existing description / message fields?

• Payment architecture coordination — over-auth is tightly coupled to
  the payment handler / PSP side of UCP. The totals model, the payment
  token exchange, and the settlement flow all need to be aware of the
  buffer. This likely requires coordination with whoever owns the payment
  architecture spec.

Proposed vehicle: A payment architecture extension, coordinated with the
PSP/payment handler spec owners. Over-authorization is not purely a
fulfillment concern — it's a payment concern triggered by fulfillment
realities.

Open question: Is over-authorization a protocol-level concern at all, or
is it an implementation detail between the business and their PSP? If the
business simply authorizes a higher amount and settles for less, does the
platform or buyer need to know about the buffer? The answer likely depends on
transparency/disclosure requirements, which vary by jurisdiction.

C4. Interaction Between C1–C3

These three concerns are deeply intertwined in practice:

1. A buyer orders 2 lbs of ground beef (variable weight) and a specific
   brand of pasta sauce (fixed price).
2. At pick time, the ground beef weighs 2.3 lbs (price increases) and the
   pasta sauce is out of stock (substitution triggered).
3. The substitute pasta sauce costs $1.50 more than the original.
4. The total has increased by ~$2.50 over the checkout estimate.
5. The over-authorization buffer covers this without a second auth.
6. The buyer is notified of the substitution and weight adjustment, approves,
   and the order settles at the actual amount.

A complete grocery local fulfillment story requires all three pieces working
together. The question for this group is whether they should be tackled as:

• (a) One combined RFC — "Grocery Fulfillment Extensions" covering
  substitution, variable pricing, and over-auth as a cohesive package
• (b) Two RFCs — substitution + variable pricing together (they're
  tightly coupled at the line item level), and over-auth separately (it's a
  payment concern)
• (c) Three separate RFCs — maximum modularity, but risks inconsistency
  across the three

Leaning toward (b) but would love input from folks closer to the payment
architecture side.

[amithanda]

Thanks @maximenajim for putting it together. I have very similar questions to what Drew already asked, so let's discuss in our review meeting live to get perspectives from everyone.

The other thing I was wondering was if there is a better way to structure the phases that you highlighted that aligns with e2e use cases that can be supported (Foundation → Methods → Locations & Availability and the Appendix A) e.g are there certain user journeys that can be supported when we land Foundation v/s what can be supported when we add Methods, Locations and Availability etc. I am hoping that every Phase unlocks some core e2e user journeys across platform and business. This might allows us to collate certain features together in a different way based on the use case. Do you think it makes sense?

[BuyWhere]

This RFC addresses a real pain point for multi-location commerce. From building BuyWhere (aggregating product data across Singapore retailers like FairPrice, Cold Storage, Giant), we found that:

1. Same retailer, different store — A product’s price and stock level can vary by location even within the same chain. FairPrice Central vs FairPrice Xtra have different inventory.
2. Fulfillment options change recommendation logic — An agent needs to know: can I pick this up today at the downtown store, or do I have to wait 2 days for delivery?
3. Store-specific promotions — Some discounts are location-locked. A store-based inventory signal lets the agent factor this in.

A few questions about the proposed scope:

• Will the store identifier be tied to a specific schema (e.g., Google Place ID, what3words) or left open-ended?
• For agents, is there a plan for a “nearest store” discovery tool, or is that left to the merchant implementation?

Happy to contribute real-world data points from Singapore retail if helpful for the RFC.