acp-intent-traces

# ACP Intent Traces

## Before writing code

**Fetch live docs**:
1. Web-search `site:github.com agentic-commerce-protocol rfcs intent_traces` for the intent traces RFC
2. Fetch `https://developers.openai.com/commerce/specs/checkout/` for how intent traces integrate with checkout
3. Web-search `site:github.com agentic-commerce-protocol spec json-schema intent` for the schema

## Conceptual Architecture

### What Intent Traces Are

Intent traces are a **built-in ACP extension** that provides structured cart abandonment signals. When a buyer abandons a checkout, the agent sends a trace explaining why — enabling merchants to understand conversion barriers and automate recovery.

### 10 Reason Codes

| Code | Meaning |
|------|---------|
| `price_sensitivity` | Total was too expensive |
| `shipping_cost` | Shipping cost was a barrier |
| `shipping_speed` | Delivery time was too slow |
| `product_fit` | Product didn't match buyer's needs |
| `trust_security` | Buyer didn't trust the merchant/payment |
| `returns_policy` | Return/refund policy was inadequate |
| `payment_options` | Preferred payment method unavailable |
| `comparison` | Buyer is comparison shopping |
| `timing_deferred` | Buyer wants to purchase later |
| `other` | Doesn't fit other categories |

### How It Works

1. Buyer initiates checkout but doesn't complete
2. Agent detects abandonment (session timeout, explicit cancellation, navigation away)
3. Agent sends intent trace via `POST /checkout_sessions/{id}/cancel`, including a single `reason_code` (required enum string, exactly one per trace)
4. Merchant receives the trace and can:
   - Aggregate for analytics
   - Trigger automated recovery (email, discount offer)
   - Adjust pricing/shipping strategy

### Privacy Considerations

- Intent traces contain behavioral signals — handle per GDPR/CCPA
- Only collect traces when the buyer has consented to data collection
- Don't store personally identifiable information in trace metadata
- Aggregate traces for analytics rather than individual tracking

### Extension Negotiation

Like all extensions, intent traces must be negotiated:
1. Agent includes `intent_traces` in `capabilities.extensions[]`
2. Merchant confirms support
3. Only then are traces exchanged

### Use Cases

- Cart abandonment analytics dashboards
- Automated recovery email workflows
- Dynamic pricing based on price sensitivity signals
- Shipping strategy optimization
- A/B testing checkout flows
- Conversion funnel analysis

### Additional Trace Fields

- **`trace_summary`** — Optional free-text summary of the abandonment reason (max 500 characters)
- **`metadata`** — Optional flat key-value map for additional context (string keys and string values only)

### Write-Only Behavior

Intent traces are **write-only** — they are sent on the `POST /checkout_sessions/{id}/cancel` endpoint and are never echoed back in GET responses. This prevents information leakage and ensures traces are used only for analytics and recovery workflows.

### Best Practices

- Send traces on every abandonment — even `other` is better than no signal
- Each trace has a single `reason_code` (required enum string); if the buyer has multiple reasons, choose the most significant one
- Process traces asynchronously — don't block the cancellation flow
- Build aggregate dashboards before automated recovery
- Test trace collection end-to-end with the agent platform
- Respect buyer privacy — anonymize before long-term storage

Fetch the intent traces RFC for exact trace payload structure, reason code definitions, and integration points before implementing.