Chapter 2: Product Requirements Document

2.1 Document Overview

Purpose

This Product Requirements Document (PRD) defines the complete functional, non-functional, integration, and user experience requirements for AdPriority. It serves as the authoritative reference for what the product must do, how it must perform, and what constraints it must operate within.

Every feature described in this document traces back to the core problem statement from Chapter 1: retailers waste ad spend because they cannot efficiently manage which products deserve the most advertising budget. Requirements that do not serve this purpose are out of scope.

Scope

This PRD covers AdPriority version 1.0 through version 2.0, spanning four development phases:

Requirements marked with a phase tag indicate the earliest phase in which they must be implemented.

Audience

Version History

Requirement ID Conventions

All requirements use a prefix that indicates their category:

2.2 Product Description

What AdPriority Is

AdPriority is a Shopify embedded application that automates product priority scoring for Google Ads Performance Max (PMAX) campaigns. It assigns a 0-5 priority score to every product in a merchant’s catalog, then syncs those scores as custom labels to Google Merchant Center (GMC). Merchants use these labels to segment PMAX campaigns so that high-priority products receive more ad budget and low-priority products receive less or none.

Core Value Proposition

BEFORE AdPriority                    AFTER AdPriority
================                     ================

All products treated equally         Products scored 0-5 automatically
  |                                    |
  v                                    v
Budget spread evenly                 Budget allocated by priority
  |                                    |
  v                                    v
Shorts get ads in winter             Shorts excluded in winter (score 0)
Dead stock gets impressions          Dead stock excluded always (score 0)
New arrivals buried                  New arrivals boosted (score 5)
  |                                    |
  v                                    v
Poor ROAS                            15-30% ROAS improvement
Hours of manual label management     Automated, zero-maintenance

Product Boundaries

What AdPriority IS:

• A priority scoring system with a 0-5 scale
• A rules engine that calculates scores from product attributes, categories, seasons, and tags
• A sync pipeline that writes scores as custom labels to Google Merchant Center
• A seasonal automation engine that adjusts priorities on season boundaries
• A Shopify embedded app built with Polaris components

What AdPriority IS NOT:

• Not a bid management tool (it does not set bids or budgets in Google Ads)
• Not a feed management platform (it only writes custom labels, not full product feeds)
• Not an analytics dashboard (Pro tier adds read-only performance data, but it is not a reporting tool)
• Not a campaign builder (merchants still structure their PMAX campaigns manually)
• Not a multi-channel tool (v1.0 targets Google Ads only, not Facebook or Bing)

2.3 Functional Requirements

2.3.1 Priority Scoring System

FR-01: Priority Score Definition

Phase: 0 | Priority: P0

Every product receives a single integer score from 0 to 5 that directly controls how aggressively it is advertised in Google Ads.

Constraints:

• Score must be an integer between 0 and 5 inclusive
• Every active product must have a score (no null scores)
• Default score for unclassified products is 2 (Low)
• Score is stored at the product level; variants inherit the product score unless individually overridden (future feature)

Acceptance Criteria:

• Every product in the database has a priority_score column with a CHECK (priority_score BETWEEN 0 AND 5) constraint
• Products without matching rules receive default score of 2
• Score values map to GMC label values using the format priority-{score}

FR-02: Score Assignment Methods

Phase: 0 (manual), 1 (bulk, rules), 2 (seasonal, performance) | Priority: P0

AdPriority supports five methods of assigning priority scores, each appropriate for different use cases:

Acceptance Criteria:

• Manual scoring updates a single product and marks it as priority_source = 'manual'
• Bulk scoring updates up to 1,000 products in a single operation
• Rules-based scoring recalculates on product import and webhook events
• Seasonal scoring triggers automatically on season transition dates
• Performance recommendations are read-only suggestions, not automatic changes

FR-03: Score Override Hierarchy

Phase: 1 | Priority: P0

When multiple scoring methods apply to the same product, the highest-priority method wins. The hierarchy is evaluated top-to-bottom; the first matching rule determines the score.

SCORE OVERRIDE HIERARCHY (highest priority wins)
=================================================

  1. Manual override          -- Merchant locks a specific score
     |                           (priority_locked = true)
     v
  2. Exclusion tags           -- "archived" or "DEAD50" force score to 0
     |                           (hard override, cannot be raised)
     v
  3. Inventory warnings       -- "warning_inv_1" reduces score by 1
     |                           (applied as modifier, not override)
     v
  4. New arrival boost        -- Products created within 14 days get score 5
     |                           (configurable duration and target score)
     v
  5. Tag modifiers            -- "in-stock" adds +1, "NAME BRAND" adds +1,
     |                           "Sale" subtracts -1
     v
  6. Seasonal calendar        -- Category-specific seasonal adjustment
     |                           (from the season x category matrix)
     v
  7. Category default         -- Base score from product type group mapping
     |
     v
  8. Global default           -- Score 2 if no rules match

