Checkout

The Checkout component implements the Universal Commerce Protocol (UCP) required by Google and manages the end-to-end checkout lifecycle.

Core capabilities

Authentication and authorization: implements UCP to authenticate requests originating from Google and to scope operations to the appropriate Store context. The component ensures that all checkout sessions are securely linked to a valid Google session token and Store.

Cart management: creates and maintains Carts within the assigned Store context. The module enforces Store isolation to ensure that Carts and Orders cannot be accessed or modified across different Stores. Cart creation includes dynamic validation of products, inventory, and pricing. Agents can also build a Cart before checkout starts by using the Cart capability.

Payment authorization handling: supports the payment authorization flow expected by Google as part of the UCP sequence.

When the Cart is ready for payment, the module does the following inside your commercetools Project:

Creates a Payment resource linked to the Cart.
Creates an Authorization Transaction on that Payment and performs authorization with a Payment Service Provider (PSP).
Updates the Authorization TransactionState (Pending, Success, or Failure) based on the PSP response.
Upon successful authorization, the corresponding Order resource is created and the status is synchronized back to Google.

Session state handling: provides real-time status updates to Google on the order fulfillment progress through webhook callbacks. This ensures a consistent state between the commercetools Order lifecycle and the Google checkout session.

Functional considerations

Inventory management

The module validates stock availability for each Product based on the inventory supply Channel assigned to the Store. During checkout, the module checks real-time stock levels before proceeding to payment.

If the requested quantity exceeds the available stock:

The module returns an out-of-stock error to Google.
The checkout session remains in a Not Ready for Payment state until availability is restored.

Synchronize inventory data with commercetools to prevent checkout interruptions due to stock issues.

Tax configuration

By default, the module uses the Tax Categories and Tax Rates defined in your commercetools Project to calculate taxes during Cart creation.

Tax calculation is automatically applied per line item based on:

The Product's assigned Tax Category.
The shippingAddress and billingAddress of the Cart (country and state values).

To integrate a third-party tax engine, use one of the following options:

Connect template: deploy the Connect Tax integration template and adapt it to your tax provider.
Prebuilt application: install an existing tax integration from the Connect Marketplace.

Shipping configuration

Shipping Methods must be defined in your commercetools Project, including:

Carrier information.
Expected delivery days.
Supported Zones and currencies.

The Shipping Method data is then surfaced to Google through the checkout session.

Configure Shipping Methods in Merchant Center, under Project settings > Shipping methods, or through the API. Custom carrier data fields, such as a tracking provider or a service-level agreement, are required. Add them as Custom Field values after module installation.

Shipping Method Custom Fields

The Google Gemini modules use Custom Fields on Shipping Methods to communicate delivery estimates and carrier information to the AI platform.

For each Shipping Method, the name and description are mandatory.

Field	Type	Description
`earliestDeliveryInDays`	Number	Minimum estimated transit time in days.
`latestDeliveryInDays`	Number	Maximum estimated transit time in days.
`carrier`	String	Shipping provider name (for example: Acme Shipping).

Shipping Method Custom Fields are not required if you use external shipping methods. In that case, delivery estimates and carrier information are provided by the external shipping service.

Order and fulfillment state management

The module monitors Order and shipment state transitions within your commercetools Project to keep the Google order view consistent. As Orders progress through the fulfillment workflow, the module propagates state changes back to Google through webhook callbacks. For example, an Order state can change from Open to Confirmed to Complete or Cancelled. Keeping Order and shipment states accurate is essential for maintaining a consistent post-purchase experience.

To automatically update Order states from your fulfillment provider, use one of the following options:

Connect template: deploy the Connect Fulfillment Integration Template and adapt it to your fulfillment provider.
Prebuilt application: install an existing fulfillment application from the Connect Marketplace.

Order view URL

After an Order is created, the module composes the order view URL that Google uses to link shoppers to your order details page. The source of this URL depends on your configuration.

AI Hub webhook response: If you configure an AI Hub webhook as the checkout extension (CTP_CHECKOUT_EXTENSION_URL), the module uses the complete orderUrl returned in the webhook response. This URL can include an external order number and any required query parameters, such as a customer token (for example, https://example.com/orders/123456789?token=customer_abcde). Use this option when order details are managed in an external Order Management System (OMS) and the URL must be composed from external identifiers.
Order URL template fallback: If the webhook response doesn't include an orderUrl, the module falls back to the orderUrlTemplate defined in the storefront field or Store Custom Field. The orderId placeholder in the template is replaced by the futureOrderNumber from the webhook payload. Additional query parameters are not added in this mode.
No webhook configured: If no AI Hub webhook is configured, the module uses the commercetools Order ID to compose the URL from the orderUrlTemplate defined in the storefront field or Store Custom Field.

UCP error mapping

UCP errors are mapped to clear, actionable messages to help shoppers understand what went wrong during checkout. Instead of displaying a generic error, the message explains the issue and, where possible, what the shopper can do to resolve it.

The following table lists the UCP error codes, their severity, and the message returned to the shopper.

Error code	Severity	Message
`out_of_stock`	Error	Item is not available.
`item_unavailable`	Error	Product `{sku}` is unavailable.
`item_ineligible`	Error	Item is not available for purchase.
`quantity_invalid_limit_exceeded`	Error	The requested quantity exceeds the maximum allowed. Please reduce the quantity and try again.
`quantity_invalid_minimum_not_met`	Error	The requested quantity is below the minimum required. Please increase the quantity and try again.
`missing_buyer_info`	Error	Some required buyer information is missing. Please provide the missing details.
`address_undeliverable`	Error	Delivery is not possible to this address. Please check the address or choose a different one.
`missing_fulfillment_info`	Error	Required delivery information is missing. Please provide it.
`eligibility_invalid`	Error	This action isn't available for the provided details.
`identity_required`	Error	User identity is required to access this resource.
`insufficient_scope`	Error	You don't have permission to complete this action.
`payment_failed`	Error	Your payment failed due to a technical issue during processing. Please try again or use a different payment method.
`payment_ineligible`	Error	The selected payment method is not accepted. Please choose a different payment method and try again.
`discount_code_invalid`	Warning	The discount code is not valid. Please check the code.
`discount_code_expired`	Warning	The discount code has expired.
`discount_code_already_applied`	Warning	This discount code has reached its usage limit and is no longer available.
`discount_code_combination_disallowed`	Warning	The discount code cannot be combined with other offers.

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

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

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

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

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

Shipping Method Custom Fields.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Order and fulfillment state management.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

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