Content API i Merchant API - automatyczna integracja z Merchant Center

Merchant API to interfejs programistyczny Google, który pozwala zarządzać kontem Google Merchant Center i danymi produktowymi bez logowania do panelu. Zastępuje starsze Content API for Shopping i rozbija jego funkcje na wyspecjalizowane sub-API: produkty, konta, źródła danych, zapasy, promocje, zwroty i raporty. Google podaje w dokumentacji Merchant API, że Content API for Shopping zostanie wyłączone 18 sierpnia 2026, więc każda integracja oparta na starym endpoincie wymaga przepisania.

Większość sklepów, które audytuję, wgrywa dane do Merchant Center plikiem XML pobieranym raz na dobę. Działa to do momentu, w którym ceny zaczynają się zmieniać częściej niż raz dziennie, magazyn schodzi do zera w środku dnia, a Merchant Center wyrzuca ostrzeżenia o niezgodności ceny między feedem a witryną. Wtedy pojawia się pytanie o integrację przez API. I właśnie w tym momencie sprzedawcy trafiają na dwie nazwy, które łatwo pomylić: Content API for Shopping oraz Merchant API. Jedna z nich ma datę wyłączenia.

Czym jest Merchant API i co zastępuje w Merchant Center?

Merchant API to zestaw interfejsów REST, którymi program po stronie sklepu wykonuje w Google Merchant Center te same operacje co człowiek w panelu: dodaje produkty, zmienia ceny i dostępność, konfiguruje źródła danych, ustawia dostawę oraz czyta raporty o ofertach.

Różnica wobec pliku z feedem jest zasadnicza i warto ją zrozumieć, zanim zaczniesz cokolwiek programować. Plik to fotografia katalogu z konkretnej godziny, którą Google pobiera według harmonogramu. Merchant API to połączenie, w którym sklep sam decyduje, kiedy wysłać zmianę. Jedna zmieniona cena to jedno żądanie, wysłane w sekundzie, w której ta cena faktycznie się zmieniła.

Zakres Merchant API pokrywa niemal cały panel Merchant Center, a nie tylko katalog produktów. Programowo obsłużysz:

• Produkty: dodawanie, aktualizacja i usuwanie ofert oraz odczyt statusu przetworzonej oferty wraz z problemami jakości danych.
• Konta: zakładanie kont i subkont, zarządzanie użytkownikami i uprawnieniami, weryfikacja adresu witryny, zgłaszanie do programów.
• Źródła danych: tworzenie źródeł podstawowych i suplementarnych, wiązanie ich ze sobą, wymuszanie pobrania pliku i sprawdzanie statusu przetwarzania.
• Zapasy: stany lokalne i regionalne, czyli dane pod reklamy asortymentu lokalnego i bezpłatne wizytówki lokalne.
• Promocje, opinie i zwroty: oferty specjalne, opinie o produktach i sprzedawcy oraz polityki zwrotów przypisane do konta.
• Raporty i diagnostykę: dane o skuteczności ofert, otoczeniu konkurencyjnym oraz problemach konta wraz z akcjami naprawczymi znanymi z panelu.

Zanim zaczniesz planować integrację, upewnij się, że rozumiesz samo narzędzie, którym ta integracja steruje - podstawy panelu i jego możliwości opisuję w przewodniku po Merchant Center. Merchant API nie naprawia źle skonfigurowanego konta, tylko przyspiesza to, co konto i tak robi.

Czym Merchant API różni się od Content API for Shopping?

Merchant API różni się od Content API for Shopping adresem bazowym, sposobem adresowania zasobów, zapisem ceny w mikrojednostkach, brakiem żądań zbiorczych customBatch oraz podziałem jednego monolitycznego interfejsu na kilkanaście sub-API. To nie jest kosmetyczna zmiana wersji, tylko inny model danych.

Największą pułapką techniczną jest zapis ceny. W Merchant API kwota trafia do pola amountMicros jako liczba całkowita w mikrojednostkach waluty, czyli 149,99 zł to 149990000. Widziałem integracje, w których programista przeniósł logikę jeden do jednego i katalog wjechał do Merchant Center z cenami zawyżonymi milion razy. Konto złapało wtedy masowe odrzucenia na niezgodność ceny w ciągu kilkunastu minut.

Kiedy Content API for Shopping przestaje działać?

Google podaje w dokumentacji Merchant API, że Content API for Shopping zostanie wyłączone 18 sierpnia 2026. Do tego dnia stara integracja działa normalnie, po nim żądania kierowane do endpointu content/v2.1 przestają być obsługiwane, a sklep traci programowy kanał aktualizacji danych.

Google przewidział furtkę dla spóźnionych. W komunikacie o wygaszeniu, który wyświetla się na każdej stronie dokumentacji Merchant API, jest odnośnik do wniosku o przedłużony dostęp do Content API for Shopping. Traktuj to jako awaryjne przedłużenie terminu, nie jako alternatywę dla migracji - wniosek kupuje czas, ale nie zmienia kierunku.

Kto musi migrować, a kogo migracja nie dotyczy?

Migracja dotyczy wyłącznie sklepów, które mają własny kod wywołujący Content API for Shopping. Jeśli dane produktowe synchronizuje partner technologiczny lub wtyczka platformy sklepowej, przepisanie integracji leży po stronie dostawcy, a Google mówi o tym wprost w przewodniku migracyjnym.

Rozstrzygnięcie zajmuje kilka minut. Zajrzyj do Merchant Center w sekcję źródeł danych i sprawdź, jak nazywa się źródło zasilające katalog oraz kto jest jego właścicielem.

• Musisz migrować, jeśli produkty wgrywa autorski skrypt, integracja napisana na zamówienie albo własne narzędzie ERP wywołujące content/v2.1.
• Musisz migrować, jeśli obsługujesz cudze konta jako agencja lub dostawca oprogramowania i to Twój projekt Google Cloud stoi za wywołaniami.
• Nie musisz migrować, jeśli katalog synchronizuje aplikacja partnera, na przykład Google & YouTube na Shopify albo dedykowana wtyczka platformy.
• Nie musisz migrować, jeśli zasilasz Merchant Center wyłącznie plikiem XML, arkuszem Google albo pobieraniem z adresu URL - te metody nie korzystają z Content API for Shopping.

Ostatni punkt jest źródłem nieporozumień, które widzę regularnie. Sprzedawca czyta o wygaszeniu Content API, panikuje i szuka programisty, choć jego katalog od lat jedzie zwykłym plikiem z feedem produktowym pobieranym z adresu URL. Taka konfiguracja jest całkowicie poza zasięgiem tej zmiany.

Jak uruchomić dostęp do Merchant API krok po kroku?

Uruchomienie dostępu do Merchant API składa się z pięciu kroków opisanych w oficjalnym przewodniku startowym Google: konto Merchant Center, projekt Google Cloud, uwierzytelnianie, rejestracja dewelopera i wysłanie pierwszego produktu. Kolejność ma znaczenie, bo każdy kolejny etap wymaga zasobu z poprzedniego.

1. Załóż lub wskaż konto Merchant Center i zanotuj jego identyfikator - to on będzie częścią ścieżki każdego zasobu w wywołaniach.
2. Utwórz projekt Google Cloud na firmowym koncie, nie na prywatnym adresie wykonawcy, i włącz w nim Merchant API.
3. Skonfiguruj uwierzytelnianie - OAuth 2.0 dla integracji działających w imieniu użytkownika lub konto usługi dla procesów serwerowych bez interakcji.
4. Zarejestruj się jako deweloper, łącząc konto Merchant Center z projektem Google Cloud metodą developerRegistration:registerGcp z podaniem adresu e-mail dewelopera.
5. Utwórz źródło danych typu API i wyślij pierwszy produkt przez zasób ProductInput, a następnie odczytaj przetworzoną ofertę zasobem Product.

Krok czwarty jest nowy względem Content API for Shopping i regularnie umyka zespołom, które przenoszą starą integrację. Bez rejestracji dewelopera powiązanie konta z projektem Google Cloud nie istnieje i żadne żądanie nie przejdzie, nawet z poprawnym tokenem. Uważam, że to najczęstsza przyczyna kilkugodzinnego szukania błędu w miejscu, w którego wcale nie ma.

Warto też od razu ustalić model uwierzytelniania. Konto usługi upraszcza automaty działające w nocy, bo nie wymaga odświeżania tokenu przez użytkownika, ale wymaga świadomego nadania mu dostępu do konta Merchant Center. OAuth 2.0 lepiej pasuje do narzędzi, w których wiele sklepów loguje się własnymi kontami.

Sub-API Merchant API: co da się zautomatyzować

Merchant API jest podzielone na sub-API odpowiadające obszarom panelu Merchant Center, a każde ma własną wersję i własny zestaw zasobów. Dzięki temu integracja obsługująca tylko ceny nie musi znać modelu danych zwrotów ani promocji.

Najważniejsze pojęcie w całym Merchant API to rozdział między ProductInput a Product. ProductInput jest tym, co wysyłasz: surowym wierszem danych przypisanym do konkretnego źródła. Product jest tym, co Google zwraca po przetworzeniu: ofertą zbudowaną z jednego wejścia podstawowego, dowolnej liczby wejść suplementarnych i wszystkich reguł feedu, razem ze statusem i listą problemów jakości danych.

Ten podział rozwiązuje realny problem diagnostyczny. Wcześniej, patrząc na ofertę w panelu, trudno było rozstrzygnąć, czy dziwna wartość atrybutu pochodzi z pliku, z reguły feedu, czy z automatycznych ulepszeń Google. Teraz jedno wywołanie pokazuje wejście, drugie wynik. Jeśli walczysz z jakością danych, to samo podejście warto przenieść na cały katalog - szerzej piszę o tym przy optymalizacji feedu produktowego. Jeśli chcesz sprawdzić, ile Twoich odrzuceń wynika z samych danych, a ile z konfiguracji konta, to dokładnie ten wątek analizuję podczas audytu Merchant Center.

Kiedy integracja przez API opłaca się bardziej niż plik z feedem?

Integracja przez Merchant API opłaca się wtedy, gdy dane w sklepie zmieniają się częściej niż Google pobiera plik, a koszt błędnej ceny lub fałszywej dostępności przewyższa koszt utrzymania kodu. Poniżej tego progu plik XML pobierany z adresu URL jest rozwiązaniem tańszym i stabilniejszym.

Nie ma tu jednej granicy liczby produktów, choć branża lubi ją podawać. Znaczenie ma zmienność, nie rozmiar katalogu. Sklep z 40 tysiącami książek o stałych cenach spokojnie żyje na pliku. Sklep z 900 produktami, w którym ceny chodzą za kursem hurtowni kilka razy dziennie, traci pieniądze na każdej godzinie opóźnienia.

• Częstotliwość zmian: ceny lub stany magazynowe zmieniają się częściej niż raz na dobę, a plik pobierany jest raz dziennie.
• Koszt rozjazdu: Merchant Center regularnie odrzuca oferty na niezgodność ceny lub dostępności między feedem a witryną.
• Skala operacyjna: obsługujesz wiele kont lub subkont i ręczna konfiguracja każdego z nich zajmuje więcej czasu niż napisanie automatu.
• Potrzeba diagnostyki: chcesz wciągać statusy ofert i problemy jakości danych do własnego raportu, zamiast klikać po panelu.
• Krótkie promocje: prowadzisz akcje kilkugodzinne, przy których czekanie na kolejne pobranie pliku zjada połowę okna sprzedażowego.

Marek, właściciel sklepu z częściami motoryzacyjnymi, zgłosił się z problemem powtarzających się odrzuceń na niezgodność ceny. Hurtownia zmieniała ceny średnio cztery razy dziennie, a feed jechał raz na dobę o czwartej rano. Po przejściu na aktualizację cen przez API czas propagacji zmiany spadł z 19 godzin do 8 minut, a liczba ostrzeżeń o niezgodności ceny zeszła z 214 do 6 w ciągu trzech tygodni. Katalog został ten sam - zmienił się tylko kanał dostarczania danych.

Uważam jednocześnie, że API bywa przereklamowane jako lekarstwo na wszystko. Kiedyś zakładałem, że integracja programowa zawsze wygrywa z plikiem. Po kilku wdrożeniach zmieniłem zdanie: sklep bez zaplecza technicznego, który wdroży API i zostanie bez osoby utrzymującej kod, jest w gorszej sytuacji niż sklep na porządnie skonfigurowanym pliku. Awaria pliku jest widoczna od razu, cicha awaria integracji potrafi trwać tygodniami.

Najczęstsze błędy migracji z Content API for Shopping

Najczęstsze błędy migracji do Merchant API nie wynikają z trudnej dokumentacji, tylko z założenia, że nowy interfejs jest kolejną wersją starego. Cztery pomyłki powtarzają się w niemal każdym wdrożeniu, które oglądałem, i wszystkie mają ten sam rodowód.

• Cena przeniesiona bez konwersji: pole amountMicros przyjmuje mikrojednostki, więc brak mnożenia przez milion daje ceny zawyżone lub zaniżone o sześć rzędów wielkości.
• Utrzymywanie logiki customBatch: Merchant API nie ma odpowiednika tej metody, a próba wysłania paczki żądań w starym formacie kończy się błędem, nie degradacją do pojedynczych wywołań.
• Adresowanie po liczbowym identyfikatorze: zasoby adresuje się pełną ścieżką w polu name, a operacje na zasobach podrzędnych wymagają wskazania zasobu nadrzędnego w polu parent.
• Pominięta rejestracja dewelopera: bez powiązania konta Merchant Center z projektem Google Cloud metodą registerGcp uwierzytelnienie przechodzi, ale wywołania biznesowe nie.
• Brak źródła danych przed wysyłką: ProductInput musi trafić do istniejącego źródła typu API, którego nie tworzy się automatycznie przy pierwszym żądaniu.
• Testy prowadzone na koncie produkcyjnym: błędna partia danych w katalogu obsługującym kampanie potrafi wywrócić emisję na kilka godzin, zanim ktokolwiek zauważy problem.

Ile trwa migracja i kto powinien ją przeprowadzić?

Migracja prostej integracji obsługującej wyłącznie produkty i ceny to zwykle od kilku do kilkunastu dni roboczych programisty, licząc z testami na koncie zapasowym. Rozbudowane wdrożenia, które dotykają kont, promocji, zapasów lokalnych i raportowania, rozciągają się na kilka tygodni, bo każdy obszar ma osobne sub-API i osobny model danych.

Podział ról jest w tym projekcie dość naturalny i warto go ustalić na starcie, żeby nikt nie czekał na nikogo.

• Programista zaplecza sklepu: przepisuje wywołania, obsługuje uwierzytelnianie, buduje kolejkę wysyłki i logowanie błędów.
• Osoba prowadząca Merchant Center: definiuje źródła danych, weryfikuje zakres atrybutów i pilnuje, żeby migracja nie zmieniła zawartości katalogu.
• Specjalista od kampanii produktowych: monitoruje liczbę zatwierdzonych ofert i emisję w dniach przełączenia, bo to tam najszybciej widać cichy błąd integracji.
• Właściciel projektu Google Cloud: odpowiada za to, żeby projekt należał do firmy, a nie do zewnętrznego wykonawcy.

W mojej codziennej praktyce widzę, że najdroższym elementem nie jest kod, tylko brak osoby, która po stronie biznesu potrafi powiedzieć, jak katalog ma wyglądać. Programista przepisze wywołania w tydzień. Ustalenie, skąd bierze się cena promocyjna i które warianty w ogóle mają trafiać do Google, potrafi zająć dłużej niż cała warstwa techniczna. Jeśli rozpoznajesz ten wzorzec u siebie, to jest moment na zewnętrzne spojrzenie na konfigurację konta, zanim ruszą prace deweloperskie.

Limity, diagnostyka i monitoring wywołań Merchant API

Merchant API udostępnia w Merchant Center diagnostykę API, która pokazuje, jak konto korzysta z interfejsu: ile żądań przechodzi, które kończą się błędem i z jakiego powodu. To pierwsze miejsce, do którego zaglądam, gdy integracja przestaje odświeżać dane, a nikt nie zgłosił awarii.

Poza panelem odpowiedzialność za monitoring leży po stronie sklepu i tu popełnia się najwięcej zaniedbań. Integracja, która wysyła dane w nocy i nikomu nie raportuje wyniku, jest bombą z opóźnionym zapłonem. Minimalny zestaw zabezpieczeń wygląda tak:

• Ponawianie z odstępem rosnącym: błędy przejściowe i odpowiedzi o przekroczeniu limitu obsługuj ponowieniem z wydłużanym opóźnieniem, nie natychmiastowym powtórzeniem w pętli.
• Alert od liczby przetworzonych ofert: spadek liczby zatwierdzonych produktów o kilkanaście procent z dnia na dzień to sygnał wcześniejszy niż jakikolwiek raport sprzedażowy.
• Log odpowiedzi, nie tylko żądań: zapisuj treść błędu zwróconego przez Merchant API, bo komunikaty wskazują konkretny atrybut i konkretne źródło danych.
• Cykliczny odczyt zasobu Product: porównanie tego, co wysłałeś, z tym, co Google przetworzył, wyłapuje reguły feedu działające inaczej, niż zakładałeś.

Warto też zaplanować, co się dzieje przy pełnym przeładowaniu katalogu. Wysyłka dziesiątek tysięcy ofert jednym ciągiem żądań to najszybszy sposób na uderzenie w limity i nierówne przetwarzanie. Rozłożenie takiej operacji w czasie oraz oddzielenie codziennej aktualizacji cen od rzadkiego pełnego przeładowania rozwiązuje problem zanim się pojawi.

Podsumowanie

Merchant API nie jest kolejną wersją Content API for Shopping, tylko innym sposobem opisania tego samego konta: zasoby mają pełne nazwy, ceny idą w mikrojednostkach, a funkcje panelu rozeszły się po wyspecjalizowanych sub-API. Data 18 sierpnia 2026 wyznacza koniec starego interfejsu, więc każdy sklep z własnym kodem wywołującym content/v2.1 ma do wykonania konkretną, policzalną pracę.

Przestań traktować integrację z Merchant Center jak jednorazowe podłączenie feedu. Zacznij ją postrzegać jako element infrastruktury sklepu, który wymaga właściciela, monitoringu i planu utrzymania - dokładnie tak samo jak system płatności czy integracja z kurierem. Sklep, który ma to poukładane, wychodzi z migracji w tydzień. Sklep, który przez lata nie wiedział, kto właściwie utrzymuje ten skrypt, spędza na tym miesiąc.

Jeśli Twoja integracja jedzie jeszcze na starym endpoincie, zacznij od inwentaryzacji wywołań i sprawdzenia, czyj projekt Google Cloud za nimi stoi. To dwie godziny pracy, które zdejmują z projektu największą niewiadomą. Reszta jest już zwykłym, przewidywalnym przepisywaniem kodu według dokumentacji.

Samodzielny Specjalista Google Ads

Artur Smolicki

Od ponad 15 lat specjalizuję się w przygotowaniu, wdrożeniu i optymalizacji kampanii Google Ads. W 2024 roku uzyskałem status Google Premier Partner dla 3% najlepszych specjalistów i agencji w Polsce. Prowadzę kampanie reklamowe na 29 rynkach zagranicznych, tak dla segmentu e-commerce jak i B2B.

Współpraca →Poznaj mnie →