Chapter 11: Google Merchant Center Integration

Google Merchant Center (GMC) is the bridge between AdPriority’s scoring engine and Google Ads campaigns. AdPriority writes custom labels to GMC products, which Google Ads then uses for product group segmentation and bid optimization. This chapter covers the custom label specification, the supplemental feed pipeline, the Content API for future scaling, and all verified data from the Nexus Clothing GMC account.

9.1 Custom Label Specifications

GMC provides five custom labels (custom_label_0 through custom_label_4) that merchants can populate with arbitrary values. These labels are invisible to shoppers but available for campaign segmentation in Google Ads.

Specification Reference

Important constraint: If a label exceeds 1,000 unique values, additional values are silently ignored for reporting and bidding. AdPriority’s label schema is designed to stay well within this limit.

Unique Value Budget

Label Capacity Planning
========================

custom_label_0 (Priority):    6 unique values   [  0.6% of 1,000 limit ]
custom_label_1 (Season):      4 unique values   [  0.4% of 1,000 limit ]
custom_label_2 (Category):   ~20 unique values   [  2.0% of 1,000 limit ]
custom_label_3 (Status):      5 unique values   [  0.5% of 1,000 limit ]
custom_label_4 (Brand Tier):  3 unique values   [  0.3% of 1,000 limit ]
                             ----
Total:                       ~38 unique values   [  0.8% of 5,000 limit ]

AdPriority uses less than 1% of the available unique value budget, leaving substantial headroom for future expansion.

9.2 AdPriority Label Schema

Each of the five custom labels serves a distinct purpose in the campaign segmentation strategy:

Label Allocation

+------------------+--------------------------------------------------+
| Label            | Purpose and Values                               |
+------------------+--------------------------------------------------+
|                  |                                                  |
| custom_label_0   | PRIORITY SCORE                                  |
|                  | Values: priority-0, priority-1, priority-2,     |
|                  |         priority-3, priority-4, priority-5      |
|                  | Used for: Primary PMAX campaign segmentation    |
|                  |                                                  |
+------------------+--------------------------------------------------+
|                  |                                                  |
| custom_label_1   | SEASON                                          |
|                  | Values: winter, spring, summer, fall             |
|                  | Used for: Seasonal performance analysis,        |
|                  |           seasonal campaign adjustments          |
|                  |                                                  |
+------------------+--------------------------------------------------+
|                  |                                                  |
| custom_label_2   | PRODUCT CATEGORY                                |
|                  | Values: t-shirts, jeans-pants, shorts,          |
|                  |         hoodies-sweatshirts, outerwear-heavy,   |
|                  |         outerwear-medium, outerwear-light,      |
|                  |         headwear-caps, headwear-cold-weather,   |
|                  |         headwear-summer, joggers, underwear-    |
|                  |         socks, footwear-sandals, footwear-shoes,|
|                  |         accessories, women-apparel, long-sleeve,|
|                  |         sweatpants, swim-shorts, other          |
|                  | Used for: Category-level ROAS reporting         |
|                  |                                                  |
+------------------+--------------------------------------------------+
|                  |                                                  |
| custom_label_3   | INVENTORY STATUS                                |
|                  | Values: in-stock, low-inventory, new-arrival,   |
|                  |         clearance, dead-stock                   |
|                  | Used for: Exclude dead-stock, boost new arrivals|
|                  |                                                  |
+------------------+--------------------------------------------------+
|                  |                                                  |
| custom_label_4   | BRAND TIER                                      |
|                  | Values: name-brand, store-brand, off-brand      |
|                  | Used for: Brand-level bidding strategy,         |
|                  |           ROAS analysis by brand tier            |
|                  |                                                  |
+------------------+--------------------------------------------------+

Label Value Details

custom_label_0 – Priority Score:

custom_label_1 – Season:

custom_label_2 – Product Category:

Normalized from the 90 Shopify product types into approximately 20 groups (see Chapter 15 for the full category mapping table). Examples:

custom_label_3 – Inventory Status:

custom_label_4 – Brand Tier:

9.3 Nexus GMC Account: Verified Data

The following data was verified from a live GMC product export conducted on 2026-02-10 (124,060 products, TSV format).

Account Overview

Current Custom Label Usage

Conclusion: All five labels are effectively available. The 7 products on custom_label_0 represent a negligible 0.006% of inventory from an inactive campaign and are safe to overwrite.

Verified Product ID Examples

GMC Product IDs (from live export):

  shopify_US_8779355160808_46050142748904
  shopify_US_9128994570472_47260097118440
  shopify_US_9057367064808_47004004712680
  shopify_US_9238797418728_47750439567592
  shopify_US_7609551716584_42582395650280
  shopify_US_8631136518376_45680298983656
  shopify_US_9208152621288_47635854262504
  shopify_US_8361353412840_44841122955496

Format:  shopify_{country}_{shopifyProductId}_{shopifyVariantId}
Country: US (for all Nexus products)
Product ID: 13 digits
Variant ID: 14 digits

Item Group ID

The item_group_id in GMC is the Shopify product ID without the prefix:

