Enhancement Proposal: Attribution Signals Extension

[sanderslee2]

Summary

Today, merchants receive the cart, buyer info, and payment data but no context about the journey that led to the purchase. This extension solves this with a discovery_attribution object that describes how a product was discovered and what factors drove the recommendation.

Motivation

Traditional e-commerce generates rich attribution data through UTM parameters, referral headers, and click paths. UCP identifies which agent initiated a transaction via the agent profile URI but merchants have no visibility into how a product was discovered, why it was selected, or what product attributes drove the agent's recommendation. Without this, merchants cannot measure agent channel ROI, optimize product feeds for agent selection, or understand their competitive positioning in agent recommendations.

Goals

• Define an optional discovery_attribution extension on checkout requests carrying discovery context and match factors
• Use closed enumerations to prevent raw user query leakage
• Enable merchant analytics: agent channel measurement, product feed optimization, and competitive positioning

Non-Goals

• Affiliate crediting or referral tracking (separate concern)
• Merchant-to-agent attribution feedback
• Extracting how agents compute match factors or rank products

Detailed Design

Capability

{
  "capabilities": [{
    "name": "dev.ucp.shopping.checkout",
    "version": "2026-01-11",
    "extensions": [{
      "name": "dev.ucp.shopping.discovery_attribution",
      "version": "2026-02-18",
      "spec": "https://ucp.dev/extensions/discovery_attribution/spec.json",
      "schema": "https://ucp.dev/extensions/discovery_attribution/schema.json"
    }]
  }]
}

Schema

{
  "discovery_attribution": {
    "schema_version": "2026-02-18",
    "discovery_context": {
      "method": "direct_search | recommendation | comparison | browsing | reorder | wishlist_match | promotion | external_referral",
      "session_type": "active_shopping | passive_suggestion | automated_reorder | gift_recommendation",
      "query_category": "string (max 100 chars)",
      "alternatives_considered": "integer",
      "rank_position": "integer (1 = top)"
    },
    "match_factors": [
      {
        "type": "price | relevance | availability | rating | brand_preference | location | past_purchase | specification_match | promotion | sustainability | delivery_speed",
        "weight": "number [0.0–1.0]",
        "description": "string (max 200 chars, optional)"
      }
    ]
  }
}

Full Example

{
  "line_items": [{ "product_id": "prod_trail_runner_42", "quantity": 1 }],
  "buyer": {
    "email": "jane@example.com",
    "shipping_address": {
      "line1": "123 Main St", "city": "San Francisco",
      "state": "CA", "country": "US", "postal_code": "94102"
    }
  },
  "discovery_attribution": {
    "schema_version": "2026-02-18",
    "discovery_context": {
      "method": "comparison",
      "session_type": "active_shopping",
      "alternatives_considered": 8,
      "rank_position": 1
    },
    "match_factors": [
      { "type": "specification_match", "weight": 0.40 },
      { "type": "rating", "weight": 0.25 },
      { "type": "price", "weight": 0.20 },
      { "type": "delivery_speed", "weight": 0.15 }
    ]
  }
}

Minimal Example

{
  "discovery_attribution": {
    "schema_version": "2026-02-18",
    "discovery_context": {
      "method": "recommendation",
      "session_type": "passive_suggestion"
    }
  }
}

Risks and Mitigations

User data leakage. Discovery context uses closed enumerations instead of free text. query_category and match_factors[].description have character limits and must not contain PII.

Gaming match factors. Agents could misrepresent weights to influence merchant behavior. Match factors are informational signals for analytics only — merchants should treat them as non-authoritative.

Test Plan

Unit tests:

• Schema validation with/without discovery_attribution
• Enum validation
• Character limit enforcement

Integration tests:

• Capability negotiation correctly includes/excludes extension
• End-to-end checkout with full discovery_attribution
• Partial attribution with minimum fields

End-to-end tests:

• Full happy path through to order webhook with attribution preserved
• Graceful degradation when merchant doesn't declare extension

Graduation Criteria

Working Draft → Candidate:

• Schema merged and documented (with Working Draft disclaimer)
• Unit and integration tests are passing
• Initial documentation is written
• TC majority vote to advance

Candidate → Stable:

• Adoption feedback has been collected and addressed
• Full documentation and migration guides are published
• TC majority vote to advance

---

Edited 2026-02-18: Narrowed scope to discovery context and match factors only. Affiliate crediting deferred to a separate extension.