Modifier Stacking Rules:

• Tag modifiers stack additively (e.g., in-stock +1 and NAME BRAND +1 = +2 total)
• Final score is clamped to the 0-5 range: Math.min(5, Math.max(0, score))
• Override tags (archived, DEAD50) short-circuit all other rules and return 0 immediately
• Manual overrides are respected until the merchant unlocks the product

Real-World Example with Nexus Clothing Data:

Product: "Jordan Craig Stacked Jeans" (active, Winter season)
  Step 1: Manual override?  No (priority_locked = false)
  Step 2: Exclusion tags?   No
  Step 3: Inventory warning? No
  Step 4: New arrival?      No (created > 14 days ago)
  Step 5: Tag modifiers:    NAME BRAND = +1 (store later)
  Step 6: Seasonal calendar: Jeans & Pants, Winter = 4
  Step 7: Category default:  Jeans & Pants = 4 (not needed, seasonal applied)
  Apply modifiers: 4 + 1 (NAME BRAND) = 5
  Final priority: 5 (PUSH HARD)

Product: "Generic Mesh Shorts" (active, Winter season)
  Step 1: Manual override?  No
  Step 2: Exclusion tags?   No
  Step 3: Inventory warning? No
  Step 4: New arrival?      No
  Step 5: Tag modifiers:    None relevant
  Step 6: Seasonal calendar: Shorts, Winter = 0
  Final priority: 0 (EXCLUDE)

Product: "Old Season Hoodie" (archived, DEAD50 tag)
  Step 1: Manual override?  No
  Step 2: Exclusion tags?   Yes -- "archived" found
  Final priority: 0 (EXCLUDE) -- short-circuit, no further processing

Acceptance Criteria:

• Override hierarchy is enforced in the exact order specified
• Manual overrides persist until explicitly unlocked by merchant
• Exclusion tags short-circuit all subsequent rules
• Tag modifiers stack additively and result is clamped to 0-5
• priority_source column records which method determined the final score

2.3.2 Category Mapping

FR-10: Category Rules

Phase: 1 | Priority: P0

The category mapping system translates Shopify product types into priority scores. Because product type names can be long and hierarchical (Nexus uses a {Gender}-{Department}-{SubCategory}-{Detail} convention with 90 unique types), AdPriority groups them into manageable category groups.

Rule Capabilities:

Category Group Structure:

AdPriority organizes 90+ Nexus product types into 20 manageable groups. Each group maps multiple product types to a single set of priority rules.

Acceptance Criteria:

• Merchant can create category groups that map multiple product types to a single priority
• Rules support AND/OR logic for combining conditions
• Unmapped product types receive the global default score (2)
• Category groups are stored per-store (multi-tenant safe)
• Changing a category rule triggers recalculation for all affected products

FR-11: Rule Examples with Nexus Data

Phase: 1 | Priority: P1

The rules engine must support the following patterns, all validated against real Nexus Clothing data:

# Seasonal category rules
IF product_type CONTAINS "Shorts" AND season = "Summer"
  THEN priority = 5

IF product_type CONTAINS "Shorts" AND season = "Winter"
  THEN priority = 0

IF product_type CONTAINS "Hoodies" AND season = "Winter"
  THEN priority = 5

IF product_type CONTAINS "Puffer" AND season = "Summer"
  THEN priority = 0

# Collection-based rules
IF collection = "New Arrivals"
  THEN priority = 5 FOR 14 days

# Tag-based rules (overrides)
IF tag = "archived" OR tag = "DEAD50"
  THEN priority = 0 (override)

IF tag = "clearance"
  THEN priority = 1

# Tag-based rules (modifiers)
IF tag = "NAME BRAND"
  THEN priority + 1

IF tag = "in-stock"
  THEN priority + 1

IF tag = "Sale"
  THEN priority - 1

IF tag = "warning_inv_1"
  THEN priority - 1

# Vendor-based rules (future)
IF vendor = "Nexus Clothing"
  THEN priority + 1 (store brand boost)

Acceptance Criteria:

