Magento 2 Google Shopping Merchant API Sync Explained

1. Magento generates an XML file with all product data
2. The feed is delivered to Google via scheduled fetch (URL) or SFTP upload
3. Batch-based: The entire catalog is sent each time

Ideal for: Stores with stable pricing and inventory that update on a predictable schedule (daily, hourly). Simple setup, reliable, and works great for most merchants.

1. Product changes in Magento automatically trigger a sync
2. Updates are sent directly to Google via their Merchant API
3. Event-driven: Only changed products are synced

Ideal for: Stores with frequent price changes, dynamic inventory, or real-time stock from ERP/PIM systems. Keeps Google in sync without waiting for the next scheduled feed.

This module is an add-on to the Feed module, not a replacement. Many stores benefit from using both:

• XML Feed: Ensures Google always has a complete, up-to-date baseline of all products
• API Sync: Pushes critical changes (price, stock) to Google immediately

This combination gives you the reliability of scheduled feeds plus the speed of real-time updates.

1. Product saved in Magento - You update a product in admin or via import
2. Flagged for sync - The indexer marks the product as "needs update"
3. Added to queue - A cron job picks up flagged products and adds them to the queue
4. Synced to Google - The queue consumer sends the data to Google Merchant API
5. Visible in Google Shopping - Changes appear in Google within minutes

When you save a product in Magento (or stock updates via import), the extension automatically flags it for synchronization. This happens via Magento's indexer system - the same technology that updates your category pages and search results.

What triggers a sync:

• Product save (admin or API)
• Stock quantity change
• Price update
• Any attribute change that affects the feed

What doesn't trigger a sync:

• Products not included in your feed (filtered out by category, attribute, etc.)
• Disabled products
• Out-of-stock products (if configured to exclude)

The extension doesn't sync immediately when you save a product. Instead, it uses Magento's message queue system:

1. Cron job runs every few minutes - Picks up flagged products
2. Products added to queue - Grouped in batches for efficiency
3. Queue consumer processes - Sends data to Google

Why a queue?

• Prevents timeout issues during bulk imports
• Handles rate limits gracefully
• Allows retries on failures
• Doesn't slow down your admin panel

Before sending data to Google, the extension compares your current product data with what was previously synced:

1. Fetches fresh product data from Magento
2. Calculates a "fingerprint" (hash) of the data
3. Compares with the stored fingerprint
4. Only syncs if something actually changed

Why this matters:

• Saves API quota - no unnecessary calls to Google
• Faster processing - skips unchanged products
• Accurate tracking - you know exactly what's synced

When a product needs syncing, the extension:

1. Transforms Magento data to Google's format
2. Sends an update request to the Merchant API
3. Records the response (success or error)
4. Updates the product status in the grid

Updates all product attributes: title, description, price, images, shipping, etc.

Used when:

• Product is first added
• Any non-inventory attribute changes
• Manual sync from admin grid

Updates only price and availability - faster and with higher API limits.

Used when:

• Only price changes
• Only stock quantity changes
• Scheduled inventory refresh

Under normal conditions:

• Indexer flags product: Instant (on save)
• Cron picks up: Within 5 minutes
• Queue processes: Within 1-2 minutes
• Google reflects change: Within 5-30 minutes

Total: Typically under 15 minutes

• Large queue backlog (bulk imports)
• Google API rate limits
• Cron not running
• Queue consumers not running

• Attribute mapping (which Magento attributes map to Google fields)
• Product filters (which products to include/exclude)
• Category mapping
• Static values (brand, condition, etc.)

• Google Cloud credentials (Service Account)
• Merchant ID and Data Source
• Sync intervals and batch sizes
• Error retry settings

When a sync fails, the extension:

1. Logs the error with details
2. Keeps the product in "Error" status
3. Retries after a configurable interval (default: 4 hours)

From the admin grid, you can:

• View error details - Click the status to see the full error
• Retry single product - Use the "Sync" action
• Retry multiple products - Select products and use mass action

Marketing > Google Shopping API > Products

Shows all products with their sync status, last sync time, and any errors.

# Check overall sync status
bin/magento googleshopping:api:status --store=1

# Manually sync specific products
bin/magento googleshopping:api:sync --store=1 --product-ids=1,2,3

# Test connection
bin/magento googleshopping:api:test-connection --store=1

Debug logging (when enabled) writes to:

var/log/googleshopping_api.log

1. Configure the Feed module first (attribute mapping, filters)
2. Set up API module credentials
3. Test connection
4. Use "Initialize Products" to populate the sync table
5. Monitor first batch for errors

• Keep cron running reliably
• Monitor the Products grid for errors
• Check Google Merchant Center for disapprovals
• Review logs periodically

For stores with 10,000+ products:

• Increase batch size (up to 1000)
• Ensure queue consumers are running
• Consider dedicated cron for queue processing
• Initial sync may take several hours

1. Check if cron is running: bin/magento cron:run
2. Check if product is in feed: Review Feed module preview
3. Check product status in grid: Look for errors
4. Check queue: bin/magento queue:consumers:list

1. Verify product shows "Synced" status
2. Check last sync time in grid
3. Wait 15-30 minutes for Google to process
4. Check Merchant Center for product disapprovals

1. Review error messages in grid
2. Check attribute mapping in Feed module
3. Verify all required fields are mapped
4. Test with a single product first