出海数字营销宝典 Logo
出海数字营销宝典evaoo.com

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

2026-11-11Google Merchant Center Docs · Evaoo Feed Engineering Lab9 min read

Google Merchant API Start Your Migration SOP: Sub-API Priority Order, ProductInput Write/Read Split, and Preventing Offer StealingGoogle 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:

  1. Legacy products.insert writes move to productInputs and require an explicit dataSource query parameter.
  2. The standalone productstatuses endpoint for reading disapproval reasons has been removed and embedded directly inside the read-only products resource.
  3. Passing the wrong dataSource parameter 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

  1. Part 1: Google Merchant API Architecture Guide: Replacing Content API for Shopping, 2026 Sunset Timeline & Modular Upgrade Plan
  2. Part 2 (Current): Google Merchant API Start Your Migration SOP: Sub-API Priority Order, ProductInput Write/Read Split & Preventing "Offer Stealing"
  3. Part 3: Google Merchant API Authentication & GCP Project Guide: IAM Key Setup, registerGcp Registration & Zero-Downtime Cutover
  4. 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 PhaseTarget Sub-API ModuleUpstream Dependency RationaleDefinition 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 + InventoriesHandles 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 + NotificationsReporting 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, and delete) target productInputs.
  • Persistence & Version Control: Data submitted through productInputs is stored persistently (Persistent) and accepts a monotonically increasing versionNumber to guard against out-of-order distributed overwrites. If an incoming versionNumber is older than the server's stored version, the server rejects the stale write.
  • Mandatory ?dataSource=... Query Parameter: Every insert, patch, or delete request 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 inside productAttributes: { ... }, while custom fields sit in the top-level customAttributes array.
  • Preserving Historical Ads Signals: During migration, keep offerId, contentLanguage, and feedLabel identical 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 (get and list only). After a productInputs write, Google asynchronously merges primary data sources, supplemental data sources, and UI attribute rules over several seconds to a few minutes to produce the synthesized Product entity served to shoppers and ad auctions.
  • Where Legacy productstatuses Moved: The standalone productstatuses service is removed; approval status is now embedded inside Product.productStatus. A single products.get or products.list call (up to pageSize=1000) returns both synthesized product attributes and per-destination approval states plus itemLevelIssues disapproval codes (see Google Ads Product Diagnostics & Overlap Troubleshooting Guide).
  • Legacy Local-Only Feed Flag (legacyLocal): If an account still holds legacy local:en:US:SKU1 local-only feed offers, the synthesized Product carries legacyLocal: true and includes a legacy_local prefix in its resource name. Google recommends gradually migrating those offers to unified online products paired with LocalInventory.

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

  1. Step 1: Read-Only Inventory of Existing Data Sources Call GET https://merchantapi.googleapis.com/datasources/v1/accounts/{ACCOUNT_ID}/dataSources to list all Primary and Supplemental data sources. Legacy Content API feeds already appear automatically in dataSources.list as standard API Primary DataSources—do not create duplicate feeds unnecessarily.
  2. Step 2: Backfill dataSource in Your Local ERP or PIM Database Iterate through existing catalog offers with products.list, read the returned dataSource field on each item, and persist the offerId -> dataSource resource mapping in your local catalog table. Route all subsequent daily updates to each item's original dataSource via productInputs:patch.
  3. 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 contentLanguage and feedLabel primary 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 by offerId without 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 ChangeLegacy Content API v2.1 MCQLNew Merchant API v1 MCQLMigration Notes
View Name FormattingMerchantPerformanceView / 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 Prefixessegments.offer_id, segments.date, metrics.clicks, metrics.impressionsoffer_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 FilterWHERE 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

SQL25 lines
1-- Legacy Content API v2.1 MCQL (Deprecated)
2SELECT
3 segments.date,
4 segments.offer_id,
5 segments.program,
6 metrics.impressions,
7 metrics.clicks
8FROM MerchantPerformanceView
9WHERE segments.date DURING LAST_30_DAYS
10 AND segments.program = 'SHOPPING_ADS'
11
12-- New Merchant API reports/v1 MCQL (Production-Ready)
13SELECT
14 date,
15 offer_id,
16 marketing_method,
17 impressions,
18 clicks,
19 click_potential,
20 click_potential_rank
21FROM product_performance_view
22WHERE date DURING LAST_30_DAYS
23 AND marketing_method = 'ADS'
24ORDER BY clicks DESC
25LIMIT 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 registered or 409 DUPLICATE_PROJECT_REGISTRATION. Continue to Part 3: Google Merchant API Authentication & GCP Project Guide: IAM Key Setup, registerGcp Registration & Zero-Downtime Cutover.

Merchant APIGoogle Merchant CenterProduct FeedDataSourcesMCQLGoogle ShoppingCross-Border E-CommerceTechnical Architecture

Found this actionable? Copy standard citation & summary

Formatted with canonical attribution link and executive summary—ready for Slack, Notion, or LLM context.