How UCP’s New Attribution Field Will Transform Agentic Commerce Tracking

On May 5, 2026, the UCP Technical Council merged a pivotal pull request into the core specification, introducing a new attribution field to cart, checkout, catalog, and order operations. This field standardizes how platforms pass referral and conversion context—such as campaign IDs, click identifiers like gclid or fbclid, and source/medium markers—through agentic commerce workflows. Unlike restrictive extensions, the field is a top-level, open string-keyed map, universally available without capability negotiation.

The addition reflects UCP’s maturing role as the backbone of agentic commerce infrastructure. Without a standardized way to carry advertising and measurement context alongside transactional data, vendors would inevitably resort to incompatible parallel solutions, fragmenting the ecosystem. The merge itself wasn’t surprising; what stands out is the architectural choice behind it and what it signals about UCP’s future direction.

The technical design of the attribution field

The attribution field is intentionally minimalist. As outlined in the pull request by Ilya Grigorik, it functions as a flat key-value object carrying platform-generated referral identifiers. For example:

{
  "attribution": {
    "campaign_id": "18234567890",
    "campaign_source": "google",
    "campaign_medium": "cpc",
    "campaign_name": "spring_2026",
    "gclid": "EAIaIQobChMI..."
  }
}

There is no prescribed schema beyond the requirement that it be a string-keyed object. Platforms populate it using their existing conventions—whether Google Analytics 4 parameters, Facebook click IDs, or custom tracking keys—while merchants process the data according to their own analytics pipelines. UCP does not enforce attribution windows, models, or assignment logic; the protocol simply carries the data, leaving interpretation to downstream systems.

The field appears in three distinct roles across the request lifecycle:

• Catalog (search/lookup): Platform-emitted input, sent from platform to merchant
• Cart: Platform-emitted input, sent from platform to merchant
• Checkout: Platform-emitted input, sent from platform to merchant
• Order: Business-emitted snapshot, sent from merchant to platform

This asymmetry is deliberate. On catalog, cart, and checkout, the platform writes the attribution as it would embed UTM parameters in a browser URL—forwarding referral context. On order, the merchant preserves the original attribution as a snapshot, closing the loop between agent-mediated conversion and the originating platform.

Grigorik summarized the intent concisely: the field "carries the same parameters platforms communicate via URL query parameters in browser-based flows, in the same flat key-value form." In agentic commerce, attribution operates like UTM strings—same parameters, same intent, but transported through a different layer.

The implementation touched 13 files, with the core addition being source/schemas/shopping/types/attribution.json. The new type definition was added as an optional property to schemas for cart, catalog_lookup, catalog_search, checkout, and order. Documentation across cart, catalog, checkout, order, and the overview section was updated to clarify the field’s purpose and semantics.

Why a core field, not an extension?

The architectural decision to make attribution a top-level core field—rather than a negotiated extension—was the most consequential aspect of the pull request. Grigorik’s proposal (#391) directly challenged an earlier alternative (#295) opened by James Andersen of Meta, which suggested a structured event_context extension with capability negotiation and validated schemas.

Andersen ultimately endorsed Grigorik’s alternative, stating, "thanks for finding a better home for attribution data than the original proposal," and the rearchitecture moved forward through Technical Council discussion.

This dynamic—where one contributor proposes a solution and another offers a structurally different alternative—is a hallmark of robust standards development, preventing fragmentation by aligning on the best fit rather than vendor-specific defaults.

Amit Handa’s comment on May 3 crystallized the decision framework, which may serve as precedent for future spec discussions:

| Criterion | Use a UCP Extension | Use Optional Flat Key-Value Pairs | |----------------------------|----------------------------|-------------------------------------------| | Impact on Behavior | Changes state or execution | Purely informational | | Data Stability | Stable, standardized | Volatile, platform-specific | | Capability Negotiation | Requires mutual agreement | Best-effort, consumed at-will | | 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 aligns perfectly with the right-side characteristics. Marketing identifiers like gclid, fbclid, and ttclid are inherently volatile and platform-specific—new adtech vendors emerge constantly, making standardization impractical. Attribution does not alter protocol behavior; it’s read-only context with no transactional consequence. There’s no need for merchants to negotiate capabilities or for UCP to enforce a rigid schema. The data flows best-effort, with downstream systems responsible for processing.

Without this flexibility, UCP risked accumulating extensions that would either ossify quickly or fail to accommodate new advertising ecosystems. By embedding attribution in core, the protocol acknowledges that some data belongs in the transport layer—not the specification—where it can evolve without stifling innovation.

A turning point for agentic commerce

The inclusion of attribution in UCP core marks a quiet but profound shift in how commercial agents operate. By standardizing the movement of referral context across platforms and merchants, UCP removes a critical friction point in agentic commerce: the inability to track conversions in a way that mirrors browser-based flows.

For merchants, this means cleaner data pipelines and fewer workarounds. For platforms, it reduces the need to build ad-hoc integrations. For the entire ecosystem, it signals UCP’s growing maturity as a comprehensive protocol—not just a transaction engine, but a bridge between commerce and marketing.

As agentic commerce scales, the ability to carry attribution data natively will become less of a feature and more of a baseline expectation. The next frontier may involve richer contextual signals, but for now, UCP has taken a decisive step toward making agentic commerce as trackable and measurable as its browser-based counterpart.