Changelog

2026-01-30

This release introduces four major features that enhance ACP's capability discovery, payment handling, and extensibility.

Capability Negotiation

Enables agents and sellers to discover and negotiate supported features during checkout. Agents declare their capabilities in requests; sellers return the intersection of supported features in responses.

Key Features:

  • Single capabilities object used in both requests and responses
  • Intersection semantics: seller computes mutual compatibility
  • Early incompatibility detection before payment authorization
  • Required field for predictable behavior

Payment Handlers Framework (Breaking Change)

Replaces simple payment method identifiers with structured handlers.

What Changed:

  1. Declaration:

    • Old: payment_provider.supported_payment_methods
    • New: capabilities.payment.handlers

  2. Handler Structure: Each handler includes ID, name, version, spec URL, delegation requirements, PCI compliance info, PSP identification, and handler-specific configuration.

  3. Payment Data:

    • Old: { "token": "spt_123", "provider": "stripe" }
    • New: { "handler_id": "card_tokenized", "instrument": { "type": "card", "credential": { "type": "spt", "token": "spt_123" } } }

Benefits:

  • Standardized handler discovery
  • Explicit security requirements
  • PSP identification for credential vaulting
  • Handler-specific configuration

Extensions Framework

Standardized mechanism for optional, composable capabilities. Extensions are declared in capabilities.extensions[] and integrate with capability negotiation.

Lifecycle: Discovery → Negotiation → Usage

Discount Extension

Rich discount code support (first ACP extension).

Features:

  • Discount code input via discounts.codes[]
  • Applied discount details with line-item allocations
  • Automatic discounts (no code required)
  • Rejected codes via messages[] with error codes

Migration: Optional extension. No changes required for existing implementations.

Version Compatibility

  • API Version: 2026-01-30
  • Previous version 2025-12-12 deprecated
  • Payment Handlers: Breaking change - requires updates
  • Extensions/Discount: Optional - adopt incrementally

2025-12-12

This release introduces several breaking changes based on learnings from early implementations.

Breaking Changes

Renamed fulfillment_address to fulfillment_details

Impact: Both requests (Create/Update) and all responses

Change:

  • Old structure: Flat fulfillment_address object with address fields only
  • New structure: Nested fulfillment_details object with optional name, phone_number, email, and nested address object

Replaced fulfillment_option_id with selected_fulfillment_options

Impact: Update requests and all responses

Change:

  • Old: Single string fulfillment_option_id field
  • New: Array selected_fulfillment_options[] with type-specific nested structures supporting multiple selections and item-level mappings

Rationale: Supports selecting different fulfillment options for different items in the same cart.

Made subtotal and tax optional in FulfillmentOption

Impact: Both FulfillmentOptionShipping and FulfillmentOptionDigital schemas

Change:

  • Old: subtotal and tax were required fields
  • New: subtotal and tax are optional; only total is required

Rationale: Not all sellers provide tax/subtotal breakdown for fulfillment options. Only the total amount is essential.

Additional Changes

  • Bug Fix: Fixed fulfillment amount types from strings to integers in OpenAPI spec
  • Added: Optional description field to the Total type
  • Added: return_policy link type
  • Added: LineItem display fields (name, description, images, unit_amount, etc.)
  • Added: Intent Traces for structured cancellation context
  • Added: Affiliate Attribution extension support

Version Compatibility

  • Clients MUST send API-Version: 2025-12-12 header
  • Previous version 2025-09-29 is deprecated
  • Breaking changes require client updates

2025-09-29

  • Initial release of the Agentic Commerce Protocol specification.
  • Published the first version of:
    • Agentic Checkout specification and OpenAPI schema
    • Delegate Payment specification and OpenAPI schema
  • Added example JSON files for both agentic checkout and delegate payment flows.
  • Documentation and RFCs for both protocols included.
Documentation | Agentic Commerce Protocol