Merchant API Migration: Complete 2026 Cutover Plan

The Merchant API v1 is the successor to the Content API for Shopping that has powered Merchant Center programmatic access since 2014. Google announced the deprecation in 2025 with a hard sunset date of August 18, 2026. After that date, calls to the v2.1 Content API endpoints return errors and any integration that still depends on them stops working.

This guide is the migration playbook we use for our customers: what is changing, what breaks if you do nothing, the endpoint-by-endpoint mapping, the OAuth scope updates, a week-by-week migration plan, and a rollback plan for the day something goes wrong. The full migration takes 1-3 days for standard integrations and up to 2-3 weeks for complex custom builds with their own data pipelines.

What is the Merchant API and why now

The Content API for Shopping was a monolithic API: one auth scope, one set of endpoints, one quota pool. As Google added more functionality (free listings, regional inventory, promotions, advanced reporting, Buy on Google), the monolith became a bottleneck. The Merchant API splits the surface into independent sub-APIs [1]:

• Products sub-API: product feed CRUD, replacing products.* endpoints
• Inventories sub-API: regional inventory and local inventory, replacing regionalinventory.* and localinventory.*
• Accounts sub-API: account info, users, links, replacing accounts.*
• Reports sub-API: a new SQL-like report query interface
• Promotions sub-API: promotional offers, replacing promotions.*
• Quota sub-API: programmatic visibility into rate limits, new functionality
• Notifications sub-API: push notifications for product status changes, new functionality

Each sub-API is versioned independently. Each sub-API has its own OAuth scope. Each sub-API has its own quota pool, which means heavy product updates do not throttle your reporting calls.

Key dates and what happens at each one

What's actually changing under the hood

The Merchant API is not a rename. Five categories of changes matter [2]:

1. Base URL

Old: https://shoppingcontent.googleapis.com/content/v2.1/...

New: https://merchantapi.googleapis.com/products/v1/... (each sub-API has its own subpath)

2. Resource paths use parents

Old: POST /content/v2.1/{merchantId}/products

New: POST /products/v1/accounts/{account}/productInputs

Most resources now require a "parent" path segment naming the account. This is consistent across all Google Cloud APIs and is the biggest source of mechanical migration churn.

3. Field renames

Several common fields were renamed for consistency. Examples:

• offerId → id on the product resource
• contentLanguage → languageCode
• targetCountry → feedLabel (semantics also subtly different)
• Several customAttributes patterns consolidated into typed fields

4. Reports gets a new query language

Reports moves from path-based filters to a SQL-like syntax. Example:

Old: GET /reports/v2.1/{merchantId}/reports?reportType=PRODUCT_PERFORMANCE_VIEW

New:

POST /reports/v1beta/accounts/{account}/reports:search
{
  "query": "SELECT product_view.id, metrics.impressions
            FROM ProductPerformanceView
            WHERE segments.date BETWEEN '2026-01-01' AND '2026-01-31'
            ORDER BY metrics.impressions DESC"
}

5. Notifications is a push-based replacement for polling

Instead of polling products.list for status changes, you subscribe to a Pub/Sub topic and Google pushes notifications when product status changes. This replaces 80% of the polling load most integrations carry today.

Sub-API endpoint mapping (old to new)

Breaking changes most teams miss

Beyond the obvious renames, four breaking changes that surprise teams during cutover:

1. Insert is now upsert by default

In Content API, inserting a product with an existing offerId returned an error. In Merchant API, productInputs.insert upserts: if the resource exists, it is updated. This is more convenient but can mask bugs (you may overwrite data you intended to create-only).

2. Custombatch is gone

The Content API custombatch endpoint that let you send up to 1000 mixed operations in one request is removed. Use the sub-API's standard batch endpoints (one per resource type) instead. Most client libraries handle this transparently, but custom HTTP integrations need rework.

3. Pagination tokens are not interchangeable

Page tokens from the Content API do not work in the Merchant API. If you persist pagination state (background jobs that resume from a token), reset the state at cutover. New tokens are also opaque strings, but the encoding changed.

4. Status enums renamed

Product status values changed from lowercase strings to UPPER_SNAKE_CASE enums. Old: "approved" / "disapproved" / "pending". New: "APPROVED" / "DISAPPROVED" / "PENDING". Any code that compares status strings exactly needs an update.

Auth changes: OAuth scope updates

The Content API used a single broad scope: https://www.googleapis.com/auth/content. The Merchant API uses per-sub-API scopes [4]:

In practice, the content scope still works across all sub-APIs during the transition. Google has signaled that the scope will narrow post-cutover, but as of May 2026 the broad scope is still supported. Plan for narrower scopes in late 2026.

Migration plan, week by week

For a standard integration (Shopify/Woo plugin or feed-management tool), 4 weeks is sufficient with comfortable validation time. Custom enterprise integrations need 6-8 weeks.

Week 1: Inventory and read

1. Inventory every Content API call in your codebase. Group by sub-API target.
2. Install the new Merchant API client library [5] alongside the existing one.
3. Build a read-only proof of concept against the new API. Verify product list + status endpoints return matching data.

Week 2: Write parity

1. Implement write endpoints (product upsert, inventory update, etc.) against the new API.
2. Run mirror writes: every Content API write also writes to the new API. Validate parity by listing products from both APIs and comparing.
3. Update OAuth consent screen to declare the new scopes. Re-request user consent and refresh tokens.

Week 3: Reports and notifications

1. Rewrite report queries in the new SQL-like syntax. Validate that historical numbers match.
2. Set up Pub/Sub topic and notifications subscription. Replace polling-based status checks with push notifications.
3. Update your warehouse pipeline if you have a BigQuery export.

Week 4: Cutover and validation

1. Switch all reads to the new API. Keep writes mirrored for 1 more week to allow rollback.
2. Run end-to-end validation: create a test product, verify it appears in Shopping, update inventory, verify update propagates, delete it.
3. Monitor error rates and quota usage on the new API for 7 days.
4. If all green, disable the Content API writes. Migration complete.

Verification checklist before cutover

Before flipping the read switch, confirm every item:

• Mirror-write parity at 100% (no missing products, identical status)
• OAuth flow tested end-to-end with the new scopes
• Report query results match historical Content API results within 0.1%
• Notifications subscription delivers events end-to-end
• Quota usage on the new API is below 80% of allocated limit [6]
• Error monitoring dashboards updated to track new endpoint paths
• Rollback script tested in staging
• Customer-facing documentation updated

Rollback plan if something breaks

Until 2026-08-18, the Content API still works, so rollback is always possible. Three-step rollback:

1. Feature flag the API choice. One environment variable that toggles between Content API and Merchant API. This is the cheapest insurance you can buy.
2. Keep both client libraries installed. Removing the old library before 60 days post-cutover is a code-velocity trap that has bitten teams we work with.
3. Keep mirror writes on for 2 weeks post-cutover. If a customer reports a problem you cannot reproduce, you can re-read from the Content API and compare.

If rollback happens, document what failed. The Content API will still be off by August 18, 2026, so understanding what failed in your migration is the only path to a successful second attempt.

What we are doing for our customers

FeedShield's integration with Merchant Center went through this migration in March 2026. Our customers do not need to take action; the new API is already powering audits, sync, and reporting. The migration we ran:

1. Inventory: 14 Content API endpoints, 6 sub-APIs in scope
2. Mirror-write window: 6 weeks (longer than the recommended 4 because we have customers across timezones and wanted a wider validation surface)
3. Cutover: completed 2026-04-09
4. Issues found in cutover: 2 minor pagination edge cases, 1 enum mismatch on a rare product status, all resolved within 24 hours

Bottom line

The Merchant API migration is one of the rare deprecation cycles where Google has been clear, the documentation is complete, and the new API is genuinely better. The hard part is the work of mapping endpoints, updating auth scopes, rewriting reports, and validating parity. Allocate 4 weeks for a standard integration, 6-8 for a complex one, and complete the migration by 2026-06-30 to leave 6 weeks of buffer before the August 18 hard cutoff.