Migrare da Content API alla Merchant API di Google (entro agosto 2026)

Google sta spegnendo la Content API for Shopping e la sostituisce con la nuova Merchant API. Non è un aggiornamento opzionale: chi invia i prodotti a Google Merchant Center in modo programmatico deve migrare, altrimenti i prodotti smettono di aggiornarsi e spariscono dai risultati di Shopping. Questa guida spiega cosa cambia e come pianificare la migrazione senza interruzioni.

Le scadenze da segnare subito

Due date contano davvero. La versione v1beta della Merchant API è stata dismessa il 28 febbraio 2026; la vecchia Content API for Shopping viene spenta definitivamente il 18 agosto 2026, senza periodo di transizione successivo. Dopo quella data, le integrazioni non migrate semplicemente non funzionano più.

Cosa cambia: da monolite a sotto-API modulari

La Merchant API è una riprogettazione della Content API: invece di un'unica interfaccia monolitica, espone sotto-API specializzate, ciascuna con il proprio ciclo di vita. Questo rende il codice più chiaro ma richiede di rimappare le chiamate esistenti.

Sotto-API	A cosa serve
Products	Inserimento e gestione dei dati di prodotto
Inventories	Disponibilità e prezzi locali, regionali e supplementari
Accounts	Configurazione account, utenti e impostazioni
Datasources	Gestione di più sorgenti dati per account
Reports	Reportistica e diagnostica avanzata

Le differenze tecniche che impattano il codice

• Niente customBatch: il metodo batch della Content API non esiste più. Le operazioni multiple si inviano insieme o si eseguono in modo asincrono.
• Concetto di datasource esplicito: i prodotti caricati via API vivono in una sorgente dati dedicata, separata dai feed a file.
• Autenticazione OAuth 2.0 / service account come prima, ma con i nuovi scope della Merchant API.
• Librerie client aggiornate: Google consiglia di adottarle per accelerare la migrazione ed evitare di gestire a mano gli endpoint REST.

Come pianificare la migrazione, passo per passo

• inventaria le chiamate Content API attuali (prodotti, inventario, account) e mappale sulle sotto-API corrispondenti;
• introduci la gestione delle datasource per i prodotti caricati via API;
• sostituisci i customBatch con invii multipli o flussi asincroni;
• esegui in parallelo (dual-write) finché non hai validato i risultati su Merchant Center;
• taglia la Content API ben prima del 18 agosto 2026, non all'ultimo.

L'impatto sull'architettura del feed

La migrazione è l'occasione giusta per pulire la pipeline. Se generi i prodotti da ERP o PIM, conviene mantenere un punto unico che produce il modello canonico e poi pubblica verso la Merchant API: lo stesso principio descritto nell'architettura di un feed prodotto multicanale. Per la pipeline schedulata da ERP a Merchant Center resta valido quanto visto nella guida su come sincronizzare il feed verso Google Merchant Center, e la qualità dei dati continua a dipendere da come ottimizzi gli attributi del feed.

Mappatura concreta delle chiamate

Il lavoro iniziale non è scrivere codice nuovo, ma costruire una tabella di equivalenza tra chiamate legacy e nuova responsabilità. In un audit tipico parto così:

Content API	Merchant API	Nota operativa
products.insert	Products sub-API	richiede datasource coerente con il canale di caricamento
products.custombatch	invii multipli + coda	non replicare il batch sincrono: gestisci retry per singolo item
inventory.set	Inventories sub-API	separa prezzo/availability dal dato prodotto stabile
accounts.*	Accounts sub-API	verifica permessi e scope OAuth prima del cutover

Runbook di dual-write

1. crea datasource Merchant API in ambiente controllato e salva l'id nel config store;
2. scrivi su Content API e Merchant API per un sottoinsieme di SKU a basso rischio;
3. confronta stato, disapprovazioni e tempi di propagazione in Merchant Center;
4. abilita il dual-write per una categoria intera, mantenendo un flag di rollback;
5. quando gli errori sono stabili, spegni Content API e lascia solo il monitoraggio Merchant API.

{
  "sku": "ERP-12345",
  "legacyContentApiStatus": "accepted",
  "merchantApiStatus": "accepted",
  "datasourceId": "accounts/123/dataSources/456",
  "lastComparedAt": "2026-06-21T08:30:00Z"
}

Errori comuni

• rimandare la migrazione fino a ridosso della scadenza, senza margine per i test;
• riprodurre customBatch uno-a-uno invece di ripensare il flusso in chiave asincrona;
• dimenticare di rimappare gli scope OAuth e i permessi account;
• migrare il codice ma non monitorare le disapprovazioni dopo lo switch.

Conclusione

La Merchant API non è solo un rename: è un modello modulare che, una volta adottato, rende l'integrazione con Google più pulita e manutenibile. Il rischio vero è la scadenza: pianifica ora, esegui in dual-write e taglia la Content API con anticipo. Riferimenti utili: la panoramica della Merchant API e la guida ufficiale alla migrazione.