On May 5, 2026, the UCP Technical Council merged PR #391 into the spec's main branch — adding a top-level attribution field to cart, checkout, catalog, and order operations. The field carries platform-emitted referral and conversion-event context: campaign IDs, click identifiers (gclid, fbclid, ttclid), source/medium markers. Open string-keyed map. Universal across requests; not gated by capability negotiation.
As UCP matures, attribution landing in core was always going to happen. Agentic commerce can't operate as commercial infrastructure without a path for advertising and measurement context to flow alongside the transactional data — and the longer that gap stayed open, the more pressure would have built for vendors to ship incompatible parallel solutions. The merge isn't the surprising part. The interesting part is the specific shape of what shipped, and what its presence in core tells us about where the spec is heading.
Two things to dig into: the technical detail of the field itself, and the trajectory implication of advertising and measurement infrastructure landing in UCP core for the first time.
What shipped
The attribution field is structurally simple. From Grigorik's own example in the PR:
{
"attribution": {
"campaign_id": "18234567890",
"campaign_source": "google",
"campaign_medium": "cpc",
"campaign_name": "spring_2026",
"gclid": "EAIaIQobChMI..."
}
}
No prescribed schema beyond "string-keyed object." Platforms populate it with whatever conventions they already use — GA4 campaign parameters, click identifiers, custom tracking keys. Businesses receive the data and process per their own analytics needs. UCP itself does not prescribe attribution windows, models, or assignment logic. The protocol carries the data; attribution math happens downstream.
The field appears in three roles across the request lifecycle:
| Operation | Role | Direction |
|---|---|---|
catalog (search, lookup) |
Platform-emitted input | Platform → merchant |
cart |
Platform-emitted input | Platform → merchant |
checkout |
Platform-emitted input | Platform → merchant |
order |
Business-emitted snapshot | Merchant → platform |
The asymmetry matters. On catalog/cart/checkout, the platform writes attribution as it would write a UTM string into a browser URL — referral context flowing forward. On order, the business preserves the originating attribution as a snapshot — closing the loop between agent-mediated conversion and the platform that produced it.
Grigorik's framing in the PR is the cleanest one-line summary of intent: the field "carries the same parameters platforms communicate via URL query parameters in browser-based flows, in the same flat key-value form." Attribution in agent-mediated commerce is the agent counterpart of UTM strings. Same parameters, same model, different transport layer.
Thirteen files changed. The core addition is source/schemas/shopping/types/attribution.json — the new type definition. Schemas for cart, catalog_lookup, catalog_search, checkout, and order all gain the field as an optional property. Specification docs across cart, catalog, checkout, order, and the overview were updated to describe the field's purpose and semantics.
The architectural decision: core field, not extension
The substantively interesting part of this PR is not what got added. It's how it got added.
PR #391 was Grigorik's alternative proposal to PR #295, which James Andersen had opened earlier proposing an event_context extension. Both proposals tried to solve the same problem — give platforms a way to pass referral/attribution data through to merchants in agent flows — but with very different architectural shapes:
- #295 (Andersen, Meta): Attribution as a structured extension. Capability-negotiated. Validated against a defined schema. Standardised vocabulary across platforms.
- #391 (Grigorik, Shopify): Attribution as a top-level core field. Open key-value map. No capability negotiation. Each platform uses its own conventions.
Andersen formally approved Grigorik's alternative — "thanks for finding a better home for attribution data than the original proposal" — and the rearchitecture went on to merge through TC discussion. That cross-vendor pattern (one TC member proposes; another offers a structurally different alternative; the original proposer endorses it) is the dynamic that produces robust standards rather than fragmented vendor extensions.
The PR discussion pivots on which architectural shape this kind of data deserves. Amit Handa wrote the canonical comment on May 3 establishing the decision framework — worth quoting because it'll likely be cited as governance precedent in future spec discussions:
| Criterion | Use a UCP Extension | Use Optional Flat Key-Value Pairs |
|---|---|---|
| Impact on Behavior | Changes state or execution of the operation | Purely informational |
| Data Stability | Stable, standardized vocabulary | Volatile, platform-specific, rapidly evolving |
| Capability Negotiation | Requires mutual agreement + active parent capability | Best-effort, consumed at-will, no gating |
| Schema Validation | Strict — transaction integrity matters | Flexible — validation happens downstream |
| Multi-Platform Scale | Data normalization across diverse platforms | Low friction; normalization burden on receiver |
| Typical Examples |
discount, fulfillment
|
attribution, referral tracking, session tags |
Attribution falls cleanly on the right side of every row. Marketing identifiers (gclid, fbclid, ttclid) are volatile and platform-specific — every adtech vendor invents their own; standardising them in the spec would be obsolete the moment a new platform launches. Attribution doesn't change protocol behaviour — it's read-only context that some downstream pipeline cares about, with no transactional consequence. There's nothing for a merchant to negotiate; either you record it or you don't.
The merged PR locks this decision in. Future contributors proposing similar volatile, informational, platform-specific data structures now have a precedent: the spec prefers flat optional key-value pairs over structured extensions for non-state-changing context. That's a piece of governance documentation as much as a feature merge, and Handa's table will be the reference for it.
The trajectory implication
UCP up to this point has been protocol mechanics. How agents discover stores. How they shop. How they pay. How they identify users. How they handle returns. The mechanics are necessary, but they don't directly produce commercial value for the ecosystem participants. A merchant with a perfectly conformant UCP implementation but no attribution can't measure agent-driven conversions, can't optimise marketing spend, can't close the loop between platform investment and merchant outcomes.
attribution closes that loop. With the field in core, the entire adtech infrastructure that powers current ecommerce extends naturally into agent-mediated commerce. Platforms attribute conversions to specific campaigns. Click identifiers persist across the agent flow. Businesses run their existing analytics pipelines on agent-driven traffic with no special handling. The bridge that makes UCP commercially usable for marketing teams — not just engineering teams — now exists in the core spec.
The trajectory implication is the part worth sitting with: UCP is evolving from protocol mechanics into commercial infrastructure. Each subsequent spec addition probably bridges another piece of existing commerce infrastructure into the agent layer. Loyalty programs. Customer data platforms. Marketing automation triggers. Inventory hooks. Each one makes UCP more complete as commercial infrastructure rather than just protocol mechanics.
The architectural-precedent decision in #391 makes that trajectory more efficient. Future contributors proposing similar bridges (attribution-adjacent measurement primitives, marketing identifiers, session metadata) now have a clear template: flat key-value pairs into core, governance precedent already established. The spec doesn't need to relitigate the core-vs-extension decision every time a volatile, informational primitive comes up.
What it means in practice
For merchants: your UCP implementation should accept the attribution field on incoming cart, checkout, and catalog requests, preserve it through to order records, and surface it through your analytics pipeline. The lift is small — it's a string-keyed JSON object on existing endpoints — but missing it means agent-driven conversions arrive at your analytics with no source attribution, which means your marketing team can't measure the channel.
For platform vendors (Shopify, WooCommerce, BigCommerce, Magento, and others): rolling attribution support into the next platform-side compatibility release is now table-stakes work. The stores running on your stack will need to accept and preserve attribution by the time the next published spec version makes this part of conformance.
For agent platforms (those of us building or testing agents that shop UCP stores): pass platform-emitted attribution forward into every cart/checkout/catalog request. The data is informational, not state-changing — your agent doesn't need to do anything with it beyond passing it through. The merchant decides what to do with it on the receive side.
For evaluators (us): the UCP Score will incorporate attribution-acceptance and attribution-preservation conformance in its next release. A store that accepts attribution on cart/checkout/catalog and threads it through to order records will score higher than one that drops it. The methodology page will reflect the rule update when the next score-version drops.
Timing: in core today, in the published spec next
One important distinction worth making explicit. PR #391 merged into the spec's main branch — not into a currently-published spec version. The latest released spec is v2026-04-08, which does not include attribution. The field lands for conformance purposes in whatever the next published spec version ships (no fixed cadence; expected in the next few months). Until then, attribution sits in the working draft on main — implementers can adopt it ahead of the release if they want, but it's not yet part of conformance for the published spec.
That distinction shapes how we're rolling out support across our tools:
- UCP Playground will adopt attribution support when the next spec version drops — agents will pass platform attribution through to merchants.
- The UCP Score will incorporate attribution-acceptance and attribution-preservation rules in the score release that aligns with the next published spec.
- The validator will support the new field as soon as the next spec ships, and the bulk checker will surface attribution conformance per-merchant after that.
The architectural certainty is already here — the schema is locked, the field is documented, the design pattern is settled. The spec drop is the conformance trigger, not the design moment. Implementers who start work today against the working draft are operating against a known target.
Where to read more
- The PR itself: #391 on Universal-Commerce-Protocol/ucp
- The merge commit:
76a3539 - The new schema type:
source/schemas/shopping/types/attribution.json - Updated authoring guidance:
docs/documentation/schema-authoring.md
About UCP Checker
UCP Checker is the independent validation and monitoring layer for the Universal Commerce Protocol. We crawl, validate, and grade every public UCP manifest in the open web, run the merchant directory and the UCP Score, publish the leaderboard and adoption stats, and track major spec events like this one as they ship.
If you're building on UCP and want to know whether your store is ready for the next spec version: run a check. If you're tracking the spec's evolution professionally: subscribe to our weekly digest — we cover spec changes like this one within a week of merge.
