Google Merchant API Start Your Migration SOP: Sub-API Priority Order, ProductInput Write/Read Split & Preventing "Offer Stealing"
Google Merchant API Start Your Migration SOP: Sub-API Priority Order, ProductInput Write/Read Split, and Preventing Offer Stealing
Overview
In Part 1: Architecture Overview, we covered Content API for Shopping's official August 18, 2026 sunset. When engineering teams begin refactoring code, three API shifts immediately surface:
- Legacy
products.insertwrites move toproductInputsand require an explicitdataSourcequery parameter.- The standalone
productstatusesendpoint for reading disapproval reasons has been removed and embedded directly inside the read-onlyproductsresource.- Passing the wrong
dataSourceparameter triggers "Offer Stealing", detaching feed attribute rules configured in the GMC console.This SOP consolidates Google's Start your migration specification alongside the Products, Data sources, and Reports compatibility guides into a step-by-step engineering rollout plan.
Series Navigation
- Part 1: Google Merchant API Architecture Guide: Replacing Content API for Shopping, 2026 Sunset Timeline & Modular Upgrade Plan
- Part 2 (Current): Google Merchant API Start Your Migration SOP: Sub-API Priority Order, ProductInput Write/Read Split & Preventing "Offer Stealing"
- Part 3: Google Merchant API Authentication & GCP Project Guide: IAM Key Setup, registerGcp Registration & Zero-Downtime Cutover
- Part 4: Google Merchant API Concurrent Requests & gRPC Channel Pool Guide: Replacing custombatch, 100-Stream Scaling & Dynamic Quotas
Chapter 1: Official Four-Step Migration Roadmap & Sub-API Priority Order
Merchant API and Content API v2.1 support Hybrid Coexistence on the same production GMC account, so teams do not need a risky big-bang cutover. Keep existing legacy jobs running while rolling out and validating one sub-module at a time.
Because sub-APIs have strict upstream/downstream dependencies, Google recommends migrating in the following sequence:
| Migration Phase | Target Sub-API Module | Upstream Dependency Rationale | Definition of Done |
|---|---|---|---|
| Phase 1 (Accounts & Auth) | Accounts (including developerRegistration) | Until GCP project developer binding via registerGcp is complete, calls to all other Merchant API sub-modules fail with 401 UNAUTHENTICATED (see Part 3: GCP Auth Guide). | Successfully call accounts.get and accounts.list to verify primary account and MCA sub-account hierarchy. |
| Phase 2 (Data Sources) | Data sources (replaces datafeeds) | productInputs.insert requires passing the target dataSource resource name explicitly in query parameters and no longer auto-creates an implicit default API feed. | Fetch the full list of existing data sources and persist each storefront's accounts/{A}/dataSources/{D} mapping in your local database. |
| Phase 3 (Products & Inventory) | Products + Inventories | Handles high-frequency SKU inserts, partial price patch calls, deletions, regional inventory syncs, and disapproval checks—while preserving offerId parity with historical Google Ads bidding signals. | Canary 1% of SKUs onto productInputs, confirm normal products.get status after the 3–5 minute async merge, and verify zero loss of campaign history. |
| Phase 4 (Reports & Alerts) | Reports + Promotions + Notifications | Reporting queries are read-only downstream consumers with low migration risk; pair with notifications Pub/Sub alerts and ucp_agentic_performance_view. | Daily BI batch jobs execute new snake_case MCQL queries cleanly and legacy report tasks are retired. |
Chapter 2: Refactoring the Products Module: ProductInput vs. Product Read/Write Separation
In legacy Content API v2.1, the single products resource handled both raw merchant writes and post-processed reads. Items inserted via products.insert expired after 30 days without refresh, and when combined with Supplemental Feeds, engineers struggled to tell whether a bug originated in raw input payloads or GMC UI feed rules.
Merchant API adopts Command Query Responsibility Segregation (CQRS), splitting catalog entities into two separate resources.
2.1 Write Path: accounts.productInputs (Persistent Raw Inputs)
- Endpoint Responsibility: Represents the raw catalog data submitted by a merchant to a specific Data Source. All mutations (
insert,patch, anddelete) targetproductInputs. - Persistence & Version Control: Data submitted through
productInputsis stored persistently (Persistent) and accepts a monotonically increasingversionNumberto guard against out-of-order distributed overwrites. If an incomingversionNumberis older than the server's stored version, the server rejects the stale write. - Mandatory
?dataSource=...Query Parameter: Everyinsert,patch, ordeleterequest must specify the full target data-source path in the URL query string, for example:POST https://merchantapi.googleapis.com/products/v1/accounts/123456/productInputs:insert?dataSource=accounts/123456/dataSources/987654 - Payload Schema Changes: Standard attributes such as title, description, link, price (
amountMicros), GTIN, and availability now live insideproductAttributes: { ... }, while custom fields sit in the top-levelcustomAttributesarray. - Preserving Historical Ads Signals: During migration, keep
offerId,contentLanguage, andfeedLabelidentical to legacy values (case-sensitive). As long as that three-part key matches, Shopping and PMax campaigns retain historical CTR/conversion learning and Conversions with Cart Data (CwCD) profit attribution remains uninterrupted. Also validate storefront pixels with the Shopify GTM & Web Pixel Generator so reported item IDs match your feed.
2.2 Read Path: accounts.products (Read-Only Synthesized View & Embedded Status)
- Endpoint Responsibility: Strictly read-only (
getandlistonly). After aproductInputswrite, Google asynchronously merges primary data sources, supplemental data sources, and UI attribute rules over several seconds to a few minutes to produce the synthesizedProductentity served to shoppers and ad auctions. - Where Legacy
productstatusesMoved: The standaloneproductstatusesservice is removed; approval status is now embedded insideProduct.productStatus. A singleproducts.getorproducts.listcall (up topageSize=1000) returns both synthesized product attributes and per-destination approval states plusitemLevelIssuesdisapproval codes (see Google Ads Product Diagnostics & Overlap Troubleshooting Guide). - Legacy Local-Only Feed Flag (
legacyLocal): If an account still holds legacylocal:en:US:SKU1local-only feed offers, the synthesizedProductcarrieslegacyLocal: trueand includes alegacy_localprefix in its resource name. Google recommends gradually migrating those offers to unified online products paired withLocalInventory.
Chapter 3: DataSources Migration Priority: Preventing "Offer Stealing"
3.1 How "Offer Stealing" Is Triggered
In legacy Content API, calling products.insert required no Feed ID—Google routed writes into the default Content API primary data source automatically. Many merchant accounts end up with two data sources side by side:
- Data Source A: The legacy default API primary data source, where merchandisers configured 20 title-concatenation and Custom Label rules in the GMC UI.
- Data Source B: A newly created Primary API Data Source provisioned while testing Merchant API.
When switching to productInputs.insert?dataSource=DataSourceB, if your code fails to check that a SKU originally belonged to Data Source A and writes the same en~US~offerId into Data Source B, Data Source B steals ownership of that offer from Data Source A. Once stolen, every custom label, promotion mapping, and attribute transformation rule attached to Data Source A stops applying to that SKU—disrupting campaign segmentation immediately.
3.2 Three-Step Anti-Stealing Audit & Three DataSource Architectures
- Step 1: Read-Only Inventory of Existing Data Sources
Call
GET https://merchantapi.googleapis.com/datasources/v1/accounts/{ACCOUNT_ID}/dataSourcesto list all Primary and Supplemental data sources. Legacy Content API feeds already appear automatically indataSources.listas standard API Primary DataSources—do not create duplicate feeds unnecessarily. - Step 2: Backfill
dataSourcein Your Local ERP or PIM Database Iterate through existing catalog offers withproducts.list, read the returneddataSourcefield on each item, and persist theofferId -> dataSourceresource mapping in your local catalog table. Route all subsequent daily updates to each item's originaldataSourceviaproductInputs:patch. - Step 3: Choose a DataSource Topology for New Workloads
- Single Primary Data Source: Best for single-storefront DTC brands where the entire catalog shares one language and feed label, minimizing maintenance overhead.
- Multiple Primary Data Sources: Best for multi-region brands operating dedicated US, EU, UK, and JP storefronts, assigning separate
contentLanguageandfeedLabelprimary sources per market. - Primary + Supplemental API Data Source: Best for merchants using Shopify's official app for core catalog sync. Leave the Shopify-managed Primary DataSource untouched, and create a separate Supplemental DataSource driven by a custom Merchant API script to attach real-time margin tiers (
customLabel0–customLabel4) or promo flags byofferIdwithout interfering with Shopify syncs. - Manual Attribute Rules Warning: If you intentionally retire an old data source and move to a new one, note that Attribute Rules configured in the GMC console cannot be copied automatically via API. Have ops recreate all rules manually on the new data source before cutting over traffic.
Chapter 4: Reports & MCQL Syntax Changes: Stripping Prefixes and Standardizing on snake_case
If your BI team extracts impressions, clicks, and price competitiveness data via legacy reports.search, update three MCQL syntax rules when migrating to POST https://merchantapi.googleapis.com/reports/v1/accounts/{ACCOUNT_ID}/reports:search:
| Syntax Change | Legacy Content API v2.1 MCQL | New Merchant API v1 MCQL | Migration Notes |
|---|---|---|---|
| View Name Formatting | MerchantPerformanceView / PriceCompetitivenessProductView (PascalCase) | product_performance_view / price_competitiveness_product_view (snake_case) | Standardized on SQL snake_case naming; MerchantPerformanceView is renamed to product_performance_view. |
| Field Name Prefixes | segments.offer_id, segments.date, metrics.clicks, metrics.impressions | offer_id, date, clicks, impressions (bare column names—drop segments. and metrics. prefixes) | Simplifies query syntax; returned JSON row objects still group fields by view structure. |
| Traffic Type Filter | WHERE segments.program = 'SHOPPING_ADS' | WHERE marketing_method = 'ADS' (or 'ORGANIC') | segments.program is replaced by marketing_method to separate paid ads from organic Free Listings (pair with our Shopify SEO Guide). |
Legacy vs. New MCQL Query Comparison
| 1 | -- Legacy Content API v2.1 MCQL (Deprecated) |
| 2 | SELECT |
| 3 | segments.date, |
| 4 | segments.offer_id, |
| 5 | segments.program, |
| 6 | metrics.impressions, |
| 7 | metrics.clicks |
| 8 | FROM MerchantPerformanceView |
| 9 | WHERE segments.date DURING LAST_30_DAYS |
| 10 | AND segments.program = 'SHOPPING_ADS' |
| 11 | |
| 12 | -- New Merchant API reports/v1 MCQL (Production-Ready) |
| 13 | SELECT |
| 14 | date, |
| 15 | offer_id, |
| 16 | marketing_method, |
| 17 | impressions, |
| 18 | clicks, |
| 19 | click_potential, |
| 20 | click_potential_rank |
| 21 | FROM product_performance_view |
| 22 | WHERE date DURING LAST_30_DAYS |
| 23 | AND marketing_method = 'ADS' |
| 24 | ORDER BY clicks DESC |
| 25 | LIMIT 1000 |
Next-Step Authentication Tip: GMC has closed the legacy console workflow for generating API keys directly. Calling endpoints without registering your GCP project first triggers
401 UNAUTHENTICATED: GCP project is not registeredor409 DUPLICATE_PROJECT_REGISTRATION. Continue to Part 3: Google Merchant API Authentication & GCP Project Guide: IAM Key Setup, registerGcp Registration & Zero-Downtime Cutover.
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.