Checkout extensibility

Extend AI Hub Checkout with API Extensions and webhooks to add custom validation, shipping logic, and fraud checks to your agentic commerce flows.

AI Hub Checkout supports extensibility through two mechanisms: API Extensions and the AI Hub webhook. External systems can participate in checkout session processing to provide dynamic validation and enrichment. Examples include tax resolution, fraud detection, and real-time inventory checks.

This extensibility model applies only to the Google AI Hub checkout module. It doesn't apply to the Stripe ACS module, which uses its own order import flow, or to the OpenAI module.

Extensibility model

commercetools provides two extensibility mechanisms that you can use independently or together.

API Extensions

API Extensions are the primary and recommended mechanism for implementing extensibility across commercetools. They are triggered directly within commercetools APIs and work across all sales channels. This makes them the right choice for logic that applies to your entire commerce setup.

API Extensions are:

triggered within commercetools APIs on Carts and Orders
channel-agnostic, working across all sales channels (storefronts, APIs, integrations)
suitable for synchronous validation and enrichment

Typical use cases include:

tax calculation
external pricing
validation logic
Custom Field enrichment
compliance rules

Conditional triggers

API Extensions support conditional triggers, which let you control when an extension runs. You can use predicates to filter execution based on the Store associated with a Cart, allowing you to:

run an extension only for agentic Stores
apply different logic for standard storefronts and AI-driven checkout flows

For example, a predicate like store(key="my-agentic-store") restricts execution to Carts in a specific agentic Store.

For more information about configuring API Extensions and conditional triggers, see API Extensions and the Implement an API Extension tutorial.

AI Hub webhook

AI Hub provides an optional webhook mechanism specifically for checkout extensibility in AI-driven or agentic experiences. Unlike API Extensions, this webhook is scoped to the AI Hub checkout lifecycle and is designed for channel-specific orchestration. You configure the webhook through the API extension settings in the Merchant Center.

The AI Hub webhook is:

invoked during checkout lifecycle actions (create, update, read, complete)
designed for agentic or channel-specific orchestration
focused on real-time checkout decision-making

Typical use cases include:

inventory checks that return errors specific to each agentic channel (for example, Google)
delivery or shipping promise creation and stock reservation in a backend system for a specific channel
fraud checks specific to an agentic channel based on request headers

When to use which

Scenario	Recommended approach
Channel-agnostic logic (tax, pricing, validation)	API Extensions
Core commerce logic reused across all channels	API Extensions
Channel-specific variation of shared logic	API Extensions with conditional triggers
Agentic or AI-specific checkout orchestration	AI Hub webhook
Inventory checks with channel-specific error handling	AI Hub webhook
Stock reservation or delivery promise for a specific channel	AI Hub webhook
Final checkout validation in AI-driven flows	AI Hub webhook

How they work together

When both mechanisms are active, they execute sequentially:

The agent triggers a checkout session action (Create or Update).
commercetools creates or updates the Cart based on the request.
API Extensions are triggered based on configured conditions and they run first to handle core Cart logic, such as taxes or pricing.
If the Cart operation succeeds, AI Hub invokes the webhook, if configured, with the corresponding action (Create, Update, Read, or Complete). The webhook handles external business logic that the Cart resource can't do, such as fraud checks or real-time inventory validation.
The external system evaluates the request.
The webhook returns a response with validation results.
AI Hub proceeds or blocks checkout based on the response.

Because execution is sequential, the two mechanisms cannot return conflicting results:

If an API Extension blocks the Cart update, the process stops immediately and the webhook is never invoked. The agent receives an error and can retry.
If the API Extension succeeds but the webhook returns a Failure response, the Cart update is preserved, but the checkout session is flagged as incomplete. The agent is blocked from completing checkout until the issue is resolved (for example, by adjusting quantities or changing the shipping address).
If the webhook itself fails due to a server error or timeout, the system proceeds with checkout rather than blocking the shopper due to a technical issue.

