Installation and setup

Requirements

• CS-Cart or Multi-Vendor 4.17.2 or later, administrator access.
• A production Merchant Center account with a verified website, and its numeric ID (shown at the top right of Merchant Center). Test accounts cannot be registered for the Merchant API.
• The Google user (or the service account) you connect must have Admin access to that account; registration needs it.
• A Google Cloud project of your own with the Merchant API enabled (API Console, API Library). API keys do not work with the Merchant API; use OAuth 2.0 or a service account.
• A cron job on your server (step 8).

Install the add-on

1. Download the kv_google_merchant-<version>.zip package from your Kavio Labs or CS-Cart Marketplace account.
2. In the admin panel open Add-ons > Manage add-ons, click the gear button, choose Manual installation and upload the archive.
3. Find Google Merchant API Sync and make sure its status is Active.
4. Enter your license key under Settings > License (Kavio Labs downloads) and click Check now.

Connect Google

Open Marketing > Google Merchant API Sync > Connection. Choose one of two ways.

A. OAuth 2.0 (sign in with Google)

1. In your Google Cloud project create an OAuth client of type Web application.
2. Add the Authorized redirect URI shown on the Connection page to that client.
3. Enter the Merchant Center ID, the client ID and the client secret, then click Authorize with Google. Sign in with a Google user who has access to the Merchant Center account and accept. You return to the Connection page and the check turns green.

If the OAuth consent screen of your project is in testing mode, Google lets refresh tokens expire after a few days; publish the app (internal use is enough) to avoid re-authorizing.

B. Service account

1. In the Cloud project create a service account and download its JSON key.
2. In Merchant Center open Settings > Access and services and add the service account address as a user with Admin access.
3. On the Connection page choose Service account, paste the JSON key and click Save and test.

The secrets are stored encrypted and never shown again.

Register API access (mandatory, once per Cloud project)

Google blocks every Merchant API call from a Cloud project that is not registered as a developer: the answer is HTTP 401 UNAUTHENTICATED, whatever the credentials. The add-on registers the project (accounts.developerRegistration.registerGcp) automatically right after the first successful connection. If that failed, or you connect a project that was registered before, use the Register API access block on the Connection page:

1. Click Register API access (the developer e-mail is optional: a Google account address, not the service account).
2. Wait about 5 minutes, then click Check registration. “Registered” means calls are accepted; “Not registered” means Google still answers 401.
3. Click Test connection.

Registration needs a production account with a verified website and Admin access of the connected user; Google refuses test accounts. Register only your primary Merchant Center account. See Google’s guide: developers.google.com/merchant/api/guides/quickstart/registration.

Create a target and run the first sync

1. Open Targets and click Add target. A target is one country and language: content language (for example en), feed label (usually the country code, US), target country, currency, the store language for texts, optional categories, vendors (Multi-Vendor) or storefront (Ultimate), tax percent and shipping.
2. Click Save and run full sync. The first push creates the API data source in Merchant Center (or reuses one with the same name) and sends the products in the background.
3. Open Mapping and set GTIN, brand and the Google product category where the automatic choice is not right. Saving the mapping re-checks every product; unchanged products cost no API calls.
4. Add the cron job from Settings > Cron (every minute is fine; overlapping runs are prevented).

Multi-Vendor and Ultimate

• Multi-Vendor: the connection belongs to the marketplace owner. Pick the vendors in the target (empty = all active vendors). Vendors have no access to the add-on.
• Ultimate: choose the storefront in the target. The target sends the storefront’s own products and the products shared with it, with links on that storefront’s domain; mapping can be set per storefront, with a default for all. One connection is one Merchant Center account and one website: the add-on warns when active targets point to different domains.

Update

Upload the new package the same way. Settings, credentials and data are kept; missing tables and settings are added on the first request. See CHANGELOG.

Uninstall

Open Add-ons > Manage add-ons, click the gear of the add-on and choose Uninstall. Settings, language variables, tables and the stored credentials are removed. Uninstalling does not call Google. Products already in Merchant Center stay there (with a frozen price and stock) until they expire after 30 days. Before uninstalling, open Targets, edit each target and click “Remove all from Google”, wait until the Jobs list shows the cleanup job done, and only then uninstall.