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

Google Merchant API Architecture Guide: Replacing Content API for Shopping, 2026 Sunset Timeline & Modular Upgrade Plan

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

Google Merchant API Architecture Guide: Replacing Content API for Shopping, 2026 Sunset Timeline, and Modular Upgrade PlanGoogle Merchant API Architecture Guide: Replacing Content API for Shopping, 2026 Sunset Timeline, and Modular Upgrade Plan

Sunset Timeline Notice

Merchant API is Google's next-generation Merchant Center (GMC) account and product management system, designed to replace the legacy Content API for Shopping (v2.1).

According to Google's official Deprecation and Sunset schedule, Content API for Shopping officially sunsets on August 18, 2026. Starting September 1, 2026, Google will progressively throttle and reject unmigrated requests with HTTP 410 Gone (reason: "content_api_sunset"), before fully shutting down all legacy servers in early 2027.

Merchants operating custom ERP or PIM catalog middleware, Google CSS partners and agencies managing multiple sub-accounts, and Shopify DTC teams running custom supplemental feed scripts must complete evaluation and migration well ahead of BFCM peak season.


Series Navigation

Covering all four modules of Google's Compatibility with Content API for Shopping documentation, we compiled a four-part migration series in the Evaoo Google Digital Marketing & Feed Engineering Hub for engineering and acquisition teams to follow in sequence:

  1. Part 1 (Current): Google Merchant API Architecture Guide: Replacing Content API for Shopping, 2026 Sunset Timeline & Modular Upgrade Plan
  2. Part 2: 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: 2026–2027 Official Sunset Timeline & Impact Self-Audit

Before scoping engineering sprints, confirm the cutoff dates for legacy endpoints and identify which integrations require code changes from your team.

1.1 Four Official Deprecation & Sunset Milestones

Milestone DateOfficial Gateway BehaviorImpact on Campaigns & GMC Product Feeds
Now – August 17, 2026Hybrid Coexistence Window: Core Merchant API v1 sub-APIs are Generally Available (GA) and can read/write alongside Content API v2.1 on the same GMC account.Ideal period for staged migration and canary rollouts; migrate sub-modules incrementally without any maintenance downtime.
August 18, 2026Official Sunset Date: Content API for Shopping v2.1 reaches end of official lifecycle support and SLA guarantees.Unmigrated custom sync scripts and scheduled inventory/price jobs enter immediate disconnection risk.
Starting September 1, 2026Progressive Outages: Google incrementally blocks legacy Content API traffic, returning HTTP 410 Gone with reason: "content_api_sunset".Failed price and stock updates cause GMC Price Mismatch disapprovals, directly jeopardizing Q4 peak readiness.
Early 2027Full Decommissioning: All legacy Content API endpoints, client SDKs, and associated Order Management / Buy on Google legacy APIs are permanently removed.100% of remaining v2.1 calls fail permanently.

Note for Shopify & Third-Party SaaS Merchants If your storefront syncs exclusively through Shopify's official Google & YouTube app or managed third-party connectors such as Feedonomics, DataFeedWatch, or Channable, the platform vendor handles the backend cutover to Merchant API automatically—no code changes are required on your side. However, your engineering team must refactor code if your stack includes any of these custom integrations:

  1. In-house ERP or warehouse services calling shoppingcontent.googleapis.com on a schedule to update real-time inventory or tiered pricing.
  2. Python or Node.js jobs polling GMC product disapprovals (formerly productstatuses) to fire Slack, Feishu, or DingTalk alerts (see Google Ads Product Diagnostics & Overlap Troubleshooting Guide).
  3. Internal BI data warehouses pulling Free Listings and Shopping Ads competitiveness reports via MCQL.
  4. Automated scripts configuring multi-country shipping templates, return policies, or Regional Inventory via API.

Chapter 2: Modular Sub-API Architecture & URL Addressing Changes

Legacy Content API for Shopping coupled account access, catalog writes, feed rules, promotions, local inventory, and reporting inside a single v2.1 namespace. Upgrading even one peripheral feature forced a full SDK bump across the entire codebase.

Following Google Cloud API Improvement Proposals (AIP), Merchant API splits those capabilities into more than a dozen decoupled sub-APIs, each carrying its own independent version (v1 or v1beta).

2.1 URL Addressing Format Comparison & Sub-API Directory

  • Legacy Content API v2.1 Request Pattern: https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/{RESOURCE}/{ID}
  • New Merchant API v1 Request Pattern: https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}
