Skip to content

feat: add negotiated fulfillment location context - #671

Open
igrigorik wants to merge 1 commit into
mainfrom
feat/location-context-contract
Open

feat: add negotiated fulfillment location context#671
igrigorik wants to merge 1 commit into
mainfrom
feat/location-context-contract

Conversation

@igrigorik

Copy link
Copy Markdown
Contributor

This PR supersedes #642, which identified the need to preserve the Business location behind store-scoped Catalog results through Cart and Checkout. Instead of adding #642's raw location field to base Context, this PR makes support explicit through Fulfillment.

  • adds optional context.location to Fulfillment's Catalog, Cart, and Checkout projections;
  • gives Cart location-aware Context without full Fulfillment structures;
  • introduces one opaque, stable, Business-scoped Location Identifier;
  • defines field roles, cross-Business isolation, unknown-ID handling, and precedence.

Adding a Business-defined location ID to base Context would define its syntax without advertising which Businesses recognize it, which operations consume it, or what behavior it affects. Fulfillment owns the relevant surfaces: Catalog methods report resolved locations, Catalog filters name destinations, and Checkout exposes destinations and selections. Contributing context.location through Fulfillment lets parties negotiate each parent capability with extends.

Contract

The same Location Identifier can appear in several fields without giving them the same meaning:

Field Meaning
context.location Provisional, non-binding anchor for location-scoped pricing, availability, estimates, or initial options.
Catalog filters.fulfills_to Explicit destination filter: can this product be fulfilled to here?
variants[].fulfillment.methods[].location Location for which a place-based Catalog method was resolved.
Checkout selection or authoritative address Explicit destination for that scope; supersedes context.location.

Journey example...

Catalog reports method.location = loc_123
        ↓
Cart carries context.location = loc_123
        ↓
Cart-to-Checkout preserves context.location
        ↓
Checkout offers loc_123 as an initial choice
        ↓
Platform selects selected_destination_id = loc_123
  → loc_123 becomes explicit for that fulfillment scope

The new common/types/location_id.json reuses the existing string wire type across Fulfillment context, Catalog method locations, destination filters, and retail locations. Within one Business, the same value identifies the same location; its containing field determines its role. selected_destination_id stays generic because it can select other destination types.


Checklist

  • Capability: New schemas (Discovery, Cart, etc.) or extensions.
  • Documentation: Updates to README, or documentations regarding schema or capabilities.
  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.

   Store-scoped Catalog results had no advertised way to preserve the
   Business location through Cart and into Checkout. Defining the field on
   base Context would make every Shopping implementation accept an opaque
   Business-scoped identifier without advertising the behavior that produces
   or consumes it.

   Have Fulfillment contribute `context.location` to Catalog requests, Cart,
   and Checkout through explicit parent composition. Cart receives only the
   location context, and implementations supporting both Catalog and Cart
   should extend both to preserve continuity. For example, `loc_123` can
   scope Catalog availability, continue through Cart, and become explicit
   only when selected as a Checkout destination.

   Introduce a shared Location Identifier and reuse it for Fulfillment
   context, Catalog method locations, destination filters, and retail
   locations. This preserves one identity across surfaces while each
   containing field defines its role. Keep `selected_destination_id` generic
   because it may also reference non-location destinations.
@igrigorik igrigorik added this to the Working Draft milestone Aug 1, 2026
@igrigorik
igrigorik requested a review from jingyli August 1, 2026 05:00
@igrigorik igrigorik self-assigned this Aug 1, 2026
@igrigorik igrigorik added the TC review Ready for TC review label Aug 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

TC review Ready for TC review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant