Skip to content

feat: add platform_reference for platform-side order correlation - #839

Draft
vishkaty wants to merge 2 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:feat/platform-reference
Draft

vishkaty wants to merge 2 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:feat/platform-reference

Conversation

@vishkaty

@vishkaty vishkaty commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Implements the contract agreed with @williammacarini on #413, with the 2026-10-26 review by @gforgab applied in abfcfdf.

platform_reference is an opaque, platform supplied correlation value. A platform instance serves many buyers across many businesses, and checkout_id is business scoped, so it is not unique across businesses. This gives the platform a key it assigns itself, so it can correlate later order events without keeping a mapping of business assigned identifiers.

Contract:

surface annotation
checkout create request optional
checkout update request omit
checkout complete request omit
checkout response echoed
order response only, carried from the originating checkout

For the Tech Council:

  1. Placement on Create rather than Complete. The issue text proposed Complete. Create keeps correlation available for the whole lifecycle and survives an ambiguous Complete timeout.
  2. update: omit, with the business retaining the create time value.

Rules carried in prose, because the annotation alone cannot carry them. The checkout object is open, so a value resent on update or complete validates in default mode, and strict mode depends on the schema revision: ucp-schema 1.4.1 rejects it at the base this PR was reviewed on and accepts it at current main after #940. So a business MUST ignore a platform_reference on an update or complete request, MUST NOT reject the request because of it, and MUST retain the Create Checkout value; stated in checkout/index.md, checkout/rest.md and the update_checkout descriptions of rest.openapi.json and mcp.openrpc.json. A business MUST reject a value over 512 characters as an invalid request and MUST NOT truncate it, and both schemas carry minLength: 1. Idempotent cart conversion keeps the stored value and never adds one. A business SHOULD NOT apply the field from a permalink query parameter. Privacy is MUST NOT, per the point @sbeashwar raised on the issue: no personally identifiable information, no directly identifying values, no credentials, and not for authentication, authorization or idempotency on either side; platforms SHOULD use an opaque, non guessable value per purchase flow. The encodings listed in the issue body (session id, composite key, signed JWT) are left out because they conflict with that rule, as @williammacarini asked. A non normative multi business example closes the section.

Verification on this head, a fast forward on the reviewed head 446fa35 and not rebased, all local:

gate result
ucp-schema lint source/ (1.4.1, identical with 1.4.0) 124 files passed, 8 W002 warnings, same as 446fa35
scripts/validate_examples.py 344 passed, 0 failed, 50 skipped, same as 446fa35
scripts/test_validate_examples.py 57 passed, the full suite at this base
scripts/test_schema_tables.py not present at this base, not rerun
yamllint exit 0
pre-commit, pinned hooks, all files 17 of 18 hooks passed; stylelint cannot load its config in this environment, on 446fa35 as well, and no CSS file changes
mkdocs build --strict, DOCS_MODE=spec, then check_links the strict build aborts here on 47 cairosvg warnings, because the cairo library is missing in this environment, so this is not a clean strict run; the warning set is identical to 446fa35 and names no changed page, check_links reports the same two anchor issues on untouched pages, and the new links resolve
schema oracle, ucp-schema 1.4.1 create request: empty string rejected, 512 characters pass, 513 fail; update request carrying the field: accepted in default mode at this head, at 446fa35 and at main
rendered projection platform_reference row in the Create Checkout table and the capability schema table, absent from the Update and Complete tables

The python-sdk and js-sdk regeneration figures from the 2026-09-18 revision predate minLength and were not rerun. One caveat for reviewers: zod strips unknown keys, and the latest @ucp-js/sdk release is 0.5.1, so a business that passes a checkout or order through its generated schemas drops platform_reference until an SDK release. That is inherent to any new optional field.

Adjacent work: #660 (mine) edits the same Update Checkout sentences in checkout/index.md, checkout/rest.md, rest.openapi.json and mcp.openrpc.json for buyer.consent; whichever lands second rebases. #816 touches both schemas but not these insertion points.

Not for merge before #413 advances; placement on Create is for the TC to confirm. @williammacarini owns the companion conformance work, opened as conformance#118 by @gforgab; the samples implementation is mine.

Adds an opaque, platform-supplied correlation value set on Create Checkout and
immutable thereafter. A platform instance serves many buyers across many
businesses, and checkout_id is business-scoped, so it is not unique across
businesses. platform_reference lets a platform correlate later order events to
its own records without keeping a mapping of business-assigned identifiers.

Contract:
  checkout: create optional, update omit, complete omit, echoed on responses
  order:    response only, carried from the originating checkout, immutable

The checkout object is open, so a value resent on update or complete still
validates. The prose therefore states the rule directly: a business MUST ignore
a platform_reference received on an update or complete request and MUST retain
the value established at Create Checkout.

Privacy: platforms MUST NOT place personally identifiable information or
credentials in this field, and MUST NOT use it for authentication,
authorization, or idempotency.

Two points for the Tech Council: placement on Create rather than Complete as
the issue text proposed, and update omit with the business retaining the
create-time value.

Refs Universal-Commerce-Protocol#413
@damaz91 damaz91 added the area:shopping Issues and pull requests related to the Shopping vertical label Sep 24, 2026
@vishkaty
vishkaty marked this pull request as ready for review October 16, 2026 20:17

@gforgab gforgab left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed for Mercado Pago, since this implements the contract @williammacarini agreed on #413 (our case: a platform-side parent cart that fans out into one checkout per Business). The core of what was agreed is here:

  • the field is set on Create only and is immutable afterwards (omit on update/complete, plus the MUST-ignore rule);
  • it is echoed verbatim and carried onto the order and every order webhook;
  • it is opaque, at most 512 characters, and excluded from auth.

I checked it against the #413 thread. A few points from that agreement didn't make it in or are narrower than agreed, and are noted inline:

  • Privacy: the agreed rule also excluded directly identifying values, and William asked for opaque values.
  • Idempotency ban: it was stated without a subject on #413, but here it binds only the platform.
  • Testability: over-length rejection, absence, and Get Order were part of William's test plan.

Inline I've also flagged idempotent cart conversion, where Create Checkout with a cart_id returns an existing checkout. All inline comments are non-blocking suggestions.

Three non-inline points:

  1. Process. On #413 the plan was to keep this as a draft until the TC confirmed Create placement. It was marked ready for review on 10-16, and #413 is still at Proposal: has the TC confirmed Create placement? Could a maintainer confirm which TC reviews it (#413 is area:payments, this PR is area:shopping) and add gov:needs-tc-review?
  2. CI. The lint, spell, docs and commit checks from 09-18 show zero jobs, so they never ran. A rebase onto main should re-trigger them. Locally the branch merges cleanly with main, ucp-schema lint passes, and the example corpus validates.
  3. Multi-Business scenario. #413 agreed to document it rather than spec it. A short non-normative example would help readers: one platform orchestration, two Businesses, the same platform_reference, possibly colliding checkout_ids.

@vishkaty, on your #413 points (single-Business first, you on samples, target current main): agreed. William is away until early November, so I'll open the conformance PR as a draft from his #413 test plan and hand it back when he returns. Its Order and webhook tests will fail against samples until the server carries the field onto the Order. Happy to help with that change.

Comment thread source/schemas/shopping/checkout.json Resolved
Comment thread source/schemas/shopping/order.json Resolved
…tocol#839

Takes the inline review on Universal-Commerce-Protocol#839: permalink exclusion and absence
detection, every order plus Get Order to the originating platform,
business side ban on authentication, authorization, idempotency and
deduplication, directly identifying values excluded, opaque value
guidance, MUST NOT reject a resent value, cart conversion rule,
minLength 1 with a prose maximum length rule, normative absence on
the order, and MUST on the order event paragraph. Mirrors the update
rule into checkout/rest.md and the update_checkout descriptions of
rest.openapi.json and mcp.openrpc.json, and adds a non-normative
multi-business example.
@vishkaty
vishkaty marked this pull request as draft October 27, 2026 02:01
@vishkaty

Copy link
Copy Markdown
Contributor Author

All eight inline suggestions are in abfcfdf, five verbatim and three with the amendments stated in the threads, as a new commit on the reviewed head 446fa35 (a plain fast forward, not a rebase) so the review threads keep their anchors.

  1. Process: not confirmed. [Proposal]: Platform Correlation Reference for Checkout and Order Webhook Events #413 has no comment since 2026-09-18. I marked this ready on 2026-10-16 ahead of that confirmation, against the plan on [Proposal]: Platform Correlation Reference for Checkout and Order Webhook Events #413, so it is back in draft until the TC confirms placement; the review is applied in full regardless. The label and the TC routing are maintainer actions.
  2. CI: confirmed, the five runs created 2026-09-18T13:19:30Z ended in failure with zero jobs. Each run page says the run required approval and was not approved before it expired; GitHub expires fork runs that wait more than 30 days (https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks). The push of abfcfdf created five new runs, all awaiting approval, so a maintainer approval is what starts them. The docs.yml steps at this base pass locally on the pushed head: ucp-schema lint 124 files with the same 8 W002 warnings as 446fa35, validate_examples 344 passed and 0 failed (same as 446fa35), the validator unit tests 57 passed, yamllint exit 0, and the pinned pre-commit hooks pass except stylelint, which cannot load its config in this environment on 446fa35 either and covers no changed file.
  3. Multi business scenario: a non normative paragraph closes the section: one parent cart, two businesses, the same platform_reference on both Create Checkout calls, both returning checkout id chk_1, each order event carrying the shared value.

On conformance#118: noted. The samples change is mine per #413 and follows #839 merging, since the samples server declares 2026-04-08 and builds the order from SDK models that do not declare the field. Help on it is welcome then.

@williammacarini

Copy link
Copy Markdown

Thanks @vishkaty — I checked abfcfdf against what we agreed on #413 and it covers the full contract, including Gabriel's suggestions. From the Mercado Pago side this is ready for TC review.

Two things need a maintainer: (1) approving the pending fork workflow runs on abfcfdf so CI actually runs, and (2) routing to a TC and adding gov:needs-tc-review — #413 is area:payments, this PR is area:shopping, and the open decision (Create vs Complete placement, update: omit) is a Shopping TC call. Could one of the maintainers pick this up? Happy to present the multi-business use case at a TC meeting or at the Summit.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:shopping Issues and pull requests related to the Shopping vertical

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants