Extensions

The ACP Extensions Framework lets sellers add optional capabilities to checkout (e.g., discount codes, loyalty, future features) in a standardized way. Extensions are advertised and negotiated through capability negotiation, and they add well-defined fields to the core checkout schema so agents can discover and use them without changing the base protocol.

Why extensions?

The core Agentic Checkout API is designed to stay stable. New features (discounts, loyalty programs, subscriptions, etc.) should be optional and composable so that:

• Sellers can adopt only the extensions they need.
• Agents can ignore extensions they don’t support and still complete checkouts.
• The spec can evolve with new extensions without breaking existing implementations.

Extensions integrate with the same capabilities object used for capability negotiation: agents declare which extensions they understand in the request, and sellers return which extensions are active for that session in the response.

How extensions are negotiated

Extension negotiation follows the same request/response pattern as other capabilities:

1. Agent request — The agent sends capabilities.extensions as an array of extension identifiers (e.g. ["discount"]) to indicate which extensions it understands.
2. Seller response — The seller includes capabilities.extensions as an array of extension declaration objects. Each declaration describes one extension that is active for this session and which schema fields it adds.

The extensions array in capabilities is optional. Sellers that don’t support any extensions can omit it; agents must handle responses with or without extensions. When an agent declares supported extensions, sellers should utilize those extensions when they are available.

Extension declaration (response)

When a seller supports an extension, each active extension is described by an object in capabilities.extensions:

Extension identifiers

• Core ACP extensions use simple lowercase names (e.g. discount)
• Third-party extensions should use reverse-domain naming to avoid collisions (e.g. com.merchant.loyalty-program).
• An optional version suffix is allowed (e.g. discount@2026-01-27). If omitted, the latest stable version is assumed.

The extends field

The extends array uses JSONPath expressions to say exactly which parts of the checkout schema the extension adds. Each entry has the form:

$.<SchemaName>.<fieldName>

Examples:

This gives agents and tooling a machine-readable way to know which request/response fields come from which extension, and supports schema composition and validation.

Schema and spec URLs

• schema — URL to a JSON Schema that defines the structure of the fields added by the extension. Useful for validation, SDK generation, and documentation. Recommended for third-party extensions.
• spec — URL to a human-readable specification for the extension.

Core ACP extensions (like discount) may omit these URLs because their schemas are part of the ACP spec; third-party extensions are encouraged to provide both.

Example: discount extension

The Discount Extension is the first extension defined in ACP. It adds discount code support with rich applied discounts, allocation details, and rejection messaging.

When the discount extension is active:

• Create/update requests can include a discounts object with a codes array (discount codes to apply).
• Checkout session response includes a discounts object with applied (successfully applied discounts) and optionally rejected (codes that could not be applied, with reasons).

The seller declares it in the response like this:

{
  "capabilities": {
    "payment": { "handlers": [...] },
    "extensions": [
      {
        "name": "discount",
        "extends": [
          "$.CheckoutSessionCreateRequest.discounts",
          "$.CheckoutSessionUpdateRequest.discounts",
          "$.CheckoutSession.discounts"
        ],
        "schema": "https://example.com/extensions/discount/schema.json",
        "spec": "https://example.com/extensions/discount/spec"
      }
    ]
  }
}

The agent can then send discount codes in create/update requests and read discounts.applied and discounts.rejected from the session response. Full field definitions for the discount extension are in the checkout and discount schemas in the spec.

Composition rules

Extensions are designed to compose safely with the core schema:

• Extensions MUST NOT modify existing required fields or change the semantics of existing fields.
• Extensions MAY add new optional fields to the checkout object.
• Extensions MAY add new values to the messages[].code enum for extension-specific errors (e.g. discount rejection reasons).

Extension-specific fields are ignored by clients that don’t support that extension; the rest of the checkout flow continues to work.

Extension lifecycle

Extensions can have a lifecycle status (used in documentation and registries): draft, experimental, stable, deprecated, retired. Versioning uses the same date format as the core protocol (e.g. discount@2026-01-27).

Security and validation

• Extensions MUST NOT introduce new authentication or authorization that bypasses the core protocol.
• Extension-specific data follows the same PCI/PII handling rules as core checkout data.
• Sellers MUST validate extension-specific inputs with the same rigor as core fields.

Summary

Next steps