Repository navigation
Conversation
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
gforgab
left a comment
There was a problem hiding this comment.
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 (
omiton 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:
- 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 isarea:shopping) and addgov:needs-tc-review? - 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 lintpasses, and the example corpus validates. - 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 collidingcheckout_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.
…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.
|
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.
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. |
|
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 |
Implements the contract agreed with @williammacarini on #413, with the 2026-10-26 review by @gforgab applied in abfcfdf.
platform_referenceis an opaque, platform supplied correlation value. A platform instance serves many buyers across many businesses, andcheckout_idis 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:
For the Tech Council:
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_referenceon 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 carryminLength: 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:
platform_referencerow in the Create Checkout table and the capability schema table, absent from the Update and Complete tablesThe python-sdk and js-sdk regeneration figures from the 2026-09-18 revision predate
minLengthand were not rerun. One caveat for reviewers: zod strips unknown keys, and the latest@ucp-js/sdkrelease is 0.5.1, so a business that passes a checkout or order through its generated schemas dropsplatform_referenceuntil 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.