Multiple API Extensions can be configured at the Project level and chain together during Cart processing. This is standard commercetools behavior. Each agentic channel has a single webhook endpoint. This endpoint handles all checkout lifecycle actions (Create, Update, Read, Complete). If your implementation needs to address multiple concerns (fraud, inventory), route internally within your endpoint. Different agentic channels can each have their own webhook configuration.

AI Hub webhook reference

To use the AI Hub webhook, you build and host an HTTP endpoint that receives requests from AI Hub and returns structured responses. AI Hub acts as the caller: it sends an HTTP POST request to your endpoint at each checkout lifecycle stage. Your endpoint processes the request and returns a JSON response that tells AI Hub whether to proceed or block the checkout.

The following sections describe the contract between AI Hub and your endpoint, including configuration, request format, and expected response structure.

Configuration

Configure the webhook in the Merchant Center under the Checkout tab of the agentic channel. The following fields are available:

Field	Description
Extension URL	The HTTPS URL of your webhook endpoint
Extension secret	The full value sent in the Authorization header of webhook requests, including the authentication scheme. The system injects this value as-is, without adding or removing a scheme prefix. Provide the complete header value, such as `Bearer my-token` or `Basic <credentials>`. The value must start with a valid scheme prefix, such as `Bearer` or `Basic`.
Extension timeout (ms)	Maximum time in milliseconds to wait for a response. Defaults to 10000 ms (10 seconds)

For more details, see the API extension settings on the Manage agentic channels page.

Authentication

AI Hub injects the Extension secret value directly into the Authorization header of every webhook request. The system does not add a scheme prefix or perform any transformation, so the value you configure is sent exactly as written.

Authorization headertext
Authorization: <extension-secret-value>

Provide the complete header value, including the authentication scheme. For example, to make the header read Bearer my-token, configure the Extension secret as Bearer my-token. commercetools validates that the configured value starts with a valid scheme prefix, such as Bearer or Basic.

Your endpoint must validate this value to confirm the request originates from AI Hub. Reject requests with missing or invalid authorization.

HTTPS is required for production endpoints. IP allowlisting and request signing are not supported.

Actions

At each checkout lifecycle stage, AI Hub sends a POST request to your endpoint. The request body contains an action field that identifies the stage, and a resource field with the Cart ID. AI Hub constructs this payload automatically based on the checkout event.

The following example shows the structure of a request body:

Structure of a request bodyjson
{
  "action": "Create",
  "resource": {
    "typeId": "cart",
    "id": "<cart-id>"
  }
}

Action types

Action	Description
`Create`	Checkout session initialized
`Update`	Cart or session updated
`Read`	Current checkout state retrieved
`Complete`	Checkout completion requested

Create

Invoked when a checkout session is initialized. Use this action to set up context for the checkout flow.

Typical integrations:

checkout context setup
external system initialization

Update

Invoked when the Cart or session is updated. Use this action to revalidate Cart changes or sync with external systems.

Typical integrations:

inventory validation (soft check)
external system synchronization

Read

Invoked when an agent retrieves the current state of the checkout. Use this action to return the latest validation state without modifying the Cart.

Typical integrations:

checkout state synchronization

Complete

Invoked as the final validation step before Order creation. Use this action for hard checks that determine whether checkout can proceed.

Typical integrations:

fraud detection
inventory validation (hard check)
business rule enforcement

Request format

This section describes the exact format of the HTTP request that AI Hub sends to your endpoint. Use this as a reference when building your service.

Headers

Header	Description
`Authorization`	Configured Extension secret, sent as-is
`Content-Type`	`application/json`

Body

The request body contains only the action identifier and a Cart reference. No additional Cart data, customer information, or channel details are included in the payload.

To access Cart contents for validation, your endpoint must retrieve the Cart from the commercetools API using the provided id.

Response format

Your endpoint must return a JSON response that tells AI Hub the outcome of the validation. The response can include a result type and validation errors.

Structure

Structure of a response bodyjson
{
  "result": {
    "type": "Success",
    "errors": []
  }
}

Result object

Field	Type	Required	Description
`type`	String	Yes	`Success` or `Failure`. Indicates whether the checkout can proceed.
`errors`	Array	Conditional	Validation errors that block checkout. Required when `type` is `Failure`.

Success response

A Success response indicates that checkout can proceed:

Response structure for a successful requestjson
{
  "result": {
    "type": "Success"
  }
}

Failure response

A Failure response blocks checkout. At least one error must be included:

Response structure for a failed requestjson
{
  "result": {
    "type": "Failure",
    "errors": [
      {
        "code": "VALIDATION_ERROR",
        "message": "Checkout failed"
      }
    ]
  }
}

When checkout is blocked by a Failure response, the Cart is preserved. The shopper (or agent) receives the error messages from the response and can adjust the Cart — for example, by changing quantities or updating the shipping address. Each adjustment triggers a new webhook request, allowing re-validation until checkout succeeds.

Errors

Structure

Example of a response that contains an errorjson
{
  "code": "VALIDATION_ERROR",
  "message": "Item is out of stock"
}

Field	Type	Description
`code`	String	Error code identifying the type of error.
`message`	String	Human-readable description of the error.

Error codes are custom strings defined by the implementer. You can use any value, but since error behavior depends on the underlying agent protocol, aligning with platform-specific codes improves interoperability. For Google Universal Commerce Protocol (UCP) channels, see the Google UCP error code reference.

A Failure response blocks checkout. You can return multiple errors in a single response. Only hard errors are supported — warnings are not currently available. Errors should be consistent and deterministic to ensure predictable checkout behavior.

HTTP status codes

Status	Description
`200`	Request processed. Business logic outcome is in the response body.
`4xx`	Client error.
`5xx`	Server error.

Return business logic errors (validation failures, fraud checks) in the response body with "type": "Failure", not through HTTP status codes.

Timeouts

The default timeout is 10 seconds (10000 ms). You can override this value in the Merchant Center configuration.

If the webhook request exceeds the configured timeout, returns an HTTP 5xx, or cannot be completed because of a network error, AI Hub ignores the webhook result and proceeds with checkout. This is a fail-open behavior that prioritizes checkout completion over blocking the shopper due to a technical issue with the webhook endpoint.

In these technical failure cases, no webhook-provided changes are applied to the Cart/session. The Cart/session remains in the state it was in before the webhook call, and checkout continues without any validation results or other enrichments that would have come from that webhook response.

Idempotency and retries

AI Hub only applies webhook business logic from a successful HTTP 200 response. A timeout, HTTP 5xx, or network error does not roll back the shopper's checkout session; instead, the webhook result is discarded and the Cart/session remains unchanged by that webhook attempt.

Because failed webhook attempts do not apply partial webhook-driven changes, a later retry is effectively a fresh attempt against the current Cart/session state. AI Hub does not implement idempotency headers or automatic retries on its end.

This fail-open behavior applies only to technical failures. A successful 200 response with "type": "Failure" is a deliberate business decision and still blocks checkout, as described in Failure response.

Extensibility model.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

API Extensions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Conditional triggers.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AI Hub webhook.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

When to use which.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

How they work together.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

AI Hub webhook reference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Configuration.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Authentication.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Actions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Action types.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Read.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Complete.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Request format.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Headers.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Body.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Response format.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Structure.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Result object.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Success response.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Failure response.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Errors.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Structure.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

HTTP status codes.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Timeouts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Idempotency and retries.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Extensibility model

API Extensions

Conditional triggers

AI Hub webhook

When to use which

How they work together

AI Hub webhook reference

Configuration

Authentication

Actions

Action types

Create

Update

Read

Complete

Request format

Headers

Body

Response format

Structure

Result object

Success response

Failure response

Errors

Structure

HTTP status codes

Timeouts

Idempotency and retries