Preface

Why This Book Exists

Every retailer running Google Ads faces the same quiet problem: not all products deserve the same advertising budget, but managing priorities manually is a losing battle.

Consider a clothing retailer with 5,000 products. Shorts should get maximum ad spend in June and minimum in December. Jackets are the opposite. New arrivals need a visibility boost. Clearance items should not eat budget at all. Bestsellers should always get strong spend. Slow movers should barely appear.

A marketing manager who gets this right can double their return on ad spend. A marketing manager who gets this wrong – or, more commonly, who never gets around to managing it at all – bleeds budget into irrelevant products every single day.

This Blueprint documents a complete system for solving that problem: AdPriority, a Shopify app that automates Google Ads product priority scoring using a 0-5 scale with seasonal automation.

The Problem in Detail

Google Performance Max (PMAX) campaigns are powerful but opaque. Google’s algorithm decides which products to show, when, and to whom. Merchants have one primary lever for influencing product-level spend: campaign segmentation using Google Merchant Center custom labels.

The workflow looks like this:

+-----------------------------------------------------------------+
|                                                                   |
|   1. Assign custom labels to products in GMC                     |
|   2. Create separate PMAX campaigns (or asset groups)            |
|      segmented by those labels                                    |
|   3. Set different budgets and ROAS targets per segment           |
|   4. Google optimizes within each segment independently          |
|                                                                   |
+-----------------------------------------------------------------+

The problem is step 1. Assigning and maintaining custom labels across thousands of products is:

• Time-consuming: Manual updates for every seasonal change, every new arrival, every clearance event
• Error-prone: Forgetting to update labels means budget flowing to the wrong products for days or weeks
• Difficult to scale: What works for 100 products breaks at 1,000 and collapses at 10,000
• Knowledge-dependent: When the person who manages labels leaves, institutional knowledge walks out the door

Most merchants either ignore custom labels entirely (leaving PMAX fully automated with no guardrails) or set them once and never update them (which is almost as bad).

The Solution Approach

AdPriority introduces a simple but powerful abstraction: the Priority Score.

+=========================================================================+
|                                                                           |
|   PRIORITY SCORING MODEL                                                 |
|                                                                           |
|   Score   Name          Ad Spend Behavior                                |
|   -----   -----------   ------------------------------------------------ |
|     5     Push Hard     Maximum budget, aggressive bidding               |
|     4     Strong        High budget, balanced approach                   |
|     3     Moderate      Standard budget, conservative bidding            |
|     2     Light         Minimal budget, strict ROAS targets              |
|     1     Minimal       Very low budget, only highest-ROAS clicks        |
|     0     Exclude       No advertising -- product is suppressed          |
|                                                                           |
+=========================================================================+

The scoring engine determines each product’s priority through a clear hierarchy:

                    SCORE OVERRIDE HIERARCHY

            +----------------------------------+
            |    1. Manual Override             |   <-- Highest priority
            +----------------------------------+
                          |
            +----------------------------------+
            |    2. Seasonal Calendar           |
            +----------------------------------+
                          |
            +----------------------------------+
            |    3. New Arrival Boost           |
            +----------------------------------+
                          |
            +----------------------------------+
            |    4. Category-Based Rule         |
            +----------------------------------+
                          |
            +----------------------------------+
            |    5. Default Score               |   <-- Lowest priority
            +----------------------------------+

Priority scores flow through a pipeline that ends at Google Ads:

  +----------+     +----------+     +-----------+     +---------+     +--------+
  | Shopify  |     |          |     | Supple-   |     | Google  |     | Google |
  | Products |---->| Scoring  |---->| mental    |---->| Merchant|---->| Ads    |
  | (source) |     | Engine   |     | Feed      |     | Center  |     | PMAX   |
  +----------+     +----------+     +-----------+     +---------+     +--------+
                        |
               +--------+--------+
               |        |        |
            Rules   Seasons   Manual
            Engine  Calendar  Overrides

The Three-Phase Approach

We adopted a deliberate phased approach, starting with a real-world validation before writing a single line of SaaS code:

+=========================================================================+
|                                                                           |
|   PHASE 0: NEXUS MVP                    STATUS: VALIDATED                |
|   ------------------                    -------------------------        |
|   Google Sheets supplemental feed       10/10 products matched           |
|   Manual priority assignment            Zero GMC errors                  |
|   Nexus Clothing as test store          Pipeline proven end-to-end       |
|   Document everything                   124,060 GMC products analyzed    |
|                                                                           |
|                            |                                             |
|                            v                                             |
|                                                                           |
|   PHASE 1: SAAS FOUNDATION              STATUS: PLANNED                 |
|   -------------------------              -------------------------        |
|   Shopify app (OAuth + App Bridge)      Database schema designed         |
|   PostgreSQL database                    API endpoints specified         |
|   Core API (products, rules, sync)      Polaris UI wireframed           |
|   Basic Polaris admin UI                                                 |
|                                                                           |
|                            |                                             |
|                            v                                             |
|                                                                           |
|   PHASE 2: FULL PRODUCT                 STATUS: PLANNED                 |
|   ----------------------                 -------------------------        |
|   Seasonal calendar engine              Category x Season matrix         |
|   Rules engine (IF-THEN)                New arrival auto-boost           |
|   Content API direct sync               Bulk operations                  |
|   Google Ads performance data           ROAS recommendations             |
|                                                                           |
|                            |                                             |
|                            v                                             |
|                                                                           |
|   PHASE 3: APP STORE LAUNCH             STATUS: PLANNED                 |
|   --------------------------             -------------------------        |
|   Shopify App Store listing             Billing integration              |
|   Multi-tenant production               Usage-based tier limits          |
|   Documentation + onboarding            Marketing + landing page         |
|                                                                           |
+=========================================================================+

