Spree Google Shopping (Merchant Center)

A production-grade Spree Commerce extension that integrates directly with Google Merchant Center. Automatically sync products, variants, inventory, and pricing in real-time using the Content API v2.1
Includes a full Admin Dashboard for tracking approval status, fixing data quality issues, and managing OAuth connections securely.

🚀 Key Features

1. Real-Time Sync: Products are pushed to Google immediately upon update/create via background jobs.
   
2. OAuth 2.0 Integration: Secure, token-based authentication (No static JSON key files required).
   
3. Admin Dashboard: Live visualization of Approved, Pending, and Disapproved products.
   
4. Data Quality Issues: View specific error messages from Google (e.g., "Missing GTIN", "Image too small") directly in Spree.
   
5. Granular Control:
   • Set Global Defaults (Target Country, Currency, Shipping Rules).
   • Override attributes per Product (Brand, MPN, GTIN, Gender, Age Group).
6. Drill-Down Taxonomy: Built-in selector for Google's official Product Taxonomy (6,000+ categories).
7. Secure: Uses Rails 7 Active Record Encryption to store OAuth tokens safely.

📦 Installation

1. Add this line to your application's Gemfile:

gem 'spree_google_products', '~> 1.0'

2. Install the gem:

bundle install

3. Run the Installer: This command will copy migrations, generate encryption keys, and seed the Google Taxonomy database.

bundle exec rails g spree_google_products:install

Follow the on-screen prompts to run migrations and seed data.

⚙️ Configuration

Google Cloud Console Setup

Before using the extension, you must create credentials in Google Cloud.

1. Go to Google Cloud Console.
   

2. Create a new project (or select existing).
   

3. Enable API: Go to "APIs & Services" > "Library" -> Search for "Content API for Shopping" -> Enable it.
   

4. Create Credentials:
   

   • Go to "APIs & Services" > "Credentials".
   

   • Click Create Credentials -> OAuth Client ID.
   

   • Application Type: Web Application.
   

   • Authorized Redirect URI: https://your-store.com/admin/google_merchant_settings/callback
   (Note: Use http://localhost:3000/... for local development).
   

5. Copy the Client ID and Client Secret.
   

Environment Variables

The installer automatically adds these to your .env file. Fill in your Google credentials:

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here

Connect in Spree Admin

1. Login to your Spree Admin Panel.
2. Navigate to Google Shopping > Settings (Sidebar).
3. Click Connect Account and log in with the Google Account that manages your Merchant Center.
4. Once connected, enter your Merchant Center ID and Target Country/Currency.
5. Click Save Settings.

🛠️ Usage

Dashboard

Visit Google Shopping > Dashboard to see a live overview of your product feed health. • Approved: Live on Google Shopping.

• Limited: Live but restricted (e.g., adult content, partial regions).

• Disapproved: Critical issues preventing display.

• Sync Now: Force a full catalog sync manually.

Managing Products

You can manage Google-specific attributes in the Product Edit tab under "Google Shopping Attributes". • GTIN / MPN: Crucial for approval. If your products have barcodes, enter them here.

• Google Category: Use the drill-down selector to pick the exact Google Taxonomy ID.

• Demographics: Set Gender, Age Group, and Condition (New/Used).

Background Jobs

This extension uses ActiveJob. Ensure you have a queue adapter configured (Sidekiq, Solid Queue, or Delayed Job) for production.
• Spree::GoogleShopping::SyncProductJob: Syncs individual product updates.
• Spree::GoogleShopping::SyncAllJob: Bulk syncs entire catalog.
• Spree::GoogleShopping::FetchStatusJob: Pulls approval status from Google.

🔒 Security & Encryption

This plugin strictly adheres to security best practices. OAuth Refresh Tokens are encrypted at rest in the database using Rails Active Record Encryption.

The installer generates these keys in your .env file automatically:

ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT

⚠️ IMPORTANT: Keep these keys safe. If you lose them, you will need to disconnect and reconnect your Google Account.

🗑️ Uninstallation

To cleanly remove the extension, drop tables, and cleanup migrations, run:

bundle exec rails g spree_google_products:uninstall

This command will ask for confirmation before dropping the Google-related tables.

🗺️ Roadmap

• [x] Google Merchant Center (Content API) Sync
• [x] Product Approval Status Dashboard
• [x] Issue Reporting
• [ ] Google Ads Integration: Create Performance Max campaigns directly from Spree.
• [ ] Conversion Tracking: Auto-inject Google Ads conversion pixels.
• [ ] Free Listings: specialized support for "Free Listings" enhanced attributes.

❓ FAQ

Q: I get "Missing Active Record encryption credential" error. A: Restart your server. The encryption keys are loaded from .env on boot. If using a custom deployment, ensure the ACTIVE_RECORD_ENCRYPTION_* variables are set in your environment.

Q: Why are my products still "Pending" after syncing? A: Google takes 3-5 business days to review new products. Check the Dashboard for real-time status updates.

Q: Can I sync to multiple countries? A: Currently, the extension supports one primary Target Country per store. Multi-country feeds via the "Shipping" attribute are planned for v2.0.

License

Copyright (c) 2026. Released under the BSD-3-Clause License.