Google Merchant Center Sync for OpenCart

Overview

Google, Google Merchant Center and Google Shopping are trademarks of Google LLC. This extension is not affiliated with or endorsed by Google.

Sends your OpenCart 4.1 catalogue to Google Merchant Center through the Merchant API (the successor of the Content API for Shopping, which reached its sunset on 2026-08-18 and is being shut down) and, as a fallback, serves a scheduled Google Shopping XML / TSV feed that follows Google's product data specification. Prices, stock and status changes reach Google within minutes, and Google's own issues are listed in your admin. OpenCart 4, events only, no OCMOD, no core file changed.

What it does

• Merchant API sync. Products are sent as product inputs into an API data source per country and language (target): full sync first, then every price, stock, status and text change, in small batches, with safe retries (a lost answer never creates a copy). Disabled, excluded and deleted products are removed from Google.
• Your own Google Cloud project. Sign in with OAuth 2.0 (with PKCE) or use a service account key. Secrets are stored encrypted and masked in the log. Google sends you back through a small page of the extension, so you stay signed in to your admin (OpenCart 4.1 keeps its session cookie strictly same-site).
• Developer registration in one click. Every Cloud project must be registered once for the Merchant API; the Connection page does it and shows the state.
• Targets. One target per country, language and currency (multi-currency and multi-language), with tax and shipping hints, a category filter and "exclude out of stock".
• Mapping. GTIN (EAN, UPC, JAN, ISBN), MPN (the MPN code; SKU or model as an explicit choice), brand (manufacturer), condition, colour, size, gender and age group from product attributes, fields or fixed values; your categories mapped to the Google product taxonomy with a search box.
• Per-product exclusions and overrides. Exclude a product or override its title, Google category, identifiers, condition, colour, size, gender and age group.
• Sale prices with dates. OpenCart specials become salePrice with the effective interval, in your shop's time zone.
• Variants. OpenCart 4 variant products share the master product's id as item_group_id.
• Status and issues from Google. Approved, pending, partly approved and disapproved counts per target, and every item level issue with Google's description, severity, attribute and help link.
• Fallback feed. XML and TSV files per target behind a secret address, rebuilt by cron in batches and moved into place only when complete.
• Queue and cron guard. Jobs with retries and back-off (a 429 waits as long as Google asks), one run at a time, a cron address that refuses requests without its key.

Updates keep your data

Updating the extension (OpenCart 4.1 updates are uninstall plus install) keeps your targets, mapping, overrides, credentials, settings and licence. Uninstalling never deletes tables.

Pages

Version

1.0.0, OpenCart 4.1.0.0 - 4.1.x (tested on 4.1.0.4). There is no OpenCart 3 edition. Tested against a stand-in of the Merchant API built from Google's documentation, not against a live Merchant Center account.

Installation and setup

Requirements

• OpenCart 4.1.0.0 - 4.1.x (tested on 4.1.0.4), PHP 8.1 or later, administrator access.
• A Google Merchant Center account (a production account with a verified website; test accounts cannot register for the Merchant API) and a Google Cloud project of your own.
• Your shop on https (Google sends you back to an https address).
• The OpenCart cron (System > Maintenance > Cron Jobs runs when your host calls cron.php, for example every 5 minutes), or the web address shown on the overview page.

Install

1. Extensions > Installer: upload kv_google_merchant.ocmod.zip.
2. Extensions > Extensions > Modules: install Google Merchant Center Sync. Events, the cron job and the admin permissions are created.
3. Open Marketing > Google Merchant.

Connect (OAuth 2.0)

1. In Google Cloud console create or pick a project and enable the Merchant API.
2. APIs and services > OAuth consent screen: set it up (internal or external, add yourself as a test user while it is in testing).
3. Credentials > Create credentials > OAuth client ID > Web application. Under Authorized redirect URIs add the address shown on the Connection page (https://your-shop/extension/kv_google_merchant/return.php).
4. On the Connection page enter the Merchant Center ID, the client ID and the client secret, then click Authorize with Google and agree. You come back to the admin and the page shows the connection.
5. Click Register API access. Google needs about 5 minutes before calls work. Registration needs administrator access to the Merchant Center account.

Connect (service account)

1. In the same Cloud project create a service account and download its JSON key.
2. In Merchant Center, Settings > Access and services, add the service account's e-mail address as a user with administrator access.
3. On the Connection page choose Service account, paste the JSON key (it is stored encrypted and never shown again) and click Save and test.

Create a target

Targets > Add target: name, store, language, the two-letter content language, the feed label (usually the country code, for example US), the country, the currency, tax and shipping hints. Save and run a full sync. The first push creates the API data source for you.

Keep Google from receiving the same offer twice

Use the extension as the channel for a country and language, not next to another feed or app for the same one. If ANOTHER feed or app feeds the same country and language, set an offer ID prefix in the settings so the offer ids differ.

Configuration

Settings (Extensions > Modules > Google Merchant Center Sync, or the gear on the extension pages)

Target fields

Mapping

• Attributes. Per attribute (GTIN, MPN, brand, condition, colour, size, gender, age group): Auto, a product field (EAN, UPC, JAN, ISBN, MPN, SKU, model, manufacturer), a product attribute, a fixed value or none.
• Google product category. Per OpenCart category the numeric id or the full path from the Google taxonomy (type to search). A subcategory uses its parent's entry when it has none.

Products page

Every product that is known to a target with its state, Google status and issue count. The sliders open the per-product form: exclude, title, Google category, GTIN, MPN, brand, condition, colour, size, gender, age group, "no unique identifier".

Usage

Daily work

You do nothing. Save a product, change a price or let an order move stock: the product is queued for every active target and sent a few minutes later; unchanged products cost no call. The overview shows per target how many products Google approved, left pending, partly approved or disapproved.

Buttons

• Send queued now (per target) queues a push of everything waiting.
• Full sync re-checks every product of the target (unchanged ones are skipped by their hash) and removes the ones that are no longer eligible.
• Build now rebuilds the feed files of the target.
• Run the queue now (overview, Jobs) works the queue once, like the cron.
• Remove all from Google (target form) deletes every offer of the target at Google and pauses the target.

Google's issues

Issues lists every product that has item level issues, with Google's description, the severity (DISAPPROVED, DEMOTED, NOT_IMPACTED), the attribute, the countries and Google's "How to fix" link, and a summary of the most frequent issues. Status is read back every few hours; Read Google status now does it at once.

Feed in Merchant Center

In Merchant Center add a scheduled fetch feed and paste the XML or TSV address of the target from the overview (the address contains a secret). Use the feed only where you do not also send the same country and language through the API: an offer ID prefix does not separate them (both use the same ids). "New secret address" on the target form turns the old address off at once.

Cron

The extension registers an OpenCart cron job that runs every minute and decides what is due. The server must call OpenCart's cron.php (for example every 5 minutes). Without OpenCart's cron, call the web address shown on the overview from any cron service.

Uninstall

Extensions > Modules > Uninstall removes the events, the cron job and the permissions. Tables, settings and the licence stay, so a reinstall or update continues where it was. Products at Google stay until you use "Remove all from Google" first.

Developer notes

Technical reference for developers who customize Google Merchant Center Sync for OpenCart 4.1. Google, Google Merchant Center and Google Shopping are trademarks of Google LLC. This extension is not affiliated with or endorsed by Google.

Extension identity

No core file is changed and there is no OCMOD: everything runs through events and the OpenCart cron.

OpenCart 4 only. extension.json has no oc3 target, so kv package builds no OpenCart 3 zip; the oc3/ folder is only the scaffold tree that kv validate requires and is never packaged.

Offer ids. Default [prefix] + product id; with the source SKU or model, the code. Every id, including the fallback, is checked against the other map rows of the target; the fallback has its own shape (p<id>, then p<id>-2 ...), so a SKU of 123 and the product with the id 123 never meet. UNIQUE (target_id, offer_id) backs it in the database. The feed uses the id of the product's map row.

Removal. A row whose send was attempted (maybe_at, written before the call) is treated like a sent one: delete at Google (404 = done) before the row is forgotten. Remove all, target delete and an identity change take the same push-<target> lock as the push job.

Why this extension exists (official sources)

The Content API for Shopping reached its sunset on 2026-08-18; requests without an approved extension fail intermittently with HTTP 410 from 2026-09-01 and all endpoints are decommissioned in early 2027 (the dates may change). The replacement is the Merchant API. Source: https://developers.google.com/shopping-content/guides/sunset (read 2026-11-07).

Verification status of every Google fact used

Each row says where it comes from and whether it was read on the official page. verified = read on the page named, on the date given. flagged = not confirmed on an official page: it is implemented as stated and must be checked before relying on it. Nothing here is guessed silently.

Merchant API (base https://merchantapi.googleapis.com)

OAuth scope for all calls: https://www.googleapis.com/auth/content.

Google Shopping feed (data specification, support.google.com/merchants/answer/7052112, read 2026-11-08)

Structure

Sync rules

• Identity. Offer id = product id (or SKU / model, setting) stored in the map row BEFORE any call. The Merchant Center identity is contentLanguage~feedLabel~offerId plus the data source.
• Idempotent. A timeout leaves the row queued; the identical insert is sent again and replaces the same offer. A data source is looked up by its display name before it is created (under a lock). A delete that answers 404 counts as done.
• Change detection. The ProductInput is hashed; an unchanged product is not sent (but is refreshed after 25 days).
• Events. admin/model/catalog/product.addProduct|editProduct|addVariant|editVariant|editVariants|deleteProduct/after, catalog/model/checkout/order.addHistory/after (stock moves of orders, also fired for admin order changes), admin/view/common/column_left/before (menu), admin/controller/common/header/before (licence check). A daily full check re-evaluates every product (unchanged ones cost no call) and catches changes made behind the events (imports, SQL, scheduled special prices).
• Eligibility. Enabled products with an availability date that has come, assigned to the target's store, passing the category filter and "exclude out of stock", not excluded on the Products page. Products that leave the selection are deleted at Google when "Remove disabled products from Google" is on.
• Errors. HTTP 400/404/409/422 from a PRODUCT call belong to that product (state E with the message, the run continues). A refused LOGIN (token endpoint 400 invalid_grant / invalid_client, 401) is an AuthException: never a product error, the job stops as permanent and the Connection page shows the failure. 401/403 from the API stop the job as permanent. A 400/404 that names the data source (deleted in Merchant Center) clears the stored data source, resets the rows and retries in a minute. 429 and 5xx / network stop the run and retry with back-off; quota/daily_limit_exceeded waits until 12:00 UTC.
• Lost updates. Every map row has a version bumped on each change; a push that was in flight marks the row synced only when the version is unchanged.
• Time zone. Special-price dates are shop days: start = 00:00 of date_start, end = 00:00 of date_end (OpenCart's own rule is date_end > NOW(), so a special with date_end = today is already over and is not sent), both in the shop time zone (setting config_timezone), converted to UTC for the API and written with the shop offset in the feed. Cron buckets (daily check) use the shop day.
• Text. OpenCart stores text HTML-encoded; every text that goes to Google is decoded first, cut by characters (mb_substr), never bytes.
• Cron guard. The cron route accepts the OpenCart cron runner (five arguments) or the secret key compared with hash_equals; a web request without the key gets 403. One queue run at a time (GET_LOCK).
• Variants. OpenCart 4 variant products (master id) are sent with itemGroupId = master id; colour and size come from the variant's option values when the option is named Color / Colour / Size, or from the Products page overrides. Option-based combinations of a single product are not expanded into separate offers in 1.0.
• Identifiers. OpenCart 4.1 keeps SKU / UPC / EAN / JAN / ISBN / MPN in product_code; the auto mapping uses EAN, UPC, JAN, ISBN (first valid GTIN) for the GTIN and ONLY the MPN code for the MPN (SKU and model are shop codes, not manufacturer part numbers: they are explicit choices on the Mapping page). The product override "no GTIN / MPN" sends identifierExists = false without gtins and mpn on the API path and in the feed.

Test the HTTP layer without Google

The base URL can be overridden for tests with the setting module_kv_google_merchant_base_url (development only); the same address then also serves /token and /auth.

node tests/mock-server/server.js 11932 starts a stand-in that follows the reference (validates the ProductInput, replaces by identity, 404 on delete, paging, Google error bodies, OAuth with PKCE and JWT grants, developer registration); node tests/e2e.js runs the browser end-to-end test on a pool store and REFUSES to run unless the base URL points at 127.0.0.1 or localhost; php tests/unit.php runs the unit tests (fixtures in tests/fixtures, modeled on the official examples). No test reaches a real Google endpoint.

Troubleshooting

Every call answers 401 UNAUTHENTICATED. The Cloud project is probably not registered. Connection > Register API access, then wait about 5 minutes. A test Merchant Center account cannot register; use the production account.

"invalid_grant" / the job stops as dead. The authorization was revoked or expired. Authorize again on the Connection page. The queue keeps your changes and sends them afterwards.

403 PERMISSION_DENIED. The Google account or service account has no administrator access to the Merchant Center account (Settings > Access and services).

HTTP 429 / the push waits. Google's quota. The job waits as long as Google asks (a daily limit waits until 12:00 UTC) and continues; nothing is lost.

A product shows "no usable main image" or another error state. The product misses a title, image, link or price. Fix it and click the re-send button; the Products page shows the message.

The feed address answers 404. The extension is switched off, the licence is not valid, the target is paused, or the key in the address is old ("New secret address" turns old ones off).

The feed address answers 503 "being prepared". The first build is running or failed; check Jobs and the log, or click Build now.

Nothing is sent after a save. Check that OpenCart's cron runs (the overview shows the last run) and that the Jobs page shows no dead job. "Run the queue now" works the queue once.

Prices differ from the shop. Check the target's currency, the tax setting and that a special price with a future start date is sent with its start date (Google applies it then).

Redirect URI mismatch. The address on the Connection page must be added exactly (https, no trailing slash change) to the OAuth client's authorized redirect URIs.

Every action is in the log (Marketing > Google Merchant > Log); secrets are masked there.

FAQ

Is this the Merchant API or the old Content API?

The Merchant API. Google's Content API for Shopping reached its sunset on 2026-08-18 and is being shut down (requests fail intermittently from 2026-09-01, decommissioning is planned for early 2027); this extension never uses it.

Do I need my own Google Cloud project?

Yes. OAuth client or service account, both are yours; nothing runs through our servers. The extension only talks to Google's API hosts and, for the licence, to our licence server.

Why register the Cloud project?

Google requires it once per project; until then every call answers 401. The Connection page registers it with one click.

Can it replace my feed file?

Yes: use the API for a country and language, or the scheduled feed, not both for the same one. The offer ID prefix does NOT make them compatible: it is applied to the API and to this extension's own feed alike, so both would send the same identities. It only keeps this extension's offers apart from ANOTHER feed or app that feeds the same country and language.

Which products are sent?

Enabled products whose availability date has come, assigned to the target's store, in the target's categories, not excluded on the Products page.

How are variants handled?

OpenCart 4 variant products are sent with the master product's id as item_group_id. Colour and size come from the variant's Color / Size option or the product override. Option combinations of one product are not split into separate offers in 1.0.

What about taxes?

The Merchant API has no tax field. Choose "Tax in prices" per target: as stored, the percentage rates of the tax class for the target country, or a fixed percent. Rates that belong to single states or provinces are never added up into one figure; US and Canadian targets keep prices without sales tax, as Google asks, and US sales tax is set in Merchant Center.

GTIN missing?

The product is sent with identifierExists = false when it has no valid GTIN and no brand plus MPN, or when you tick "no GTIN / MPN" for the product (then no GTIN and no MPN are sent). The MPN is only the MPN code of the product: SKU and model are not used unless you choose them on the Mapping page. Invalid GTINs (wrong length or check digit) are never sent.

Does it work with multiple stores, languages and currencies?

Yes: one target per store, language and currency combination.

What happens to my offers when the extension is switched off or the licence is not valid?

Nothing is sent to Google while it is off, including removals: offers that are already there stay as they are (Google lets them expire after 30 days without a refresh) until the extension is active again. The admin pages stay open.

Does an update delete my settings?

No. Targets, mapping, overrides, credentials, settings and the licence are kept.

Is it tested against Google?

It is tested against a stand-in of the documented Merchant API (unit tests on PHP 8.1 and 8.3, browser end-to-end on OpenCart 4.1.0.4), not against a live Merchant Center account.

Is there an OpenCart 3 edition?

No. OpenCart 4.1 only.