# 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](/api/projects/api-extensions.md) 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](/api/projects/api-extensions.md) 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](/api/projects/api-extensions.md#conditional-triggers), which let you control when an extension runs. You can use [predicates](/api/predicates/query.md#use-predicates-in-conditional-api-extensions) 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](/api/projects/api-extensions.md) and the [Implement an API Extension](/tutorials/extensions.md) 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](/agentic-commerce/ai-hub/agentic-channels.md#google-checkout-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:

1. The agent triggers a checkout session action (`Create` or `Update`).
2. commercetools creates or updates the Cart based on the request.
3. API Extensions are triggered based on configured conditions and they run first to handle core Cart logic, such as taxes or pricing.
4. 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.
5. The external system evaluates the request.
6. The webhook returns a response with validation results.
7. 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](/agentic-commerce/ai-hub/agentic-channels.md#google-checkout-api-extension-settings) 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.

```text title="Authorization header"
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:

```json title="Structure of a request body"
{
  "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

```json title="Structure of a response body"
{
  "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:

```json title="Response structure for a successful request"
{
  "result": {
    "type": "Success"
  }
}
```

#### Failure response

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

```json title="Response structure for a failed request"
{
  "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

```json title="Example of a response that contains an error"
{
  "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](https://developers.google.com/merchant/ucp/guides/checkout/errorcode#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](/agentic-commerce/ai-hub/checkout-extensibility.md#failure-response).

## Related pages

- [Area overview page with navigation](/agentic-commerce.md)
- [Previous page: JSONata data mapping](/agentic-commerce/ai-hub/jsonata-data-mapping.md)