Checkout

AI Hub Add-On
Ask about this Page
Copy for LLM
View as Markdown

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:

  1. Creates a Payment resource linked to the Cart.
  2. Creates an Authorization Transaction on that Payment and performs authorization with a Payment Service Provider (PSP).
  3. Updates the Authorization TransactionState (Pending, Success, or Failure) based on the PSP response.
  4. 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:

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 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.

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: