# Google module overview

Enable agentic commerce on Google surfaces by connecting your commercetools data to Google's Universal Commerce Protocol.

The Google module for AI Hub lets you participate in agentic commerce on Google surfaces, including Gemini and Google Search. Through the [Universal Commerce Protocol](https://ucp.dev/specification/overview) (UCP), your product catalog, pricing, and inventory are discoverable and purchasable directly within Google's AI experiences.

The module has two components to synchronize your commerce data with Google:

- **Product Sync**: synchronizes your product catalog with Google Merchant Center using supplemental data sources.
- **Checkout**: handles cart and checkout flows through UCP, including Google Pay authorization and order creation.

## How it works

The Google module operates as a bridge between your Project and Google's commerce infrastructure:

1. Your product data is synchronized from commercetools to Google Merchant Center through supplemental feeds. Google uses this data to display your products in AI-powered shopping experiences.
2. When a buyer initiates a purchase on a Google surface, Google sends a checkout request to your UCP endpoint (hosted by the Checkout component).
3. The Checkout component creates an anonymous Cart in commercetools, calculates pricing and taxes, and returns the session details to Google.
4. Google Pay handles payment authorization. After successful authorization, the Checkout component creates an Order in commercetools.
5. Post-purchase order lifecycle events (processing, shipped, canceled) are sent to Google through webhooks.

## Functional scope

The Google module supports the following capabilities:

- Product catalog distribution to Google Merchant Center through supplemental feeds
- Real-time pricing and availability synchronization
- Anonymous cart and checkout through UCP
- Native checkout with Google Pay
- Order creation in commercetools
- Post-purchase order lifecycle events through UCP webhooks

## Prerequisites

Before configuring the Google module, ensure the following requirements are met.

### Google Merchant Center requirements

- An active Google Merchant Center account in good standing with approved products and no critical product-level issues.
- A verified online store URL.
- You must be [registered as a Google Merchant Center developer](https://developers.google.com/merchant/api/guides/quickstart/registration).
- A primary data source configured for your product feed with products uploaded and available for free listings.
- A supplemental data source created and linked to your primary data source. The advanced data source management add-on must be enabled. An attribute rule using **Take latest** must be created to allow price and availability to be overwritten by the supplemental data source.
- Return policies configured. For Advanced Accounts (multi-brand setups), return policies must be defined separately for each sub-account.
- Customer support information and business profile published and up-to-date.
- A service account configured to access the Merchant Account.

If you meet these requirements, you must then express your interest through the [UCP Integration Interest Form](https://support.google.com/merchants/contact/ucp_integration_interest).

### Google Cloud Project requirements

- Google Merchant APIs enabled.
- A service account set up and linked to the Merchant Account.

### commercetools requirements

- An active Project.
- An API Client with appropriate scopes for managing Products, Carts, Orders, and Inventory.
- A [Store](/api/projects/stores.md) configured for the storefront participating in native checkout.
  - The Store must have a [Custom Field](/api/projects/custom-fields.md) of type [CustomFieldStringType](/urn?urn=ctp%3Aapi%3Atype%3ACustomFieldStringType) called `storeUrl` containing your storefront URL. This is required for UCP Checkout. For the product feed, this is the default source for the `link` field but can be replaced by modifying the template.
- [Product Selections](/api/projects/product-selections.md) assigned to the Store to define which products are eligible for Google surfaces.
- [Inventory Entries](/api/projects/inventory.md) with supply Channels configured if you use channel-scoped availability.
- [Subscriptions](/api/projects/subscriptions.md) for product and inventory change events.

The UCP Checkout component requires Store Custom Fields (such as `storeUrl`) and cannot be configured without them. For the product feed, Store Custom Fields are optional. The default template uses them, but you can pull the values from another source or hardcode them.

Consult the data mapping documentation for details on how your commercetools data maps to Google Merchant Center attributes and UCP requirements.

### Payment requirements

Your payment service provider (PSP) must support Google Pay token processing. Compatible PSPs include Adyen, Stripe, and other providers that can process Google Pay encrypted payment tokens.

## Configuration

The Google module requires the following configuration:

### Product Sync component

| Configuration field | Description |
| --- | --- |
| Merchant Center Account ID | Your Google Merchant Center account identifier. |
| Primary data source ID | The identifier of your primary product data source in Google Merchant Center. |
| Supplemental data source ID | The identifier of the supplemental data source linked to your primary data source. |
| Service Account Key (JSON) | The JSON key file for the Google Cloud service account. |
| API Client credentials | commercetools API Client ID and secret. |
| Store Key | The key of the Store scoping the product catalog. |
| Locale | The locale used for extracting localized product data. |
| Price country | The country used for price selection. |
| Price currency | The currency used for price selection. |

### Checkout component

| Configuration field | Description |
| --- | --- |
| API Client credentials | commercetools API Client ID and secret. |
| Store Key | The key of the Store scoping the checkout flow. |
| Distribution Channel Key | The key of the Channel used for product distribution. |
| Supply Channel Key | The key of the Channel used for inventory supply. |
| Inventory Mode | The inventory mode for line items in the Cart. |

## Data synchronization

The Google module uses two synchronization strategies to keep your product data current in Google Merchant Center.

### Real-time synchronization (event-driven)

Price and availability updates are synchronized in near real-time using commercetools [Subscriptions](/api/projects/subscriptions.md). When product prices or inventory levels change, the component processes the event and updates the supplemental data source in Google Merchant Center.

Supported events include:

- `ProductPriceChanged`
- `ProductPriceDiscountsSet`
- `InventoryEntryCreated`
- `InventoryEntryDeleted`
- `InventoryEntryQuantitySet`
- `ProductPublished`
- `OrderCreated`

Updates are sent in batch requests to the Google Merchant API with `price` and `availability` specified in the update mask, ensuring that only those fields are modified.

### Supplemental product synchronization (job-based)

To support native checkout eligibility and compliance requirements, a scheduled job synchronizes UCP-specific attributes to the supplemental data source. This includes product eligibility flags (such as `native_commerce`) and compliance data (such as `consumer_notice`).

The job runs on a configurable schedule, with a recommended full synchronization once per day.

## Checkout flow

The checkout flow follows the UCP specification and proceeds as follows:

1. **Create Checkout Session**: Google sends a request containing line items, buyer information, and payment instruments. The Checkout component creates an anonymous Cart in commercetools.
2. **Update Checkout Session**: Google sends updated buyer details, shipping address, and fulfillment preferences. The Checkout component updates the Cart with shipping and address information, recalculates totals, and returns updated pricing.
3. **Complete Checkout Session**: Google sends the Google Pay payment token. The Checkout component authorizes payment through your PSP, creates an Order in commercetools, and returns the completed session.

After the checkout completes, the Checkout component pushes an "Order Created" webhook to Google. Subsequent lifecycle events (shipped, canceled) are also sent as full entity updates to the Google webhook endpoint.

## Order lifecycle events

After an Order is created, your system must notify Google of lifecycle changes by sending webhook requests to the Google endpoint. These webhooks use API key authentication and require full entity updates (not partial patches) to ensure data consistency.

Supported events:

- Order created (processing)
- Order shipped (fulfilled)
- Order canceled

## Limitations

- The integration is available for eligible US retailers during the initial rollout.
- Identity linking across sessions is not supported. All checkouts are anonymous (guest checkout).
- The supplemental data source depends on products existing in the primary data source. It cannot add new products independently.
- There may be a processing delay of a few minutes between when data is sent to the Google Merchant API and when changes are reflected in Google surfaces.

## Related pages

- [Area overview page with navigation](/agentic-commerce.md)