Product ID (GMC):       shopify_US_8779355160808_46050142748904
Item Group ID (GMC):    8779355160808
Shopify Product ID:     8779355160808
Shopify Variant ID:     46050142748904

This is important because supplemental feeds operate at the variant level (full product ID), while Google Ads reporting can aggregate at the item group level (parent product).

9.4 Supplemental Feeds

A supplemental feed adds or overrides attributes on products already present in the primary feed. The primary feed (from Shopify Google Channel) provides core product data. AdPriority’s supplemental feed adds only the five custom labels.

How Supplemental Feeds Work

Primary Feed                    Supplemental Feed
(Shopify Google Channel)        (AdPriority Google Sheet)
+---------------------------+   +---------------------------+
| id (required)             |   | id (required - must match)|
| title                     |   | custom_label_0            |
| description               |   | custom_label_1            |
| price                     |   | custom_label_2            |
| image_link                |   | custom_label_3            |
| availability              |   | custom_label_4            |
| brand                     |   +---------------------------+
| gtin                      |
| product_type              |        ||
| ... (30+ attributes)     |        || GMC merges by ID
+---------------------------+        ||
                                     \/
                            +---------------------------+
                            | Merged Product in GMC     |
                            +---------------------------+
                            | id                        |
                            | title                     |
                            | description               |
                            | price                     |
                            | custom_label_0  <-- NEW   |
                            | custom_label_1  <-- NEW   |
                            | custom_label_2  <-- NEW   |
                            | custom_label_3  <-- NEW   |
                            | custom_label_4  <-- NEW   |
                            | ... (all other attributes)|
                            +---------------------------+

Critical Requirements

Supported Feed Formats

MVP Approach: Google Sheets

For the MVP and Starter/Growth tiers, AdPriority uses Google Sheets as the supplemental feed format. This approach was validated with 10 Nexus products on 2026-02-10 with zero issues.

9.5 Content API v2.1 (Future: Pro Tier)

For merchants who need faster-than-daily label updates, the Content API provides programmatic access to GMC product data.

Authentication

OAuth 2.0 for Google APIs

Scope:  https://www.googleapis.com/auth/content

Flow:
  1. Merchant connects Google account in AdPriority settings
  2. OAuth consent screen requests Content API scope
  3. Google returns authorization code
  4. Backend exchanges code for refresh token
  5. Refresh token stored encrypted in database
  6. Access tokens generated on demand (1-hour lifetime)

Updating Custom Labels (PATCH)

Endpoint: PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

{
  "customLabel0": "priority-5",
  "customLabel1": "winter",
  "customLabel2": "jeans-pants",
  "customLabel3": "in-stock",
  "customLabel4": "name-brand"
}

Use the updateMask query parameter to specify which fields to update:

?updateMask=customLabel0,customLabel1,customLabel2,customLabel3,customLabel4

Batch Operations (custombatch)

For bulk updates, the products.custombatch endpoint processes multiple products in a single HTTP request:

// backend/src/integrations/google/merchant.ts
import { google } from 'googleapis';

const content = google.content('v2.1');

interface LabelUpdate {
  gmcProductId: string;  // e.g., "shopify_US_8779355160808_46050142748904"
  labels: {
    customLabel0: string;
    customLabel1: string;
    customLabel2: string;
    customLabel3: string;
    customLabel4: string;
  };
}

export async function batchUpdateLabels(
  auth: any,
  merchantId: string,
  updates: LabelUpdate[]
): Promise<void> {
  const entries = updates.map((update, index) => ({
    batchId: index,
    merchantId: merchantId,
    method: 'update',
    productId: `online:en:US:${update.gmcProductId}`,
    product: {
      customLabel0: update.labels.customLabel0,
      customLabel1: update.labels.customLabel1,
      customLabel2: update.labels.customLabel2,
      customLabel3: update.labels.customLabel3,
      customLabel4: update.labels.customLabel4,
    },
    updateMask: 'customLabel0,customLabel1,customLabel2,customLabel3,customLabel4',
  }));

  const response = await content.products.custombatch({
    auth,
    requestBody: { entries },
  });

  // Process response for errors
  for (const entry of response.data.entries || []) {
    if (entry.errors) {
      console.error(`Batch ${entry.batchId} failed:`, entry.errors);
    }
  }
}

Rate Limits and Quotas

Error Handling

Exponential Backoff Implementation

async function withBackoff<T>(
  fn: () => Promise<T>,
  maxRetries: number = 5
): Promise<T> {
  let delay = 1000; // Start at 1 second

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      if (attempt === maxRetries) throw error;

      const isRetryable =
        error.code === 429 ||
        error.code === 503 ||
        error.message?.includes('rate');

      if (!isRetryable) throw error;

      await new Promise(resolve => setTimeout(resolve, delay));
      delay = Math.min(delay * 2, 60000); // Cap at 60 seconds
    }
  }

  throw new Error('Max retries exceeded');
}

9.6 Feed Processing Timeline

Understanding the end-to-end timeline from priority change to Google Ads effect:

Timeline: Priority Change to Google Ads Effect
================================================

T+0h    AdPriority calculates new priority score
        |
T+0m    Score written to database, flagged for sync
        |
