Google Merchant API Authentication & GCP Project Guide: IAM Key Setup, registerGcp Registration & Zero-Downtime Cutover
Google Merchant API Authentication & GCP Project Guide: IAM Key Setup, registerGcp Registration & Zero-Downtime Cutover
Migration Note: Adding a Service Account in GMC Alone No Longer Authenticates
In the legacy Content API for Shopping, developers could open Merchant Center and navigate to "Settings -> Content API -> Authentication" to generate a JSON key in one click and start calling endpoints immediately.
After upgrading to Merchant API, Google restructured authentication across two specifications—Configure API authentication from Merchant Center and Manage and transition GCP projects:
- The GMC console removed the direct API key generation button. Creating a Service Account, configuring OAuth 2.0 clients, and enabling
merchantapi.googleapis.comare now managed exclusively inside the Google Cloud Console (GCP Console).- A mandatory
developerRegistration:registerGcpstep is now enforced. Even if a service account already holds Admin access in GMC, all business API calls will fail with401 UNAUTHENTICATEDunless its parent GCP project has completedregisterGcpdeveloper binding.
Google Merchant API Migration Series Navigation
- Part 1 (Architecture & Sunset Timeline): Google Merchant API Architecture Guide: Replacing Content API for Shopping, 2026 Sunset Timeline & Modular Upgrade Plan
- Part 2 (Migration Order & Read/Write Split): Google Merchant API Start Your Migration SOP: Sub-API Priority Order, ProductInput Write/Read Split & Preventing "Offer Stealing"
- Part 3 (Current — Authentication & GCP Architecture): Google Merchant API Authentication & GCP Project Guide: IAM Key Setup, registerGcp Registration & Zero-Downtime Cutover
- Part 4 (High Concurrency & Quota Governance): Google Merchant API Concurrent Requests & gRPC Channel Pool Guide: Replacing custombatch, 100-Stream Scaling & Dynamic Quotas
Chapter 1: Reusing Legacy Keys & Configuring New GCP Credentials
Service Account JSON keys originally created in the legacy GMC console remain valid and can be reused directly. You only need to complete two steps inside that key's parent GCP project: enable the Merchant API service and run registerGcp once.
If you are provisioning credentials for a new DTC storefront or ERP service, follow the 4 steps in the Google Cloud Console:
| Configuration Step | Console Location & Command | Required Permissions (IAM Role / GMC Access) & Notes |
|---|---|---|
| Step 1: Locate or create a GCP project | Open the Google Cloud Console. If your legacy project was auto-generated by GMC, select your organization in the project picker and look for an associated project named similarly to Content API for Shopping. | For production workloads, create a dedicated named project (such as prod-evaoo-merchant-api) to isolate quota monitoring and security audits. |
Step 2: Enable merchantapi.googleapis.com | Search for Merchant API under "APIs & Services > Library" and click Enable, or run gcloud services enable merchantapi.googleapis.com. | The operator must hold roles/owner, roles/editor, or roles/serviceusage.serviceUsageAdmin on the GCP project. |
| Step 3: Create a Service Account or OAuth 2.0 credential | Use a Service Account for server-side jobs; on Cloud Run or GKE, prefer Workload Identity to eliminate static key files. External multi-merchant SaaS apps should use an OAuth 2.0 Web Client. | Keep using the https://www.googleapis.com/auth/content OAuth scope. Because the scope matches v2.1, existing merchant Refresh Tokens remain valid without re-prompting for consent. |
| Step 4: Add the Service Account to the GMC user list | Copy the service account email (formatted like [email protected]) and add it in GMC Next under "Settings > Access and services > Users". | You must assign the Admin role when performing the initial registerGcp registration or managing account settings. Routine catalog reads/writes should follow least privilege with Standard. |
Chapter 2: developerRegistration:registerGcp Prerequisites & Troubleshooting
After enabling the API and granting GMC user access, execute a one-time developer registration request using credentials from that GCP project. Select your deployment scenario in the GCP Authentication Architecture & Error Diagnostic Simulator below (single storefront direct integration, MCA agency sub-accounts, dual-GCP zero-downtime cutover, or 401/409 troubleshooting) to generate the corresponding commands:
2.1 Five Prerequisites for Calling registerGcp
Missing any of the following prerequisites will cause the registration call to fail:
- Production GMC Account Only: Legacy sandbox Test Accounts do not support calling
registerGcp. - Verified & Claimed Website: An empty shell GMC account without a verified storefront domain fails validation. For configuring first-party domain and markup signals, see Google Data Strength Best Practices.
- Caller Holds
ADMINRole in the Target GMC Account: CallingregisterGcpwithStandardaccess triggers403 PERMISSION_DENIED. - Provide a Real Google User or Team Email for
developerEmail: The{"developerEmail": "[email protected]"}payload field receives breaking-change notices, quota alerts, and compliance notifications. Never pass a.gserviceaccount.comservice account email, or the API immediately rejects the request with400 INVALID_ARGUMENT. - Allow a 5-Minute Propagation Window & 14-Day Invite Acceptance: After
registerGcpreturns200 OK, global gateway routing takes roughly 5 minutes to propagate; wait 5 minutes in scripts before starting high-volume catalog syncs. If the supplieddeveloperEmailis not yet a member of that GMC account, Google sends an invitation email that the recipient must accept within 14 days.
2.2 registerGcp Request & Response Example
| 1 | # Run a one-time registration using an admin OAuth token from the target GCP project |
| 2 | curl -X POST "https://merchantapi.googleapis.com/accounts/v1/accounts/123456789/developerRegistration:registerGcp" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" -H "Content-Type: application/json" -d '{ |
| 3 | "developerEmail": "[email protected]" |
| 4 | }' |
On success, the endpoint returns a DeveloperRegistration resource object containing the bound gcpIds project number list. Afterward, you can verify registration status anytime by calling GET https://merchantapi.googleapis.com/accounts/v1/accounts/123456789/developerRegistration.
Chapter 3: Binding Topology Rules: 1 GMC : N GCP vs. 1 GCP : 1 Primary GMC
Multi-brand retail groups operating multiple GMC accounts and agencies managing hundreds of client GMC accounts frequently hit 409 ALREADY_EXISTS (DUPLICATE_PROJECT_REGISTRATION) when designing cloud architecture. Follow these two binding cardinality rules before provisioning projects:
| Binding Direction | Official Ratio Limit | Architectural Meaning & Engineering Practice |
|---|---|---|
| Forward: 1 Primary GMC Account -> Multiple GCP Projects | Supports 1 : N (One-to-Many) | You can register an ERP inventory sync service (GCP Project A), a BI data warehouse pipeline (GCP Project B), and an AI auditing MCP service (GCP Project C) to the same primary GMC account—isolating microservice quotas and limiting key-compromise blast radius. |
| Reverse: 1 GCP Project -> Multiple GMC Accounts | Strictly 1 : 1 (One-to-One Primary Account) | A single GCP project can be registered to only 1 top-level GMC account at any time (either a Standalone account or an MCA parent account). Calling registerGcp with the same GCP project against a second GMC account immediately returns 409 DUPLICATE_PROJECT_REGISTRATION. |
3.1 Multi-Brand Groups & Multi-Tenant SaaS Architectures
When managing dozens of sub-brands or serving hundreds of external merchants, do not spin up hundreds of GCP projects, and never call registerGcp on an MCA sub-account. Google officially recommends two multi-tenant architectures:
- Multi-Brand Groups, CSS Providers & Agencies (MCA Advanced Account Pattern): Register 1 core GCP project once to your group's top-level MCA (Multi-Client Account). Once registered, credentials from that GCP project can directly read and write across all sub-accounts under that MCA (for example, calling
accounts/{SUB_ACCOUNT_ID}/productInputs:insert) without registering sub-accounts individually. - Third-Party E-Commerce SaaS Apps & ERP Vendors (Cross-Tenant OAuth Pattern): Register your SaaS platform's official GCP project to your own company's primary developer GMC account to establish your platform developer identity, and declare your actual partner role (Marketplace, Agency, CSS, Brand, or POS integrator) in partner attributes. From there, use standard OAuth 2.0 consent flows—or have external merchants add your service account to their GMC user list—so that this single registered GCP project can access authorized merchant data without calling
registerGcpon external merchant accounts.
Chapter 4: Dual-GCP Zero-Downtime Cutover & Unregistration for Large Teams
If your production Content API jobs still run inside a legacy GCP project, you can use this upgrade to migrate into a cleanly scoped new GCP project with zero interruption to live ads or inventory syncs. Google's Manage and transition GCP projects documentation outlines two transition paths and two recovery endpoints.
4.1 Choosing Between Two GCP Migration Paths
- Option 1: In-Place Upgrade (Keep Existing GCP Project). Ideal for teams whose current GCP project already has clear ownership and tight IAM controls. Enable
merchantapi.googleapis.comand runregisterGcpdirectly in the existing project so legacy and new services run side by side during transition with minimal operational churn. - Option 2: Dual-GCP Isolated Cutover (Dual-GCP Zero-Downtime Cutover). Ideal for large merchants migrating module by module in 4 steps:
- Leave the legacy GCP project untouched running existing Content API v2.1 workloads; if a complex migration requires transition support, the legacy project identity stays intact.
- Create a new production GCP project, enable Merchant API, provision least-privilege service accounts, and call
registerGcpto bind the new GCP project to your primary GMC account. - Shift traffic incrementally by module—moving product updates, inventory sync, and reporting pulls onto the new GCP project. For aligned client-side tracking governance, refer to our Google Tag & GTM Unification Guide and the Tracking & Attribution Hub.
- Once Content API traffic on the legacy GCP project drops to zero, revoke old keys and decommission the legacy project.
4.2 Reverse Lookup & Safe Unregistration Endpoints
If integration testing hits 409 DUPLICATE_PROJECT_REGISTRATION and your team does not know which GMC account currently owns a GCP project, use these two endpoints:
- Reverse Lookup of Current Binding: Call
GET https://merchantapi.googleapis.com/accounts/v1/accounts:getAccountForGcpRegistrationwithout passing an Account ID. The gateway inspects the caller credential's GCP project and returns the bound primary GMC account resource name (such asaccounts/99887766). - Safe Unregistration & 24-Hour Grace Window (
unregisterGcp): To move a GCP project from an old primary GMC account to a new one, first callPOST .../accounts/{OLD_ID}/developerRegistration:unregisterGcpagainst the old account. Unregistering provides roughly a 1-day (24-hour) grace window so in-flight requests do not abruptly break, while immediately freeing the GCP project to bind to the new primary account.
Next Article: Once authentication is configured, if you need to update prices and inventory for 60,000 SKUs per minute during peak sales events, continue to Part 4—Google Merchant API Concurrent Requests & gRPC Channel Pool Guide: Replacing custombatch, 100-Stream Scaling & Dynamic Quotas—to implement channel pooling and dynamic quota governance after
custombatchretirement.
Found this actionable? Copy standard citation & summary
Formatted with canonical attribution link and executive summary—ready for Slack, Notion, or LLM context.
Put Into Practice: Companion Browser Workbenches
UTM Builder Pro Matrix Workspace
Reverse URL parser, GA4 channel group diagnostics, and dynamic ad macro batch CSV export.
Shopify GTM & GA4 Web Pixel Generator
Generate production-ready Shopify Customer Events Web Pixel code for GA4, Meta, and TikTok.