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.

v3.0

CurrentAugust 2026

Escrow, Financing & Insurance Removed

ACP v3.0 removes the escrow, financing, and insurance concepts introduced in v2.0. Cresva never holds, receives, routes, finances, insures, or pays out funds; it facilitates discovery, negotiation, and order handoff, and payment happens directly between the buyer and the merchant on the merchant's own rails. v2.0's escrow endpoints and states described the platform as a fund custodian, which conflated a release-timing status with an actual holding of money the platform never had a license to hold. This release corrects that: the transaction lifecycle no longer has an ESCROWED state, and disputes are recorded, not adjudicated or settled by Cresva.

Breaking changes

  • POST /transactions/{id}/escrow/release and POST /transactions/{id}/escrow/dispute are removed. Use POST /transactions/{id}/confirmation-window/confirm to close a confirmation window early, or POST /transactions/{id}/confirmation-window/dispute to record a dispute; there is no release endpoint because there are no platform-held funds to release. See Spec Section 6, Transactions and Confirmation Window.
  • The escrow, escrowed, and disputed-with-escrow states are removed from the transaction state machine, replaced by an optional, separate confirmation-window status (pending_confirmation / confirmed / disputed) that is STATUS ONLY and never gates any fund movement. A transaction's own status still moves pending → confirmed → completed, or into disputed → resolved. See Spec Section 6.1.
  • For the avoidance of doubt: Cresva does not underwrite financing or insure agent commerce revenue. Nothing in the public ACP spec ever defined financing or insurance endpoints; this is stated here because v2.0's escrow language could be read as implying a broader custodial or financial-services role than Cresva has ever had.
  • escrow.created, escrow.released, and escrow.disputed webhook events are removed, replaced by confirmation_window.opened, confirmation_window.confirmed, and confirmation_window.disputed. transaction.disputed and transaction.resolved still cover the transaction's own dispute status. See Spec Section 10.1.

Migration notes

Any integration calling the escrow/release or escrow/dispute endpoints should switch to POST /transactions/{id}/confirmation-window/confirm or POST /transactions/{id}/confirmation-window/dispute; there is no replacement for escrow/release because Cresva never held the funds it referenced, and closing the window early is a status change, not a fund release. Any integration relying on the financing or insurance endpoints should treat them as permanently removed, not deprecated.

Changes

  • Added POST /transactions/{id}/confirmation-window/confirm and POST /transactions/{id}/confirmation-window/dispute to manage a transaction's optional confirmation window without implying Cresva holds or freezes funds(Spec Section 6)
  • Added an explicit statement to the Transactions section: Cresva never holds funds; payment happens between buyer and merchant on the merchant's rails(Spec Section 6)
  • Removed escrow, financing, and insurance from the spec, the SDKs, and this site(Spec Section 6)

v2.0

March 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, 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. (This entry originally described a v2.0 escrow feature as holding funds; as of v3.0, that description is corrected. See the v3.0 entry above.)

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 a release-timing status for conditional purchases (removed in v3.0; see above)(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)