Enable the Retail API (retail.googleapis.com) in your Google Cloud project and create a service account with the Retail Editor role; download the service account key or use Workload Identity Federation for production.
Import your product catalog by calling the products.import method (POST to https://retail.googleapis.com/v2/projects/{project}/locations/global/catalogs/default_catalog/branches/default_branch/products:import); the importConfig supports inlineSource (JSON in the request body), gcsSource (Cloud Storage URI for JSON Lines files), or bigQuerySource for large catalogs.
Map your product data to the Retail API Product schema: required fields include id, title, and categories; recommended fields include priceInfo, brands, description, uri, and availability.
Record real-time user events by calling userEvents.write (POST /v2/.../userEvents:write) with an event object containing eventType (e.g., 'detail-page-view', 'add-to-cart', 'purchase-complete'), userInfo (visitorId), and productDetails; for bulk historical backfill use userEvents.import.
After accumulating sufficient event data, use the Retail console to create serving configs for Search and Recommendations; the AI models are trained on catalog + event data and improve over time.
Known gotchas
Vertex AI Search for retail was renamed to AI Commerce Search (under Gemini Enterprise for Customer Experience); documentation URLs moved to docs.cloud.google.com/retail — old links redirect but confirm you are reading current docs.
visitorId in user events must be consistent per anonymous user across sessions; use a stable first-party cookie identifier rather than a session ID, as changing IDs break the user's event history for ML training.
Import jobs are long-running operations; use the returned operation name with operations.get to poll for completion rather than assuming the catalog is immediately searchable.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp