Merchant API in Google Ads Scripts: Apr 22 Migration

Two Dates That Matter

What's Actually Changing

The Merchant API is not a version bump of the Content API. It is a different surface with a different architecture. Three semantic changes matter most:

Sub-API Migration Priority

Google explicitly calls out four sub-APIs as the priority migration targets: Accounts, Products, Data Sources, and Reports. The ranking below extends that to the rest of the Merchant API surface, ordered by typical agency script impact.

Enabling Merchant API in Ads Scripts

Three-step enablement, done once per script project:

1. Link the script project to a Google Cloud project. In the Ads Scripts editor: Project Settings → Google Cloud Platform project → set the project ID. The project needs the Merchant API enabled under APIs & Services.
2. Register the Cloud project with Merchant Center. In Merchant Center: Developer settings → register your Cloud project ID. This is the step that actually grants the script permission to call Merchant API on behalf of the merchant account.
3. Enable the Merchant API Advanced Service in the Ads Scripts editor. Resources → Advanced Google services → toggle on the Merchant API service(s) you need (Products, Inventories, Promotions, etc.). Each sub-API is a separate toggle.

Product Script: Before and After

The most common Shopping script pattern is a daily product fetch to feed a reporting sheet. Here is the full before/after for a hypothetical low-stock alerter.

Content API (legacy)

function lowStockAlert_contentApi() {
  const merchantId = '123456789';
  const products = ShoppingContent.Products.list(merchantId).resources || [];

  const alerts = [];
  for (const p of products) {
    if (p.availability === 'out_of_stock') {
      alerts.push({
        id: p.id,                             // numeric ID
        title: p.title,
        price: parseFloat(p.price.value),     // price is a float string
        currency: p.price.currency,
      });
    }
  }

  Logger.log(`Found ${alerts.length} out-of-stock items.`);
}

Merchant API (new)

function lowStockAlert_merchantApi() {
  const parent = 'accounts/123456789';
  const res = MerchantApiProducts.Accounts.Products.list(parent);
  const products = res.products || [];

  const alerts = [];
  for (const p of products) {
    if (p.productStatus?.destinationStatuses?.some(
      ds => ds.approvalStatus === 'disapproved' ||
            p.availability === 'OUT_OF_STOCK'
    )) {
      alerts.push({
        name: p.name,                                 // resource name
        title: p.attributes?.title,
        priceDollars: Number(p.price.amountMicros) / 1_000_000,  // micros → dollars
        currency: p.price.currencyCode,
      });
    }
  }

  Logger.log(`Found ${alerts.length} out-of-stock items.`);
}

Five things changed: the service namespace, the identifier format (parent is now a resource name), the product shape (many old top-level fields moved into p.attributes), the price arithmetic (divide micros by 1,000,000), and the status enum casing (OUT_OF_STOCK not out_of_stock).

Inventory and Promotions Diffs

Regional inventory update

Content API: Inventory.set with merchant ID, product ID, and region. Merchant API: LocalInventories sub-resource on a product, keyed by store code.

// Content API → Merchant API
// OLD: ShoppingContent.Inventory.set(resource, merchantId, productId)
// NEW:
const name = `accounts/${account}/products/${productId}/localInventories/${storeCode}`;
MerchantApiInventories.Accounts.Products.LocalInventories.insert(
  {
    storeCode: storeCode,
    availability: 'IN_STOCK',
    price: { amountMicros: 4999000000, currencyCode: 'USD' },
    quantity: 42,
  },
  `accounts/${account}/products/${productId}`
);

Promotion insert

// Content API's promotions are now Merchant API's Promotions sub-API.
MerchantApiPromotions.Accounts.Promotions.insert(
  {
    promotionId: 'SPRING26',
    contentLanguage: 'en',
    targetCountry: 'US',
    redemptionChannel: ['ONLINE'],
    couponValueType: 'PERCENT_OFF',
    percentOff: 20,
    promotionDisplayDates: { ... },
  },
  'accounts/123456789'
);

The Shadow-Mode Validation Pattern

Never cut over cold. The reliable pattern: run the old script and the new script side-by-side against the same account for two full reporting cycles, write both outputs to a shared sheet, and diff. Promote only after zero unexplained drift.

function shadowMode() {
  const legacyRows = lowStockAlert_contentApi_returnRows();
  const newRows    = lowStockAlert_merchantApi_returnRows();

  const sheet = SpreadsheetApp.openById('SHEET_ID').getSheetByName('ShadowDiff');
  sheet.appendRow([
    new Date(),
    legacyRows.length,
    newRows.length,
    legacyRows.length - newRows.length,
  ]);

  // Alert if |diff| > 2 across a full day
  const threshold = 2;
  if (Math.abs(legacyRows.length - newRows.length) > threshold) {
    MailApp.sendEmail('alerts@agency.com', 'Shadow diff exceeded',
      `Legacy: ${legacyRows.length}, New: ${newRows.length}`);
  }
}

The 90-Day Rollout Calendar

Common Pitfalls and Fixes

Portfolio-Scale Migration Checklist

For agencies with 20+ client accounts on Shopping, these are the moves that keep the migration from spiraling:

• Inventory all Shopping scripts across the portfolio. Build the list before April 22 — if you find it on August 10 you are too late.
• Group by script template. Most agencies run 5-10 canonical script shapes copied across clients. Port once, reuse across accounts.
• Centralize the migration helper. Write one shared Apps Script library with the price-conversion and resource-name helpers; include it in every migrated script.
• Automate the comparison sheet.One sheet per client, same shadow-mode diff formula, auto-email on delta > 2.
• Communicate rollout windows to clients so a week of shadow-mode weirdness doesn't generate escalations.

Conclusion

The Merchant API is a better surface than the Content API. Modular sub-APIs, push notifications, resource-name consistency with the rest of Google Ads API — all genuine improvements. But the migration is real work, and silent failures after August 18, 2026 will cost agencies orders of magnitude more than the port itself. The agencies we see doing it well started in late April. The calendar above is the fastest safe path.

Frequently Asked Questions