The critical insight: Phase 0 is not a prototype. It is a real, working pipeline that validates the entire concept with actual GMC data before any engineering investment in the SaaS product. The supplemental feed approach was tested on 2026-02-10 with 10 Nexus products – all 10 matched in GMC with zero issues.

What Makes This Blueprint Different

1. Built on Real Data

This is not a theoretical product specification. The research behind this Blueprint includes:

2. Validated Pipeline

The most risky part of any GMC integration is the product ID matching between Shopify and Merchant Center. We validated this before writing the Blueprint:

    SUPPLEMENTAL FEED VALIDATION RESULTS (2026-02-10)

    +-----------------------------+----------+
    | Metric                      | Result   |
    +-----------------------------+----------+
    | Products submitted          | 10       |
    | Products matched in GMC     | 10       |
    | Match rate                  | 100%     |
    | Label propagation errors    | 0        |
    | Time to reflect in GMC      | < 1 hour |
    | Custom label conflicts      | 0        |
    +-----------------------------+----------+

    Verdict: Pipeline is PROVEN. Build with confidence.

3. Existing Infrastructure

AdPriority does not start from scratch. It builds on proven Shopify app infrastructure:

• Existing Shopify app template with OAuth flow (/volume1/docker/sales-page-app/)
• Shared PostgreSQL 16 instance (postgres16 container, production-grade)
• Docker deployment pipeline with Cloudflare Tunnel for external access
• Established development workflow on Synology NAS

4. Clear Market Gap

Market research identified a specific gap: no Shopify-native, affordable solution exists that is specifically focused on priority scoring for Google Ads. Competitors offer custom labels as a secondary feature within general-purpose feed management tools. AdPriority makes priority scoring the primary product.

Who Should Read This Book

The Technology Stack

+=========================================================================+
|                         TECHNOLOGY STACK                                  |
|                                                                           |
|   BACKEND                              FRONTEND                          |
|   -------                              --------                          |
|   Node.js 20 LTS                       React 18                         |
|   Express.js                           Vite (build tool)                 |
|   TypeScript                           Shopify Polaris v13               |
|   Prisma ORM                           React Query (server state)        |
|   Bull + Redis (job queue)             Chart.js (analytics)              |
|                                                                           |
|   DATABASE                             INTEGRATIONS                      |
|   --------                             ------------                      |
|   PostgreSQL 16                        Shopify Admin API (GraphQL)       |
|   (shared postgres16 container)        Google Sheets API v4              |
|   Redis 7 (cache + queue)             GMC Content API for Shopping       |
|                                        Google Ads API v17                |
|   INFRASTRUCTURE                                                         |
|   --------------                                                         |
|   Docker + Docker Compose              AUTHENTICATION                    |
|   Cloudflare Tunnel                    ---------------                   |
|   GitHub Actions (CI/CD)               Shopify OAuth (App Bridge)        |
|   Synology NAS (host)                  Google OAuth 2.0                  |
|                                        JWT session tokens                |
|                                                                           |
+=========================================================================+

Why This Stack

Business Model

Pricing rationale: Positioned between budget tools (Simprosys at $4.99) and enterprise solutions (Feedonomics at $1,000+). The $29 entry point is accessible for small Shopify merchants. The $79 tier captures the core value proposition of seasonal automation. The $199 tier targets performance-focused marketers who want data-driven decisions.

Conventions Used in This Book

Code Samples

// TypeScript code appears in blocks like this
async function calculatePriority(productId: string): Promise<number> {
  // Scoring engine implementation
}

SQL Statements

-- SQL code appears in blocks like this
CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    store_id UUID NOT NULL REFERENCES stores(id),
    priority_score INTEGER DEFAULT 3 CHECK (priority_score BETWEEN 0 AND 5)
);

API Examples

# HTTP requests appear like this
curl -X PATCH /api/products/abc123 \
  -H "Authorization: Bearer <token>" \
  -d '{"priority_score": 5}'

Important Notes

Note: Important information appears in blockquotes like this.

Warning: Critical warnings that could cause data issues or deployment failures.

ASCII Diagrams

Architecture and flow diagrams use ASCII art for portability:

+----------+     +----------+     +----------+
|  Client  |---->|   API    |---->| Database |
+----------+     +----------+     +----------+

Priority Score Indicators

When priority scores appear inline, they follow this convention:

• P5 = Push Hard (highest)
• P4 = Strong
• P3 = Moderate
• P2 = Light
• P1 = Minimal
• P0 = Exclude (no ads)

Acknowledgments

This Blueprint was created through collaboration between:

• Nexus Clothing – the real-world test store whose 5,582 products and 124,060 GMC listings validated the entire approach
• Google Merchant Center documentation – for making the supplemental feed specification clear enough to validate in one session
• The Shopify developer ecosystem – for excellent App Bridge and Polaris documentation
• Claude Code agents – who helped research, design, implement, and review every chapter

Let’s Build

The supplemental feed works. The product IDs match. The custom labels are available. The market gap is real. The infrastructure is ready.

This Blueprint contains everything needed to go from a validated Google Sheets prototype to a production Shopify app on the App Store.

Turn the page and let’s begin.

February 2026

Document Information