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.
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, orFailure) 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 Paymentstate 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
shippingAddressandbillingAddressof the Cart (countryandstatevalues).
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.
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. |