• All rule patterns above can be expressed in the rules engine
• Rules can be tested with a “preview” mode that shows affected products without applying changes
• Rules are evaluated in priority order (see FR-03 hierarchy)

2.3.3 Product Mapping

FR-20: Product Identification

Phase: 0 | Priority: P0

AdPriority must correctly map Shopify product and variant identifiers to Google Merchant Center product IDs. The mapping is the foundation of the supplemental feed pipeline – an incorrect ID means the custom label will not be applied.

GMC Product ID Format (verified from live GMC export, 124,060 products):

Format:    shopify_US_{productId}_{variantId}
Example:   shopify_US_8779355160808_46050142748904

Components:
  shopify    -- Constant prefix (identifies source platform)
  US         -- Country code (ISO 3166-1 alpha-2)
  8779355160808      -- Shopify product ID (13 digits)
  46050142748904     -- Shopify variant ID (14 digits)

Item Group ID (parent product, used for variant grouping in GMC):

Format:    {productId}
Example:   8779355160808

Verified Real Examples from Nexus GMC Export:

Storage Strategy: Hybrid approach (recommended)

Metafield Schema:

{
  "namespace": "adpriority",
  "key": "config",
  "type": "json",
  "value": {
    "priority": 4,
    "priority_source": "seasonal",
    "priority_locked": false,
    "last_synced_at": "2026-02-10T10:00:00Z",
    "custom_labels": {
      "label_0": "priority-4",
      "label_1": "winter",
      "label_2": "jeans-pants",
      "label_3": "in-stock",
      "label_4": "name-brand"
    }
  }
}

Acceptance Criteria:

• GMC product IDs are generated using the format shopify_US_{productId}_{variantId}
• All variant-level IDs are stored (GMC uses variant-level IDs exclusively)
• Product mapping table has a computed gmc_product_id column
• Mapping handles product ID changes gracefully (e.g., product delete + recreate)

FR-21: Custom Label Structure

Phase: 0 | Priority: P0

AdPriority uses all five Google Merchant Center custom label slots to provide rich segmentation data for Google Ads campaigns. The label schema was designed to stay well within GMC’s limits while providing maximum campaign segmentation flexibility.

Total unique values across all labels: ~38 (well within the 5,000 total limit)

Status Determination Logic:

Brand Tier Determination Logic:

Acceptance Criteria:

• All five custom labels are populated for every active variant in the supplemental feed
• Label values use lowercase with hyphens (e.g., jeans-pants, not Jeans & Pants)
• Label values are within the 100-character maximum per value
• Total unique values per label do not exceed 1,000

2.3.4 Seasonal Calendar

FR-30: Season Definitions

Phase: 2 | Priority: P1

AdPriority uses a four-season calendar with configurable start/end dates. The default configuration follows the Northern Hemisphere retail calendar.

ANNUAL SEASON TIMELINE
=======================

JAN | FEB | MAR | APR | MAY | JUN | JUL | AUG | SEP | OCT | NOV | DEC
|___WINTER____|______SPRING______|______SUMMER______|______FALL______|WIN
       ^              ^                  ^                 ^
     Feb 28         May 31             Aug 31           Nov 30

Configuration Options:

Acceptance Criteria:

• Season detection correctly identifies the current season based on date and timezone
• Season transitions trigger automatic priority recalculation
• Merchants can preview the impact of an upcoming season change before it takes effect
• Manual season override allows merchants to trigger early or late transitions

FR-31: Seasonal Rules

Phase: 2 | Priority: P1

Each category group has a configurable priority score per season. This forms the Category x Season matrix, which is the core of the seasonal automation engine.

Full Seasonal Priority Matrix (Nexus Clothing default configuration):

Holiday Modifiers:

In addition to the seasonal matrix, specific shopping events can temporarily boost priorities:

Holiday Modifier Rules:

• Holiday modifiers are additive on top of the seasonal base score
• Final score is clamped to 0-5 after applying holiday modifiers
• Holiday modifiers do not override manual locks or exclusion tags
• Merchants can enable/disable individual holidays
• Custom holiday events can be created (Growth+ tier)

Acceptance Criteria:

• Seasonal priorities auto-apply on season transition dates
• Category x Season matrix is editable per merchant
• Holiday modifiers apply and expire on the configured dates
• Preview shows exact products and scores that will change on next transition
• Manual season trigger overrides the date-based automatic transition

2.3.5 New Arrival Automation

FR-40: New Arrival Boost

Phase: 2 | Priority: P1

New products added to the store automatically receive a high priority score for a configurable period, ensuring they get advertising visibility during their launch window.

Configuration Parameters:

Behavior:

WITHOUT DECAY (default):
  Day 0-14:   Priority 5 (Push Hard)
  Day 15+:    Falls back to category/seasonal score

WITH DECAY ENABLED:
  Day 0-7:    Priority 5 (Push Hard)
  Day 8-14:   Priority 4 (Strong)
  Day 15-21:  Priority 3 (Normal)
  Day 22+:    Falls back to category/seasonal score

Interaction with Override Hierarchy:

• New arrival boost sits at position 4 in the hierarchy (see FR-03)
• Manual overrides take precedence over new arrival boost
• Exclusion tags (archived, DEAD50) take precedence over new arrival boost
• Inventory warnings take precedence over new arrival boost
• New arrival boost takes precedence over tag modifiers, seasonal rules, and category defaults

Detection Method:

• Shopify created_at timestamp compared against current date
• Products detected via products/create webhook for real-time processing
• Daily reconciliation job catches any missed webhook events

Acceptance Criteria:

• Products created within days_threshold days automatically receive boost_priority score
• Boost expires silently after the threshold period, reverting to standard scoring
• Decay schedule (when enabled) reduces score on the configured interval
• Configuration is per-store, not global
• Manual overrides are not affected by new arrival boost

2.3.6 Google Merchant Center Sync

FR-50: Sync Methods

Phase: 0 (Sheets), 2 (Content API), 1 (CSV) | Priority: P0

AdPriority supports three methods of syncing custom labels to Google Merchant Center, available at different subscription tiers:

Google Sheets Pipeline (MVP and primary method):

AdPriority Database
       |
       |  Google Sheets API (googleapis/sheets/v4)
       v
Google Sheet (shared publicly, Viewer access)
  +----------------------------------------------------------------+
  | id                                    | custom_label_0 | ...    |
  | shopify_US_8779355160808_46050142748904 | priority-5   | ...    |
  | shopify_US_9128994570472_47260097118440 | priority-4   | ...    |
  +----------------------------------------------------------------+
       |
       |  GMC auto-fetches daily (or on manual trigger)
       v
Google Merchant Center
       |
       |  Labels applied to matching products
       v
Google Ads PMAX Campaigns

Feed Size Estimates for Nexus:

Acceptance Criteria:

• Google Sheets supplemental feed is generated with correct column names (id, custom_label_0 through custom_label_4)
• Product IDs in the Sheet exactly match GMC primary feed IDs (case-sensitive)
• Sheet is shared with “Anyone with the link” at Viewer access
• CSV export produces a downloadable file with the same structure
• Content API integration (Pro tier) uses products.custombatch for efficiency

FR-51: Sync Schedule

Phase: 1 | Priority: P0

Sync Status Dashboard:

The UI must display:

• Last sync timestamp
• Number of products pending sync
• Number of products successfully synced
• Number of sync errors
• “Sync Now” button for manual trigger

Acceptance Criteria:

• Scheduled sync runs at merchant-configured intervals (minimum: daily)
• Manual sync trigger writes to Sheet within 60 seconds
• Sync status is visible on the dashboard
• Products with needs_sync = true are included in the next scheduled sync
• After successful sync, needs_sync is set to false and last_synced_at is updated

FR-52: Error Handling

Phase: 1 | Priority: P1

Retry Configuration:

Max retries:          3
Initial delay:        1,000 ms
Backoff multiplier:   2
Maximum delay:        30,000 ms

Acceptance Criteria:

• All sync errors are logged with timestamp, error type, and affected product IDs
• Retry logic uses exponential backoff for transient failures
• Persistent failures (3+ consecutive) trigger a merchant notification
• Manual CSV export is always available as a fallback when automated sync fails
• Error count is displayed on the sync status dashboard

2.3.7 Google Ads Integration (Pro Tier)

FR-60: Performance Data

Phase: 3 | Priority: P2

Pro tier merchants can connect their Google Ads account to view performance metrics segmented by priority tier.

GAQL Query Example:

SELECT
  segments.product_custom_attribute0,  -- priority score label
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM shopping_performance_view
WHERE segments.date DURING LAST_30_DAYS

Acceptance Criteria:

• Performance data is fetched daily and stored in the database
• Dashboard displays ROAS, spend, and conversion data grouped by priority tier
• Historical trend charts show 30, 60, and 90-day windows
• Data is read-only (AdPriority does not modify Google Ads settings)

FR-61: Recommendations