T+1m    Google Sheet updated via Sheets API (MVP)
        |  -- OR --
        Content API PATCH sent (Pro tier)
        |
T+1h    GMC begins processing supplemental feed
to      (Google Sheets: fetched on schedule, typically daily)
T+24h   (Content API: processed within minutes to hours)
        |
T+24h   Custom labels visible in GMC product data
to      Labels available in Google Ads for
T+48h   product group filtering and bid optimization
        |
        Google Ads campaigns use new labels
        for next ad serving cycle

MVP (Google Sheets):  ~24-48 hours end-to-end
Pro (Content API):    ~1-6 hours end-to-end

For priority scoring, this latency is acceptable. Priority changes are strategic decisions (seasonal shifts, new arrivals) rather than real-time price adjustments.

9.7 Feed Size Planning

Nexus Store Estimates

Multi-Tenant Scaling

For the SaaS product, each tenant gets their own Google Sheet:

All scenarios are comfortably within Google Sheets limits. Even the largest stores use less than 10% of the 10-million-cell capacity.

9.8 Supplemental Feed Test Results (Verified 2026-02-10)

A live test was conducted on the Nexus GMC account to validate the supplemental feed pipeline end-to-end.

Test Configuration

Sample Products Tested

Results

Verification Steps Completed

1. Created Google Sheet with 10 sample products and 6 columns
2. Shared sheet publicly (Viewer access)
3. Added as supplemental feed in GMC
4. Linked to all 3 primary data sources
5. Triggered manual update
6. All 10 products matched within 1 hour
7. All attribute names recognized with zero issues

Conclusion: The Google Sheets supplemental feed pipeline is confirmed working. The shopify_US_{productId}_{variantId} ID format matches correctly. This validates the MVP approach.

9.9 GMC ID Construction

AdPriority constructs GMC product IDs from Shopify product and variant IDs. The construction is deterministic and requires no GMC API lookup.

// backend/src/services/sync/gmc.ts

/**
 * Construct the Google Merchant Center product ID from Shopify IDs.
 *
 * Format: shopify_{country}_{productId}_{variantId}
 *
 * Verified against 124,060 products in Nexus GMC export (2026-02-10).
 * All products follow this format with country code "US".
 */
export function buildGmcProductId(
  shopifyProductId: number | string,
  shopifyVariantId: number | string,
  countryCode: string = 'US'
): string {
  return `shopify_${countryCode}_${shopifyProductId}_${shopifyVariantId}`;
}

// Examples:
// buildGmcProductId(8779355160808, 46050142748904)
//   => "shopify_US_8779355160808_46050142748904"
//
// buildGmcProductId(9128994570472, 47260097118440)
//   => "shopify_US_9128994570472_47260097118440"

Multi-Country Considerations

For SaaS merchants selling in multiple countries, the country code in the GMC ID varies:

AdPriority stores the country code per tenant and uses it in ID construction. For the Nexus MVP, this is hardcoded to US.

9.10 Reconciliation Strategy

Data drift can occur when products are added or removed from GMC’s primary feed. AdPriority runs periodic reconciliation to ensure labels remain accurate.

Daily Reconciliation (Automated)

Daily Reconciliation Job (runs at 3:00 AM)
============================================

1. Fetch all active products from Shopify API
2. Compare with product_mappings database table:
   a. New products (in Shopify, not in DB)
      -> Create mapping, calculate priority, add to Sheet
   b. Removed products (in DB, not in Shopify)
      -> Mark deleted, remove from Sheet on next sync
   c. Changed products (type, tags, or vendor changed)
      -> Recalculate priority, update Sheet if changed
3. Regenerate complete Google Sheet
4. Log reconciliation report:
   - Products added: N
   - Products removed: N
   - Priorities changed: N
   - Errors: N
5. Alert if > 5% of products changed (unusual, may indicate
   bulk import or data issue)

Weekly GMC Verification (Pro Tier)

For Pro tier merchants with Content API access:

Weekly GMC Verification (runs Sunday 2:00 AM)
===============================================

1. Fetch product list from Content API
2. Compare custom labels with expected values:
   a. Missing labels -> Product may not be in Sheet
   b. Wrong labels   -> Stale data, queue update
   c. Unknown products -> New in GMC, investigate
3. Generate verification report
4. Alert on > 1% label mismatch rate

9.11 Chapter Summary

Google Merchant Center integration is the critical output layer of AdPriority. The app writes five custom labels to GMC products using a supplemental feed (Google Sheets for MVP, Content API for Pro tier). These labels encode priority score, season, category, inventory status, and brand tier – enabling Google Ads campaigns to segment products by business-relevant attributes.

Key verified facts for Nexus Clothing:

• 124,060 variant-level products in GMC
• All 5 custom labels effectively available (only 7 products had label_0 values)
• Product ID format confirmed: shopify_US_{productId}_{variantId}
• Supplemental feed test: 10/10 matched, zero issues
• Google Sheets capacity: 1.2% of cell limit for active variants
• Content API rate limit: 2 updates per day per product
• End-to-end label propagation: 24-48 hours (Sheets), 1-6 hours (API)