Skip to content
Cresva
Developers
Changelog

Protocol changelog. Every version. Every breaking change.

A complete history of Agent Commerce Protocol versions. Each release includes what changed, why it changed, and how to migrate.

v2.0

CurrentMarch 2026

Negotiation, Transactions & Trust

ACP v2.0 is a major release that extends the protocol from read-only product queries to full-lifecycle commerce. Agents can now negotiate prices, execute transactions with escrow, and assess brand trustworthiness through a structured trust score system. This release reflects 6 months of feedback from early adopters who needed more than catalog search - they needed a protocol that could close the loop from discovery to delivery.

Breaking changes

  • The query response envelope changed from { results: [...] } to { products: [...] }. All clients consuming query responses must update their field access. See Spec Section 4.2.
  • Error responses now follow RFC 7807 Problem Details format. The previous { error: string, code: number } shape is no longer returned. See Spec Section 8.1.
  • Rate limit headers changed from X-RateLimit-* to standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers per the IETF Rate Limiting draft. See Spec Section 7.3.
  • The discovery manifest schema added required fields: protocol_version, capabilities, and endpoints. Manifests missing these fields will fail validation. See Spec Section 2.1.

Migration notes

To migrate from v1.x to v2.0: (1) Update your discovery manifest to include the new required fields. (2) Update query response parsing to use the products key instead of results. (3) Update error handling to parse RFC 7807 Problem Details. (4) Update rate limit header parsing. The v1.x query and discovery endpoints remain available at /v1/* paths for 12 months after the v2.0 release (sunset: March 2027).

Changes

  • Added negotiation protocol with typed offers, counter-offers, and state machine(Spec Section 5.1)
  • Added transaction protocol with full lifecycle management(Spec Section 6.1)
  • Added escrow support for conditional purchases with timed release(Spec Section 6.4)
  • Added trust score system with 7 components and tier classification(Spec Section 9.1)
  • Added 30+ webhook event types for real-time notifications(Spec Section 10.1)
  • Added HMAC signature verification for webhook security(Spec Section 10.3)
  • Added agent-exclusive offers and bundle endpoints(Spec Section 5.5)
  • Added price hold mechanism for time-limited pricing(Spec Section 5.3)
  • Added feedback endpoint for agent quality signals(Spec Section 9.4)
  • Added degradation headers for partial/stale data indication(Spec Section 7.5)
  • Enhanced product card format with comparison highlights and brand voice summary(Spec Section 4.3)
  • Enhanced query protocol with review and availability intents(Spec Section 4.1)
  • Improved error responses with detailed field-level validation(Spec Section 8.1)
  • Added cart management endpoints for multi-product transactions(Spec Section 6.2)
  • Added dispute resolution protocol with claim and evidence submission(Spec Section 6.6)
  • Added structured shipping and fulfillment tracking(Spec Section 6.5)
  • Added support for subscription and recurring purchase intents(Spec Section 5.6)
  • Added protocol capability negotiation in discovery manifest(Spec Section 2.2)

v1.5

December 2025

Query Improvements & Developer Experience

ACP v1.5 is a minor release focused on improving the query layer based on feedback from the first wave of agent integrations. Early adopters reported that natural language queries often lacked enough structured context for storefronts to return relevant results. This release introduces query context hints, faceted filtering, and cursor-based pagination to address those gaps. It also adds SDK improvements that reduce boilerplate for common integration patterns.

Migration notes

v1.5 is fully backward compatible with v1.0. No migration steps are required. New features are opt-in: agents can include the new context and facets fields in queries, and storefronts can return facet metadata in responses. Existing v1.0 clients will continue to work without modification.

Changes

  • Added cursor-based pagination to replace offset/limit pagination for large result sets(Spec Section 4.2)
  • Added faceted filtering with dynamic facet metadata in query responses(Spec Section 4.4)
  • Added query context hints for budget, urgency, and use-case signals(Spec Section 4.1)
  • Added semantic search fallback for queries that do not match structured filters(Spec Section 4.5)
  • Added batch query endpoint for issuing multiple queries in a single request(Spec Section 4.6)
  • Added product comparison endpoint for side-by-side attribute comparison(Spec Section 4.7)
  • Added geo-awareness fields for location-sensitive pricing and availability(Spec Section 4.1)
  • Improved SDK retry logic with exponential backoff and jitter(SDK Docs)
  • Improved rate limit response headers with retry-after guidance(Spec Section 7.3)
  • Added OpenAPI 3.1 specification file for all v1.x endpoints(Spec Appendix A)
  • Added ACP Validator CLI for automated compliance testing(Tools Docs)
  • Added request ID header (X-ACP-Request-Id) for distributed tracing(Spec Section 7.4)

v1.0

September 2025

Initial Release

The inaugural release of the Agent Commerce Protocol. ACP v1.0 establishes the foundational primitives for AI agent-to-brand commerce: a discovery mechanism for agents to find storefronts, a query protocol for searching product catalogs, and a structured product card format for machine-readable product representation. This version focuses on the read path - enabling agents to discover brands and search their catalogs. Write operations (negotiation, transactions) are deferred to future versions based on real-world adoption feedback.

Migration notes

This is the initial release. There is no prior version to migrate from. Brands implementing ACP for the first time should start with the discovery manifest and query endpoint. The recommended implementation order is: (1) Publish /.well-known/acp.json, (2) Implement the query endpoint with search intent, (3) Add recommend and compare intents, (4) Implement rate limiting.

Changes

  • Introduced the Agent Commerce Protocol specification(Spec Section 1.1)
  • Added query protocol with search, recommend, compare, and detail intents(Spec Section 4.1)
  • Added AgentProductCard format for structured product representation(Spec Section 4.3)
  • Added discovery protocol with .well-known/acp.json(Spec Section 2.1)
  • Added API key authentication with public and secret key types(Spec Section 3.1)
  • Added rate limiting with tiered access (Free: 100 req/min, Growth: 1000 req/min, Enterprise: custom)(Spec Section 7.1)
  • Added standard error response format with error codes and human-readable messages(Spec Section 8.1)
  • Added semantic versioning and backward compatibility rules(Spec Section 1.3)
  • Added product attribute schema with support for custom typed attributes(Spec Section 4.3)
  • Added review summary format with average rating, count, and highlight extraction(Spec Section 4.3)
  • Added CORS and preflight configuration guidance for browser-based agents(Spec Section 7.2)
  • Published reference implementation for Node.js storefronts(GitHub Repository)