Sub-API Namespace ({SUB_API})Recommended VersionCore Responsibilities & Replaced Legacy ModulesTypical Production Use Cases
accountsv1Handles account management, user access, business info, automatic improvements, terms of service, shipping/return policies, online store registration, and developerRegistration (GCP binding).Bulk MCA sub-account provisioning, domain verification, shipping rate tables.
datasourcesv1Replaces legacy datafeeds; manages Primary, Supplemental, Promotion, and Regional Inventory data sources, including on-demand fetch triggers.Creating API product ingestion channels and triggering scheduled feed fetches.
productsv1Split into productInputs (persistent async writes) and products (read-only synthesized view + embedded approval status); removes standalone productstatuses.Catalog onboarding, partial price patch updates, reading item-level disapproval diagnostics.
inventoriesv1Manages online regional pricing/stock (RegionalInventory) and brick-and-mortar store stock (LocalInventory).U.S. state-level pricing differentials and Local Inventory Ads (LIA) stock decrements.
reportsv1Powers updated MCQL (Merchant Center Query Language) analytics covering product performance, price competitiveness, Best Sellers, and UCP agentic performance views.BI warehouse ETL pipelines, bestseller trend monitoring, AI shopping agent conversion tracking.
promotionsv1Creates and retrieves promotional coupon codes, BOGO/tiered discounts, and promotion review statuses.Syncing sitewide BFCM promo codes to Google Shopping badges at scale.
notificationsv1New capability: configures Cloud Pub/Sub or Webhook push subscriptions (NotificationSubscription).Real-time alerting when hero SKUs are disapproved or change review state, eliminating polling.
quotav1Inspects daily quota totals, consumed usage, and per-minute burst limits per QuotaGroup.Adaptive rate limiting across distributed sync workers.
lfp / issueresolution / ordertracking / reviewsv1 / v1betaCovers Local Feeds Partnership (LFP), account/item appeal triggers (triggeraction), fulfillment tracking signals, and Merchant/Product Reviews APIs.Resolving policy violations and maintaining star ratings on Free Listings.

Chapter 3: Three Resource Encoding Rules That Trigger 400 Errors

During initial integration testing, most failures stem from reusing legacy ID concatenation patterns. Use the interactive translator below to switch across product writes, single-item status reads, MCQL reports, and GCP registration—comparing v2.1 vs. v1 URLs and JSON payloads and testing special-character SKU encoding:

Merchant API Endpoint Translator

3.1 Hierarchical Resource Identifiers name & parent (AIP-122)

  • Legacy Content API accepted merchantId and productId as separate path parameters. In Merchant API, every entity carries a globally unique hierarchical name path (such as accounts/123456789/products/en~US~SKU-9001).
  • When creating or listing child resources, pass the parent container path in parent (for example, parent = "accounts/123456789").

3.2 Removing channel from Composite Product Keys & Switching : to ~

  • Legacy Composite ID (4 colon-delimited segments): online:en:US:SKU-9001 or local:en:US:SKU-9001
  • New Composite ID (3 tilde-delimited segments): en~US~SKU-9001 (strictly {contentLanguage}~{feedLabel}~{offerId}).
    • Why channel Was Removed: Merchant Center Next unifies online and local product models, removing online and local prefixes from primary keys (for legacy local-only feed migration compatibility, see the legacyLocal note in Part 2: Start Your Migration SOP).
    • Distinguishing feedLabel from targetCountries: The middle segment is the uppercase two-letter or custom data-source feedLabel (e.g., US or US-PROMO), not the list of target countries.

3.3 Mandatory Unpadded RFC 4648 base64url Encoding for Special SKU Characters

Cross-border apparel, auto-parts, and multi-variant catalogs frequently embed punctuation in SKUs. Google mandates encoding whenever the full composite product key (contentLanguage~feedLabel~offerId) contains any of these reserved characters:

  • Characters Requiring Encoding: %, ., +, /, :, two or more ~ characters (i.e., when offerId itself contains ~), ,, (, *, !, ), &, ?, =, @, #, $.
  • Encoding Rule: Encode the entire contentLanguage~feedLabel~offerId string using RFC 4648 Section 5 base64url without trailing = padding (Unpadded). Always encode the full composite string—never encode offerId alone.
    • Invalid Request (returns 400 or 404): accounts/123456/products/en~US~TEE/BLK+XL#1
    • Valid Request (full-string unpadded base64url): Encode en~US~TEE/BLK+XL#1 as ZW5-VVN-VEVFL0JMSytYTCMy (replacing + with -, / with _, and stripping trailing =), then request accounts/123456/products/ZW5-VVN-VEVFL0JMSytYTCMy.