Phase: 3 | Priority: P3

Based on performance data, AdPriority generates actionable recommendations for priority score adjustments.

Acceptance Criteria:

• Recommendations are displayed as dismissible cards in the dashboard
• Each recommendation shows the current score, suggested score, and supporting data
• Merchant can accept (applies change) or dismiss (hides recommendation)
• Dismissed recommendations do not reappear for the same product within 30 days

2.4 Non-Functional Requirements

2.4.1 Performance Requirements

2.4.2 Scalability Requirements

Infrastructure Scaling Approach:

2.4.3 Security Requirements

2.4.4 Availability Requirements

2.5 Integration Requirements

2.5.1 Shopify Integration

IR-01: App Installation

Phase: 1 | Priority: P0

Session Token Claims:

IR-02: Data Access

Phase: 1 | Priority: P0

Required API Scopes:

Data Retrieved from Shopify:

IR-03: Webhooks

Phase: 1 | Priority: P0

Mandatory GDPR Webhooks (required for App Store approval – app will be rejected without these):

App Lifecycle Webhooks:

Product Webhooks:

Webhook Security:

All webhooks must verify the X-Shopify-Hmac-Sha256 header using HMAC-SHA256 with the app’s client secret. Unverified webhooks must be rejected with 401 Unauthorized.

2.5.2 Google Merchant Center

IR-10: Authentication

Phase: 0 (Sheets only, no auth), 2 (Content API) | Priority: P0 (Sheets), P2 (API)

IR-11: API Operations

Phase: 2 (Content API) | Priority: P2

Rate Limits:

2.5.3 Google Ads API (Pro Tier)

IR-20: Authentication

Phase: 3 | Priority: P2

IR-21: API Operations

Phase: 3 | Priority: P2

2.6 UI/UX Requirements

UIR-01: Dashboard

Phase: 1 | Priority: P0

The dashboard is the landing page of the app, providing an at-a-glance view of the store’s priority scoring status.

UIR-02: Product Management

Phase: 1 | Priority: P0

UIR-03: Rules Engine

Phase: 2 | Priority: P1

UIR-04: Seasonal Calendar

Phase: 2 | Priority: P1

UIR-05: Settings

Phase: 1 | Priority: P0

2.7 Data Requirements

DR-01: Nexus Catalog Baseline

The following data has been verified from live Shopify Admin API and GMC product exports:

DR-02: GMC Custom Label Availability

DR-03: GMC Custom Label Constraints

DR-04: Google Sheets Constraints

DR-05: Product ID Format Verification

2.8 Acceptance Criteria

MVP (Phase 0: Nexus Implementation)

Beta Release (Phase 1)

Production Release (Phase 2-3)

2.9 Constraints and Assumptions

Technical Constraints

Platform Constraints

Assumptions

2.10 Out of Scope (v1.0)

The following features are explicitly excluded from version 1.0 and may be considered for future releases:

2.11 Open Questions and Risks

Open Questions

Risks

2.12 Requirement Traceability Matrix

This matrix maps each functional requirement to its implementation phase, source document, and related acceptance criteria.

Summary

This Product Requirements Document defines 21 functional requirements, 24 non-functional requirements, 11 integration requirements, and 5 UI/UX requirement areas for AdPriority. Every requirement traces back to the core problem: retailers waste ad spend by treating all products equally in Google Ads.

The requirements are organized by priority and phase:

• Phase 0 (Week 1-2): Core scoring system (FR-01, FR-20, FR-21, FR-50) validated with Nexus Clothing
• Phase 1 (Week 3-4): SaaS foundation (FR-02, FR-03, FR-10, FR-51, FR-52, IR-01 through IR-03) with 5 beta testers
• Phase 2 (Week 5-8): Full product (FR-11, FR-30, FR-31, FR-40) with seasonal automation and rules engine
• Phase 3 (Week 9-12): App Store launch (FR-60, FR-61, IR-20, IR-21) with billing and scale

Key technical decisions validated during the research phase:

1. GMC product ID format: shopify_US_{productId}_{variantId} – confirmed from 124,060 product export
2. All 5 custom labels available: Only 7 products use label_0 (0.006%), labels 1-4 are empty
3. Supplemental feed pipeline works: 10/10 test products matched in GMC with zero errors
4. Google Sheets capacity is sufficient: ~120,000 cells for Nexus (1.2% of 10M limit)

The next step is to use these requirements as the implementation guide for Phase 0 (Chapter 18) and the architectural foundation for the system design (Chapter 4).