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.

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.

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;}