Google Merchant API — operational notes

Operational gotchas for the Merchant API v1 integration (Merchant Center
account 8613489, US + CA on one account). This is the "what bites you in
production" companion to the build docs — it does not restate the architecture.

Build/design context lives in the task docs:
doc/tasks/202606291024_MERCHANT_API_FEED_MIGRATION.md
(product-feed cutover) and
doc/tasks/202606301102_GOOGLE_MERCHANT_PROMOTIONS.md
(promotions layer).

Code: Feed::Google::MerchantApi::Client,
Edi::Google::{Orchestrator,ProductDataProcessor,Sender,PromotionDataProcessor,PromotionSender}.

The two halves of a product

Merchant Center composes each served product from two independent data
sources, and they migrate independently:

Primary product data Local inventory
Carries title, price, availability, shipping, … per-store storeCode + quantity
Source today API push — productInputs:insert, one primary API data source per feed label (US, CA), daily via EdiProductDataFlowWorker (02:15 CT) still a FILE/FETCH feed — WY-US/CA Local Inventory, fetching /api/v1/:locale/google/local_inventory
Built by Feed::Google::MerchantApi::ProductInputBuilder Feed::Google::LocalInventoryGenerator via GoogleLocalInventoryFeedWorker (04/10/16/22 CT, US then CA at :15)

The local inventory source is supplementary: it only attaches per-store
availability onto primary products that already have FREE_LOCAL_LISTINGS /
LOCAL_INVENTORY_ADS enabled. The primary feed cannot carry per-store stock.
You need both halves, and they are joined by offer id inside Merchant Center.

Migrating the primary source orphans local inventory

Symptom: products report ELIGIBLE_LIMITED with issue
local_stores_lack_inventory, even though the local inventory feed contains
them, is in stock, and uploaded without errors.

Cause: when the primary product data source is migrated or recreated (the
FILE → per-country API cutover), the already-attached local inventory records
are orphaned. They point at a data source that no longer owns those products.
This is not a feed regression and not a destinations-config problem.

Do NOT "fix" it by disabling local destinations. That kills a working local
program. During the 2026-06-30 reconciliation, US was serving 792 products
correctly while CA showed 653 limited — same config, one half mid-migration.

Fix — force a re-fetch of the local inventory data source. No config change,
no code change:

POST https://merchantapi.googleapis.com/datasources/v1/accounts/8613489/dataSources/<local-inventory-ds>:fetch

Auth is the same service account and https://www.googleapis.com/auth/content
scope the client already uses (google.merchant.service_account in credentials;
1Password IT/Google-Merchant-API). Enumerate the data sources with
Feed::Google::MerchantApi::Client#data_sources to find the local inventory
name. ⚠️ Client has no fetch method — this is a one-off curl or
bin/rails runner call, not a code path.

Result on 2026-06-30: CA went 653 ELIGIBLE_LIMITED → 0 after a single forced
fetch.

Verify with localInventories, not the report

The three surfaces settle at wildly different speeds:

Surface Lag
fileUpload status (itemsTotal, error count) seconds
inventories/v1/…/products/local~en~CA~<offer>/localInventories ~15 min
product_view reporting (item_issues, ELIGIBLE_LIMITED counts) hours

Right after a forced fetch, product_view still reported stale
resolution: MERCHANT_ACTION. Don't trust the immediate recount and don't
re-run the fix on the strength of it — watch a sample offer's
localInventories flip 404 → 200 instead.

Not to be confused with the other ELIGIBLE_LIMITED

The migration task doc records a different root cause for
ELIGIBLE_LIMITED at
202606291024_MERCHANT_API_FEED_MIGRATION.md:174:
a single refurbished SKU (tws2-ldn11ph-btk) that we correctly exclude from the
feed but which Merchant Center still had cached from the old FETCH feed (Google
retains fetched products ~30 days). Its issue string was
missing_shipping_mismatch_of_shipping_method_and_offer_currency, it affected
1 product, and the resolution was to wait for expiry — nothing to fetch.

Tell them apart by the issue code and the blast radius:

Orphaned local inventory Stale MC cache
Issue local_stores_lack_inventory missing_shipping_mismatch_of_shipping_method_and_offer_currency
Scale hundreds, one whole feed label 1–2 products
In google_feeds? yes no (correctly excluded)
Fix forced dataSources…:fetch nothing; expires in ~30 days

A third variant, also currency-mismatch, comes from using one unscoped API
data source for both countries — see the "USE TWO PER-COUNTRY API SOURCES"
warning in the migration doc.

Anomaly monitoring (disapprovals / item issues)

GoogleMerchantReportSyncWorker (05:00 CT) pulls the product_view report
(Feed::Google::MerchantApi::ReportPuller) onto each catalog_item.google_report;
ListingIssueSyncWorker (05:30 CT) reconciles it into ListingIssue rows via
ListingIssues::GoogleAdapter, same as Amazon/Walmart/Wayfair. Check the CRM
Listing Issues dashboard (provider=google filter) or the daily
retailer-compliance email — no separate Google-specific dashboard exists or is
needed. See the migration doc's Phase 4 for the build.

Both of these were learned the hard way on the first live promo push
(2026-06-30). Both are now closed in code; the code is the authority, and these
notes exist only so the error strings are searchable.

  • Effective window must be strictly under 6 months. Google measures it in
    absolute UTC time, so a calendar "6 months minus a day" plus end_of_day plus
    a DST offset change still tips over and returns HTTP 400
    INVALID_PROMOTION_DURATION_EXCEEDS_LIMIT. The ceiling is computed as an
    absolute Time with a one-week buffer in
    PromotionBuilder#effective_period
    — read that method and its comment before touching the date maths.

  • The discount must be additional at checkout. Google test-crawls the
    landing page, applies the promo, and rejects with "No or a lower discount
    found"     if there is no further discount — i.e. if the discount is already
    baked into the feed salePrice. promo_tracking / auto_apply coupons are
    exactly that case, so they can never be syndicated. Enforced by
    Coupon#syndicate_to_google_eligibility
    (app/models/coupon.rb), which also requires a
    public tier-3 customer-entered code.

The practical consequence: WarmlyYours' sale-page coupons are all
promo_tracking, so essentially none qualify — and that's correct. Those
discounts already serve through the product feed's salePrice, which is the
right channel. Google Promotions only adds value for genuine
checkout-additional / code offers.

Miscellaneous

  • v1beta is dead (HTTP 410 since 2026-02-28). Use
    merchantapi.googleapis.com/{datasources,products,promotions,inventories,reports}/v1.
  • Developer registration is required on top of adding the service account as
    a Merchant Center user — see the migration doc's "developer registration is
    REQUIRED" section.
  • Content API for Shopping v2.1 sunsets 2026-08-18; do not build on it.