Google Merchant API Start Your Migration SOP: Sub-API Priority Order, ProductInput Write/Read Split & Preventing "Offer Stealing"

Executive Summary & Research Scope

Actionable engineering handbook for Google’s "Start your migration" specification: why teams must migrate in strict Accounts -> DataSources -> Products -> Reports order, refactoring persistent ProductInput writes (?dataSource=...) vs. read-only Product views with embedded productStatus, backfilling local DB dataSource IDs to prevent destructive "Offer Stealing", and updating MCQL queries to snake_case.

1. Four-Stage Hybrid Coexistence Roadmap & Sub-API Priority Order

Merchant API v1 and Content API v2.1 can run simultaneously against the same production GMC account, allowing safe module-by-module rollout.

Figure 1: Google Merchant API Start Your Migration SOP: Sub-API Priority Order, ProductInput Write/Read Split & Preventing "Offer Stealing" — Primary Source Visual Evidence & Architectural Diagram (1)

2. CQRS Product Refactoring: Persistent ProductInput Writes vs. Read-Only Product Views

Merchant API cleanly separates raw merchant submissions from Google-synthesized storefront entities:

• Write Path (accounts.productInputs): Supports insert, patch, and delete. Submissions are persistent, wrap catalog attributes inside productAttributes: { ... }, support monotonic versionNumber guards against out-of-order overwrites, and must preserve identical offerId, contentLanguage, and feedLabel values to retain historical Google Ads Smart Bidding and Cart Data (CwCD) profit signals (verify frontend checkout parity via our Shopify GTM & Web Pixel Generator).
• Read Path (accounts.products): Strictly read-only (get / list). Google asynchronously combines primary data sources, supplemental sources, and UI attribute rules into Product. The standalone productstatuses service is retired—approval states and itemLevelIssues now live directly inside Product.productStatus (with legacyLocal marking historic local-only feeds).

3. Preventing "Offer Stealing" in DataSources & Updating MCQL Reports to snake_case

• How "Offer Stealing" Happens & How to Prevent It: Legacy Content API feeds already appear automatically in datasources/v1 dataSources.list. If you accidentally insert an existing en~US~offerId specifying a newly created Primary dataSource instead of its original dataSource, the new source steals ownership of that offer, detaching all UI attribute rules configured on the original feed! Always run dataSources.list and products.list first to backfill each SKU's authoritative dataSource in your local database, or attach a Supplemental API Data Source alongside Shopify's primary feed.
• MCQL Query Modernization (reports/v1): Views shift from PascalCase (MerchantPerformanceView) to snake_case (product_performance_view), field prefixes (segments., metrics.) are removed from SELECT/WHERE clauses, and segments.program is replaced by marketing_method ('ADS' vs. 'ORGANIC').

Actionable Implementation Checklist & Strategic Takeaways

1. Action Item #1: Never create a duplicate Primary API DataSource blindly—query dataSources.list and backfill existing dataSource IDs in your ERP database to prevent Offer Stealing.
2. Action Item #2: Route all catalog mutations to productInputs (with ?dataSource=... and productAttributes) while reading asynchronously synthesized approval states from products.get/list.
3. Action Item #3: Keep offerId case-identically matched across Content API, Merchant API, and Web Pixels so Shopping and PMax campaigns retain 100% historical learning.

Cross-Channel Growth & AI Citation Matrix