Google Merchant API Architecture Guide: Replacing Content API for Shopping, 2026 Sunset Timeline & Modular Upgrade Plan
Google 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:
- Part 1 (Current): Google Merchant API Architecture Guide: Replacing Content API for Shopping, 2026 Sunset Timeline & Modular Upgrade Plan
- Part 2: 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: 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 Date | Official Gateway Behavior | Impact on Campaigns & GMC Product Feeds |
|---|---|---|
| Now – August 17, 2026 | Hybrid 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, 2026 | Official 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, 2026 | Progressive 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 2027 | Full 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 & YouTubeapp 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:
- In-house ERP or warehouse services calling
shoppingcontent.googleapis.comon a schedule to update real-time inventory or tiered pricing.- 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).- Internal BI data warehouses pulling Free Listings and Shopping Ads competitiveness reports via MCQL.
- 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 Version | Core Responsibilities & Replaced Legacy Modules | Typical Production Use Cases |
|---|---|---|---|
accounts | v1 | Handles 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. |
datasources | v1 | Replaces 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. |
products | v1 | Split 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. |
inventories | v1 | Manages 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. |
reports | v1 | Powers 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. |
promotions | v1 | Creates and retrieves promotional coupon codes, BOGO/tiered discounts, and promotion review statuses. | Syncing sitewide BFCM promo codes to Google Shopping badges at scale. |
notifications | v1 | New capability: configures Cloud Pub/Sub or Webhook push subscriptions (NotificationSubscription). | Real-time alerting when hero SKUs are disapproved or change review state, eliminating polling. |
quota | v1 | Inspects daily quota totals, consumed usage, and per-minute burst limits per QuotaGroup. | Adaptive rate limiting across distributed sync workers. |
lfp / issueresolution / ordertracking / reviews | v1 / v1beta | Covers 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:
3.1 Hierarchical Resource Identifiers name & parent (AIP-122)
- Legacy Content API accepted
merchantIdandproductIdas separate path parameters. In Merchant API, every entity carries a globally unique hierarchicalnamepath (such asaccounts/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-9001orlocal:en:US:SKU-9001 - New Composite ID (3 tilde-delimited segments):
en~US~SKU-9001(strictly{contentLanguage}~{feedLabel}~{offerId}).- Why
channelWas Removed: Merchant Center Next unifies online and local product models, removingonlineandlocalprefixes from primary keys (for legacy local-only feed migration compatibility, see thelegacyLocalnote in Part 2: Start Your Migration SOP). - Distinguishing
feedLabelfromtargetCountries: The middle segment is the uppercase two-letter or custom data-sourcefeedLabel(e.g.,USorUS-PROMO), not the list of target countries.
- Why
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., whenofferIditself contains~),,,(,*,!,),&,?,=,@,#,$. - Encoding Rule: Encode the entire
contentLanguage~feedLabel~offerIdstring using RFC 4648 Section 5base64urlwithout trailing=padding (Unpadded). Always encode the full composite string—never encodeofferIdalone.- Invalid Request (returns 400 or 404):
accounts/123456/products/en~US~TEE/BLK+XL#1 - Valid Request (full-string unpadded
base64url): Encodeen~US~TEE/BLK+XL#1asZW5-VVN-VEVFL0JMSytYTCMy(replacing+with-,/with_, and stripping trailing=), then requestaccounts/123456/products/ZW5-VVN-VEVFL0JMSytYTCMy.
- Invalid Request (returns 400 or 404):
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 Dimension | Legacy 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 Protocol | HTTP/1.1 JSON REST only | Supports both gRPC (HTTP/2 + binary Protobuf) and JSON REST | Adopting 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 page | 4x higher cap at 1,000 items per page | Auditing 100,000 SKUs drops from 400 paginated round trips to 100. |
Click Potential Rank (clickPotentialRank) | Unnormalized rank affected by total catalog size fluctuations | Normalized 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 Detection | Relies on scheduled polling of productstatuses.list | Event-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 call | custombatch removed; replaced by async concurrent streams & HTTP multipart/mixed | Simplifies 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.comis 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:
| 1 | SELECT |
| 2 | date, |
| 3 | offer_id, |
| 4 | brand, |
| 5 | category_l1, |
| 6 | impressions, |
| 7 | clicks |
| 8 | FROM ucp_agentic_performance_view |
| 9 | WHERE date DURING LAST_30_DAYS |
| 10 | ORDER BY clicks DESC |
| 11 | LIMIT 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.
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.