Google Retail

Sync product catalog data and user behavioral events to Google Cloud Retail (Vertex AI Search for Commerce). Power search results, personalized recommendations, and merchandising insights with enriched product and event data from your warehouse.

Prerequisites

• A Google Cloud project with the Retail API (Vertex AI Search for Commerce) enabled
• A catalog created in the Retail API (a default_catalog is created automatically when the API is enabled)
• A Google Cloud service account or OAuth credentials with the following IAM permissions:
  • retail.products.import (for product syncs)
  • retail.userEvents.import (for user event syncs)
  • retail.catalogs.get (for connection testing)

Authentication

Google OAuth 2.0

1. In Zeotap, click Add Destination and select Google Retail
2. Click Connect with Google
3. Sign in with a Google account that has access to the target GCP project
4. Grant the requested cloud-platform scope
5. Zeotap securely stores the OAuth tokens and automatically refreshes them

Service Account Bearer Token

1. In the Google Cloud Console , navigate to IAM & Admin > Service Accounts
2. Create or select a service account with the required Retail API permissions
3. Generate a bearer token using the Google Cloud CLI:

   gcloud auth print-access-token --impersonate-service-account=SA_EMAIL

4. Paste the token into the Access Token field in Zeotap

Note: Service account bearer tokens expire after 1 hour. For production syncs, use OAuth 2.0 with a refresh token for automatic renewal.

Configuration

Target Settings

Supported Operations

Sync Modes

• Upsert uses the INCREMENTAL reconciliation mode, which inserts new products or updates existing ones matched by product ID.
• Insert also uses INCREMENTAL mode — the Retail import API is idempotent, so inserting a product that already exists will update it.

Audience Sync Modes

Google Retail does not have a list or audience membership concept. Use standard sync modes to send product and event data.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Product Fields

User Event Fields

How It Works

1. Product Sync: Zeotap sends product data to the Retail API products:import endpoint in batches of up to 100 products. The import operation runs asynchronously on Google’s side. In Incremental mode, existing products are updated by ID and new products are created. In Full mode, the entire catalog branch is replaced.

2. User Event Sync: Zeotap sends behavioral events to the userEvents:import endpoint in batches of up to 10,000 events. Events must include an event_type and visitor_id. The Retail API uses these events to train recommendation models, improve search ranking, and power personalization.

3. Authentication: Zeotap uses OAuth 2.0 bearer tokens with the cloud-platform scope. Tokens are automatically refreshed before they expire.

4. Error Handling: Each batch chunk is processed independently. Failed chunks are reported with the HTTP status and error message from the API. Transient errors (rate limits, server errors) are retried with exponential backoff.

Rate Limits

The batch import endpoints (products:import and userEvents:import) are the recommended approach for high-volume data sync and are subject to project-level quotas. Zeotap automatically handles rate limiting with exponential backoff.

Best Practices

• Use Incremental mode for regular product syncs to avoid replacing the entire catalog
• Include all required fields for events — detail-page-view and add-to-cart events must include a product_id; purchase-complete events must include revenue
• Use consistent visitor IDs across all event types for accurate behavioral modeling
• Include at least 100 unique visitor IDs per event type for model training quality
• Upload events within 24 hours of occurrence for optimal recommendation freshness
• Map currency_code when syncing products with pricing to ensure proper price display and filtering

Troubleshooting

Authentication failed: invalid or expired token

Verify your OAuth connection is active or regenerate the service account bearer token. Bearer tokens expire after 1 hour. For production use, connect with OAuth 2.0 which automatically refreshes tokens.

Catalog not found (404)

Verify the GCP Project ID and Catalog ID are correct. The Retail API must be enabled on the project. Check that the default catalog exists by visiting the Retail console .

Permission denied (403)

The authenticated account needs the following IAM roles:

• roles/retail.editor (or specific retail.products.import and retail.userEvents.import permissions)
• Verify the service account or user has been granted access in IAM & Admin for the target project.

Product import fails with INVALID_ARGUMENT

Ensure every product row has a valid id field (UTF-8 encoded, max 128 characters). Verify that availability values use the exact enum strings: IN_STOCK, OUT_OF_STOCK, PREORDER, or BACKORDER.

User events not appearing in recommendations

Events require at minimum: eventType, visitorId, and eventTime. For search-related events, include searchQuery or pageCategories. For purchase events, revenue and currencyCode are required. Also verify you meet the minimum event volume thresholds (250,000 search events in 90 days for search optimization).

Events rejected as stale

The Retail API rejects events with timestamps that are too old. Ensure event_time is in RFC 3339 format and within the acceptable time window (typically within the last 24 hours for real-time ingestion).

Products not showing in search results

Product imports are processed asynchronously. There may be a delay of several minutes before products appear in search results. Also verify that the products have the required title field and are imported to the correct catalog branch.

Rate limiting (429 errors)

Zeotap automatically retries rate-limited requests. If you see persistent rate limit errors, check your project quotas in the Google Cloud Console under APIs & Services > Quotas. Consider requesting a quota increase for high-volume syncs.