Chapter 4: Data Types, Transport Protocols & New Capability Comparison

Beyond URLs and primary keys, Merchant API introduces major upgrades to numeric precision, transport throughput, and event notifications:

Comparison DimensionLegacy Content API for Shopping (v2.1)New Google Merchant API (v1)Change Summary & Refactoring Notes
Price Structure (Price)Decimal string value: "29.99" + currency: "USD"Integer micros amountMicros: "29990000" + currencyCode: "USD"1 currency unit = 1,000,000 micros; prevents cross-language floating-point rounding drift and aligns with Google Ads API billing units.
Transport ProtocolHTTP/1.1 JSON REST onlySupports both gRPC (HTTP/2 + binary Protobuf) and JSON RESTAdopting gRPC with channel pooling sharply lowers serialization CPU and bandwidth for million-SKU syncs (see Part 4: Concurrent Requests & Channel Pool Guide).
List Pagination Cap (pageSize)Maximum 250 items per page4x higher cap at 1,000 items per pageAuditing 100,000 SKUs drops from 400 paginated round trips to 100.
Click Potential Rank (clickPotentialRank)Unnormalized rank affected by total catalog size fluctuationsNormalized to 1–1000 (1 represents the highest click potential tier)Enables consistent month-over-month SKU potential tracking alongside the June 15 Google Ads Product Reporting Expansion.
Status Change DetectionRelies on scheduled polling of productstatuses.listEvent-driven push via notifications (Pub/Sub)Pushes real-time alerts on disapprovals, price mismatches, or account issues—cutting polling quota usage by ~90%.
Custom Batching (custombatch)Relies on custombatch to bundle requests into one HTTP callcustombatch removed; replaced by async concurrent streams & HTTP multipart/mixedSimplifies per-item retries and idempotent error handling without re-parsing an entire failed envelope.

Chapter 5: AI Agent Endpoints: Official MCP Server & UCP Agentic Performance Reports

Google builds all next-generation Agentic Commerce interfaces exclusively on Merchant API—neither capability exists in legacy Content API.

5.1 Official Managed Merchant API MCP Server

Google introduced a remote, open-protocol Merchant API MCP Server in its developer documentation (endpoint https://merchantapi.googleapis.com/mcp, currently in Alpha preview):

  • How It Works: Engineering and ops agents (such as Gemini CLI, Claude Code, or internal diagnostic agents) do not need custom REST wrappers. Once merchantapi.googleapis.com is enabled with OAuth credentials, connecting to the MCP endpoint lets agents invoke GMC tools in natural language for catalog lookup, disapproval triage, inventory audits, and reporting.
  • Practical Application: Pair the official MCP endpoint with the automated auditing workflows in our SEO & GEO AI Audit Playbook to build daily GMC disapproval monitors that generate remediation patches automatically.

5.2 New ucp_agentic_performance_view Agentic Commerce Report

Previously, across Google AI Mode, Gemini shopping assistants, and Universal Commerce Protocol (UCP) flows, merchants lacked visibility into how often conversational AI assistants recommended their products (see Google UCP Agentic Commerce & Shopify Native Checkout Guide and Google Ads AI-Powered Search Experiences & AI Mode Guide).

Merchant API reports/v1 introduces ucp_agentic_performance_view, allowing MCQL queries by date, offer_id, and surface for AI-agent-driven impressions and clicks:

SQL11 lines
1SELECT
2 date,
3 offer_id,
4 brand,
5 category_l1,
6 impressions,
7 clicks
8FROM ucp_agentic_performance_view
9WHERE date DURING LAST_30_DAYS
10ORDER BY clicks DESC
11LIMIT 100

Combine this view with OpenAI's Businesses in ChatGPT 28-Day Search Insights & Shopify Direct Integration to measure real-time feed impressions and clicks across conversational AI shopping channels.


Chapter 6: Next Steps for Migration Preparation

After reviewing the architecture and the August 18, 2026 sunset deadline, do not jump straight into rewriting production catalog writes. Google requires migrating modules in strict dependency order to prevent data-source ownership conflicts (Offer Stealing).

Proceed to Part 2—Google Merchant API Start Your Migration SOP: Sub-API Priority Order, ProductInput Write/Read Split & Preventing "Offer Stealing"—to follow the four-step migration schedule, ProductInput vs. Product CQRS refactoring, and snake_case MCQL updates.

Google Merchant CenterMerchant APIContent APIGoogle AdsGoogle ShoppingCross-Border E-CommerceShopify & DTCAPI Migration

Found this actionable? Copy standard citation & summary

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