1. Distribution Channel Overview

Product distribution for automotive and off-road e-commerce spans four major channel categories. Not every product belongs on every channel. A chassis frame cannot be sold on Amazon with free two-day shipping, but a bolt-on air shock kit absolutely can. This section maps the full distribution landscape and defines a phased rollout strategy that prioritizes high-impact channels first.

1.1 Channel Categories

Distribution channels fall into four categories based on how they connect products to buyers. Each category has distinct feed requirements, audience behavior, and cost structures.

1.2 Complete Channel Registry

The following table defines every distribution channel in the system. Each channel has a unique key used in the database, a human-readable label, and an assigned implementation phase.

1.3 Phase Roadmap

Phase 1 — Owned Traffic & Discovery (Launch)

Phase 1 channels drive traffic back to your own website. You own the customer relationship, collect the email, and control the checkout experience. These channels require product feeds but do not handle fulfillment or take a sales commission. Implementation cost is low: create the feed files, submit them to each platform, and monitor for errors.

• Google Shopping — highest-intent automotive searches; Shopping tab and Google Images integration
• Bing Shopping — accepts Google feed format directly; 10-15% of search market; older, higher-income demographic
• Meta Commerce — Facebook Shops and Instagram Shopping; strong for lifestyle and build photography
• Pinterest Shopping — long content lifespan (pins circulate for months); strong for project inspiration and build planning

Phase 2 — Marketplace Expansion (Growth)

Phase 2 channels place products on third-party storefronts where the platform controls checkout, payment processing, and often fulfillment expectations. Commission rates range from 8% to 15%. These channels require more operational overhead: inventory sync, order management, returns processing, and platform-specific compliance. Deploy Phase 2 only after Phase 1 feeds are stable and generating consistent traffic.

• YouTube Shopping — links products directly to build videos and install tutorials; powered by Google Merchant Center
• TikTok Shop — emerging channel for younger demographic; strong for viral product discovery
• eBay Motors — established automotive parts marketplace; vehicle compatibility lists are critical
• Amazon — massive reach but high commission (12-15% for automotive); requires FBA or merchant fulfillment
• Walmart Marketplace — growing alternative to Amazon; requires application approval
• ShareASale — affiliate network connecting products to off-road blogs, YouTube channels, and forum influencers

1.4 Channel Decision Tree by Product Type

Not every product belongs on every channel. Use this decision tree to determine which channels apply.

2. Feed Format Specifications

Each distribution channel requires product data in a specific format. While Google and Bing use similar XML schemas, social platforms prefer CSV/TSV flat files. This section provides the complete field mapping for every Phase 1 format, plus notes on Phase 2 marketplace differences.

2.1 Google Merchant XML

Google Shopping feeds use an Atom XML format with the g: namespace for Google-specific fields. This is the most comprehensive feed format and serves as the foundation for Bing and YouTube Shopping feeds.

Field Mapping

XML Structure Example

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:g="http://base.google.com/ns/1.0">
  <title>Patriot Chassis Product Feed</title>
  <link href="https://patriotchassis.com" rel="alternate"/>
  <entry>
    <g:id>PC-AIR-001</g:id>
    <g:title>Patriot Chassis Air Shock Kit - GM 10-Bolt</g:title>
    <g:description>Bolt-on air shock conversion kit...</g:description>
    <g:link>https://patriotchassis.com/product.html?id=PC-AIR-001</g:link>
    <g:image_link>https://patriotchassis.com/images/products/air-shock-kit-gm.jpg</g:image_link>
    <g:price>849.99 USD</g:price>
    <g:availability>in_stock</g:availability>
    <g:brand>Patriot Chassis</g:brand>
    <g:mpn>PC-AIR-001</g:mpn>
    <g:identifier_exists>false</g:identifier_exists>
    <g:condition>new</g:condition>
    <g:google_product_category>Vehicles &amp; Parts > Vehicle Parts &amp; Accessories > Motor Vehicle Parts > Motor Vehicle Suspension Parts</g:google_product_category>
    <g:product_type>Suspension > Air Shock Kits</g:product_type>
    <g:shipping_weight>22.5 lb</g:shipping_weight>
  </entry>
</feed>

2.2 Meta (Facebook/Instagram) CSV

Meta Commerce Manager accepts product data as CSV or TSV files. The format is simpler than Google XML but has strict column naming requirements. Column headers must match exactly.

Column Specification

2.3 Pinterest CSV

Pinterest accepts CSV/TSV feeds through its Catalogs feature. The format closely mirrors Google's field naming but adds Pinterest-specific fields for rich pin display.

Column Specification

2.4 Bing Shopping XML

Microsoft Advertising accepts Google Shopping feeds directly with minimal modification. Bing processes the same Atom XML format and recognizes the g: namespace fields. The primary differences are operational, not format-based.

Key Differences from Google

3. Per-Product Channel Selection

A single "publish to all channels" toggle is inadequate for automotive and off-road e-commerce. A complete rolling chassis cannot be listed on Amazon — it requires freight shipping coordination, has no UPC, and needs customer consultation before purchase. Meanwhile, a bolt-on air shock kit is a perfect Amazon product: fixed price, standard box, UPC-assignable, and shippable via common carriers. Per-product channel selection ensures each product appears only on channels where it can actually be sold and fulfilled.

3.1 Why Per-Product Matters

Automotive products span an enormous range of complexity, price, and fulfillment requirements. Listing a $45,000 turnkey build on Amazon would generate support tickets, bogus orders, and immediate policy violations. Listing a $12 bolt pack only on Google Shopping wastes marketplace potential. Per-product channel assignment prevents three categories of problems:

• Policy violations — Marketplaces reject products that cannot meet their fulfillment and return policies. Oversized freight items without shipping dimensions get disapproved. Products without GTINs get flagged on channels that require them.
• Customer confusion — A "Request a Quote" product appearing on a platform with an "Add to Cart" button creates false expectations. The customer expects to buy; the seller expects a phone call. Both are frustrated.
• Wasted ad spend — Paying CPC for clicks on products that cannot convert on a given platform burns budget. If a product requires a consultation, drive traffic to your own site, not a marketplace.

3.2 Product Type Decision Matrix

The following matrix maps product characteristics to eligible channels. Products must meet ALL criteria in a column to be eligible for that channel.

3.3 Channel Assignment in the Database

Each product's channel assignments are stored in the portal_product_channels table. This table links a product to its enabled channels and stores per-channel overrides.

portal_product_channels
├── id (INT AUTO_INCREMENT PK)
├── product_id (INT FK → portal_products.id)
├── channel_id (INT FK → portal_feed_channels.id)
├── enabled (TINYINT(1), default 1)
├── custom_title (VARCHAR(255), nullable — override for this channel)
├── custom_description (TEXT, nullable — override for this channel)
├── custom_category (VARCHAR(255), nullable — platform-specific category)
└── UNIQUE(product_id, channel_id)

3.4 Per-Channel Overrides

Some products need different titles, descriptions, or categories depending on the platform. Override fields allow customization without duplicating the entire product record.

When to Use Overrides

4. Feed Generation Architecture

Feed generation transforms product data stored in the portal database into platform-specific output files. The system supports multiple sites, multiple channels, and per-product channel selection through a single generation pipeline.

4.1 Data Flow

The feed generation pipeline reads from three primary tables and produces output files for each enabled channel per site.

portal_products (master product data)
    │
    ├── portal_product_channels (per-product channel assignments + overrides)
    │
    └── portal_sites (site configuration: domain, feed URLs, brand info)
          │
          ▼
    Feed Generator (PHP)
          │
          ├── google-feed.xml     (Google Shopping + Bing)
          ├── meta-feed.csv       (Facebook / Instagram)
          ├── pinterest-feed.csv  (Pinterest Catalogs)
          └── generation-log.json (timestamp, counts, errors)

4.2 Multi-Site Support

The portal manages products across multiple sites. Each site has its own domain, brand name, and product catalog. The feed generator produces separate feed files for each site because each platform merchant account is tied to a specific domain.

4.3 File Output & Naming Conventions

Feed files follow a strict naming convention for predictable URLs and automated submission.

/{site-slug}/feeds/
├── google-feed.xml           ← Google Shopping / Bing Shopping
├── meta-feed.csv             ← Facebook / Instagram Commerce
├── pinterest-feed.csv        ← Pinterest Catalogs
├── feed-log.json             ← Generation metadata
└── archive/
    ├── google-feed-2026-02-25.xml    ← Daily archive
    └── meta-feed-2026-02-25.csv

Feed URL Pattern

Each feed is accessible at a predictable URL for platform submission:

https://{domain}/feeds/google-feed.xml
https://{domain}/feeds/meta-feed.csv
https://{domain}/feeds/pinterest-feed.csv

4.4 Generation Process

The feed generator follows a strict sequence to ensure data integrity and traceability.

1. Query eligible products — SELECT products WHERE status = 'approved' AND site_id matches AND channel is enabled in portal_product_channels
2. Apply channel overrides — For each product-channel pair, check for custom_title, custom_description, custom_category, custom_image_url; use override if not NULL, otherwise use base product field
3. Validate required fields — Verify all required fields are present and formatted correctly for the target format; skip products with validation errors and log the reason
4. Transform data — Convert field values to platform-specific formats (e.g., in_stock for Google vs in stock for Meta)
5. Generate output file — Write XML or CSV to the output path
6. Archive previous version — Move the previous feed file to the archive/ directory with a date suffix
7. Write generation log — Record timestamp, product count, error count, and skipped product IDs with reasons

4.5 Generation Logging

Every feed generation run produces a log entry in feed-log.json for debugging and monitoring.

{
  "generated_at": "2026-02-25T14:30:00-07:00",
  "site": "patriotchassis",
  "feeds": {
    "google": { "products": 67, "skipped": 3, "file_size": "48.2 KB" },
    "meta":   { "products": 64, "skipped": 6, "file_size": "22.1 KB" },
    "pinterest": { "products": 58, "skipped": 12, "file_size": "19.8 KB" }
  },
  "errors": [
    { "product_id": 42, "channel": "google", "reason": "Missing image_link" },
    { "product_id": 71, "channel": "meta", "reason": "Price is 0.00" }
  ]
}

5. Feed Quality Requirements

Feed quality directly determines product visibility. Google Merchant Center, Meta Commerce Manager, and Pinterest Catalogs all run automated validation on submitted feeds. Products with missing required fields, invalid images, or price mismatches are disapproved — often silently. This section defines the minimum quality bar for every feed field across all platforms.

5.1 Required Fields by Platform

5.2 Image Specifications by Platform

Image quality is the single most common reason for feed disapprovals. Every platform has specific minimum dimensions, format requirements, and content restrictions.

5.3 Product Identifier Rules

Product identifiers (GTIN, MPN, brand) tell platforms whether your product matches known catalog entries. Incorrect identifier handling is a leading cause of silent disapprovals.

5.4 Price Formatting Requirements

5.5 Availability Status Mapping

Each platform uses slightly different availability values. The feed generator must translate the portal's internal status to the correct platform format.

6. Automotive & Niche Considerations

Automotive aftermarket e-commerce has industry-specific data standards, fitment requirements, and marketplace conventions that do not apply to general retail. This section covers the standards and integrations that matter for chassis, suspension, and off-road product distribution.

6.1 ACES — Aftermarket Catalog Exchange Standard (Phase 2)

ACES is the industry standard for expressing vehicle fitment data — which parts fit which vehicles. It maps products to Year/Make/Model/Submodel (YMMS) combinations using standardized vehicle configuration codes maintained by the Auto Care Association.

Why ACES Matters

• eBay Motors uses ACES-derived compatibility data to power its "Parts Finder" and vehicle compatibility lists
• Amazon Automotive requires ACES-format fitment data for the "Confirm this fits your vehicle" widget
• Google Shopping supports vehicle compatibility via vehicle_compatibility structured data (emerging)
• Distributors and dealers require ACES data to list your products in their catalogs

ACES Data Structure

6.2 PIES — Product Information Exchange Standard (Phase 2)

PIES is the companion standard to ACES. While ACES defines fitment (what vehicles a part fits), PIES defines the product itself — attributes, descriptions, images, dimensions, and marketing content in a standardized format.

PIES Attribute Categories

6.3 eBay Vehicle Compatibility Lists

eBay Motors uses its own vehicle compatibility format derived from ACES. Sellers provide fitment data as a compatibility list attached to each listing. This powers the "This item fits your vehicle" badge that dramatically increases conversion rates.

eBay Compatibility Format

Year | Make | Model | Trim | Engine | Notes
2014 | Chevrolet | Silverado 1500 | LT | 5.3L V8 | 4WD Only
2015 | Chevrolet | Silverado 1500 | LT | 5.3L V8 | 4WD Only
2015 | GMC | Sierra 1500 | SLE | 5.3L V8 | 4WD Only
2016 | Chevrolet | Silverado 1500 | All | 5.3L V8 | 2WD & 4WD

For products without ACES data, build compatibility lists manually from your fitment knowledge. Even a basic list covering the most common applications significantly improves search ranking within eBay Motors. Products with compatibility data receive priority placement in "Parts that fit" search results.

6.4 Amazon Part Finder Integration

Amazon Automotive uses a proprietary fitment system called "Part Finder" that lets buyers enter their vehicle details and see only compatible parts. To participate, sellers must submit fitment data through Amazon's Part Finder template — a flat file mapping each product to Year/Make/Model/Submodel/Engine combinations.

Part Finder Requirements

• Submit fitment data as a separate file from the product listing file
• Each row maps one product SKU to one vehicle application
• A single product may have dozens or hundreds of fitment rows
• Amazon validates fitment data against its own vehicle database
• Products without Part Finder data are severely disadvantaged in automotive search results

6.5 Shipping Dimensions for Oversized Items

Chassis frames, roll cages, and complete suspension kits are oversized freight items. Accurate shipping dimensions are not optional — they directly affect feed approval, shipping cost calculations, and marketplace compliance.

7. Feed Monitoring & Validation

Submitting feeds is only the beginning. Every platform runs ongoing validation against submitted product data and will disapprove individual products or suspend entire feeds when issues are detected. Monitoring is not a launch task — it is an ongoing operational responsibility.

7.1 Google Merchant Center Diagnostics

Google Merchant Center provides the most detailed diagnostics of any platform. It categorizes issues by severity and provides specific fix instructions for each disapproved product.

Common Disapprovals & Fix Strategies

Severity Levels

7.2 Meta Commerce Manager Validation

Meta's validation is less granular than Google's but equally strict on required fields. The Commerce Manager dashboard shows feed health with a percentage score and categorizes issues by type.

Common Meta Feed Issues

• Image contains too much text — Meta's 20% text rule applies to product images in ads; keep product images clean
• Description too short — Meta recommends substantial descriptions; one-line descriptions get flagged
• Invalid availability value — Must be in stock (space-separated), not in_stock (underscore)
• Non-HTTPS image URL — All image URLs must use HTTPS; HTTP URLs are rejected
• Duplicate IDs — Each product must have a unique id value across the entire feed

7.3 Pinterest Catalog Validation

Pinterest Catalogs provides a feed health dashboard showing processing status, active pins, and errors. Pinterest is generally more lenient than Google or Meta but still requires core fields.

• Image aspect ratio — Pinterest penalizes landscape images in favor of square or vertical; non-vertical images get less distribution
• Unverified domain — Feed links must point to a domain you have verified in Pinterest Business; unverified domains are rejected
• Price format — Must include currency code; $849.99 is invalid; 849.99 USD is correct

7.4 Scheduled Regeneration

Feed freshness matters. Platforms penalize stale feeds and reward frequent updates. The following schedule balances server load with data freshness.

8. Implementation Checklist

This checklist covers every step from initial setup through ongoing maintenance. Complete each section in order. Do not submit feeds to platforms until all pre-launch items are verified.

8.1 Pre-Launch Verification

• All products have complete titles (under 150 chars, keyword-rich, brand included)
• All products have descriptions (minimum 300 words for standard products; plain text, no HTML)
• All product images meet minimum 1200x1200px, JPEG format, no text overlays or watermarks
• Pinterest-specific vertical images (1000x1500px) created for visual products
• Every product has either a valid GTIN, MPN, or identifier_exists=false
• All prices are in amount currency format (e.g., 849.99 USD) with 2 decimal places
• Feed prices match landing page prices exactly (verified manually for at least 10 products)
• All product URLs resolve to live, HTTPS pages with the correct product displayed
• Availability status accurately reflects actual stock for every product
• Google product categories assigned using the official Google taxonomy
• Shipping weight and dimensions provided for all items over 20 lb
• Feed generator tested locally; output validates against platform specifications
• Feed archive directory exists and has write permissions
• Generation log (feed-log.json) writes successfully with zero errors

8.2 Channel Account Setup

Google Shopping

• Google Merchant Center account created and verified
• Website URL claimed and verified (HTML tag or DNS method)
• Business information completed (name, address, phone, return policy URL)
• Shipping settings configured (table rates, flat rate, or free shipping threshold)
• Tax settings configured (auto tax collection or manual state-by-state)
• Feed submitted via URL fetch (preferred) or direct upload
• Google Ads account linked for Shopping campaigns

Bing Shopping

• Microsoft Merchant Center store created
• Website URL verified
• UET (Universal Event Tracking) tag installed on all pages
• Minimum 50 UET events recorded before feed submission
• Feed submitted (same XML URL as Google, or use auto-import from Google)
• Microsoft Advertising account linked

Meta Commerce

• Facebook Business Manager account configured
• Commerce Manager catalog created
• Domain verified in Business Settings
• Meta Pixel installed on all pages with ViewContent, AddToCart, Purchase events
• CSV feed uploaded or URL fetch configured
• Instagram Shopping enabled (requires approved Instagram Business account)

Pinterest Shopping

• Pinterest Business account created
• Website claimed and verified
• Pinterest Tag installed on all pages
• Catalog source created with feed URL
• Product groups configured for ad targeting
• Rich Pins validated using the Pinterest URL Debugger

8.3 Feed URL Submission

Each platform needs to know where to fetch your feed. Submit the following URLs after your feed generator is deployed and producing valid output.

8.4 Ongoing Maintenance

• Check Google Merchant Center diagnostics weekly for new disapprovals
• Check Meta Commerce Manager feed health weekly
• Check Pinterest Catalog processing status weekly
• Verify feed generation log daily for errors or skipped products
• Regenerate feeds immediately after any price change or stock update
• Review and update Google product categories quarterly (taxonomy updates)
• Audit product images quarterly — replace low-quality or outdated images
• Test all product URLs monthly — detect and fix broken links before platforms do
• Review channel performance monthly — disable underperforming channels, optimize high-performers
• Archive old feed files monthly — keep 30 days of history, purge older archives

9. New Site Onboarding Playbook

This section is the repeatable playbook for bringing a brand-new site into the feed distribution system. Every site — whether it sells chassis, trailers, ranch equipment, or fabrication tools — follows the same sequence. The system is designed so that a new site can go from zero to live feeds in a single working session once its products are in the portal.

9.1 Step 1 — Build Process Discovery (Q9b)

During the Build Process Discovery phase (Question 9b), the client selects which distribution channels apply to their business. The Build Process form (/build-process/index.html) presents all 10 channels organized by category:

The client's channel selections during Discovery determine which channels get enabled at the site level in Step 3. Phase 2 channels (YouTube, TikTok, eBay, Amazon, Walmart, ShareASale) can be selected during Discovery for planning purposes — they appear dimmed in the portal UI until implementation is ready.

9.2 Step 2 — Product Pipeline Completion

Products must pass through the portal workflow before they can appear in feeds. The feed generator only includes products with status = 'approved' or status = 'live'. The minimum viable product record for feed eligibility requires:

9.3 Step 3 — Enable Site Channels

After products are loaded, enable the channels selected during Discovery at the site level via the Hub Feeds dashboard (/hub/feeds.html).

1. Open Hub → select the site from the site picker
2. The Channels tab shows all 10 channels with toggle switches
3. Enable the channels chosen during Discovery (Q9b)
4. For each enabled channel, optionally set:
   • merchant_id — Google Merchant ID, Meta Catalog ID, etc.
   • feed_url — the public URL where the generated feed will be served
   • config — channel-specific JSON (rare for Phase 1)
5. Site-channel configuration is stored in portal_site_channels

9.4 Step 4 — Assign Products to Channels

Use the Distribution tab (10th tab) in the Product Editor for per-product channel assignment.

1. Open the portal → select the site → open a product
2. Navigate to the Distribution tab
3. Check/uncheck channels for this product (only site-enabled channels are interactive; others are dimmed)
4. Optionally expand "Customize" on any channel to set:
   • custom_title — platform-optimized title (e.g., shorter for Google, lifestyle-focused for Pinterest)
   • custom_description — channel-specific description override
   • custom_category — platform-specific taxonomy path
5. Save — assignments are stored in portal_product_channels

9.5 Step 5 — Generate & Verify Feeds

1. Open Hub → Feeds → select the site
2. Click "Generate" on each enabled channel
3. Verify the product count matches expectations
4. Download and spot-check the generated file:
   • XML feeds: validate with W3C Feed Validator; check for entity encoding, proper g: namespace
   • CSV feeds: open in a spreadsheet; verify column headers, no broken UTF-8, prices formatted correctly
5. Check the Generation Log tab for any errors

9.6 Step 6 — Deploy Feed Files to Production

Feed files must be accessible at public URLs on the site's production domain for platforms to fetch them. Deploy using the standard DevHub → Production pipeline.

# Feed output directory structure on production:
/{site-docroot}/feeds/
├── google-merchant.xml
├── bing-shopping.xml
├── facebook-catalog.csv
└── pinterest-catalog.csv

# URLs submitted to platforms:
https://{domain}/feeds/google-merchant.xml
https://{domain}/feeds/bing-shopping.xml
https://{domain}/feeds/facebook-catalog.csv
https://{domain}/feeds/pinterest-catalog.csv

9.7 Step 7 — Platform Account Setup

For each enabled channel, create the platform merchant account and submit the feed URL. See Section 8.2 for the detailed checklist per platform. The sequence is always:

1. Create merchant/business account on the platform
2. Verify domain ownership (HTML meta tag, DNS TXT record, or file upload)
3. Install tracking pixel/tag on all site pages (Google Tag, Meta Pixel, Pinterest Tag, UET Tag)
4. Configure shipping and tax settings
5. Submit feed URL for scheduled fetching (daily recommended)
6. Wait for initial processing (Google: ~30 min, Bing: up to 3 days, Meta: ~1 hour, Pinterest: ~24 hours)
7. Review diagnostics for disapprovals and fix any issues

9.8 Onboarding Checklist (Copy Per Site)

• Site exists in portal_sites with correct domain, slug, and name
• Q9b Discovery channels documented and agreed with client
• Products loaded in portal with all required fields (see 9.2 table)
• Products reviewed: images present, descriptions ≥ 50 chars, prices set, SKUs unique
• Products advanced to approved or live status
• Site channels enabled in Hub Feeds dashboard
• Per-product channel assignments completed in Distribution tab
• Feeds generated successfully with expected product counts
• Feed files deployed to production domain
• Feed URLs accessible via HTTPS with no auth required
• Platform merchant accounts created for each enabled channel
• Domain verified on each platform
• Tracking pixels installed (Google Tag, Meta Pixel, Pinterest Tag, UET)
• Feed URLs submitted for scheduled daily fetching
• Initial diagnostics reviewed — zero disapprovals
• Feed regeneration schedule configured (daily at 2:00 AM)

10. Data Quality & Sanitization Rules

Product data in the portal database often contains HTML entities, formatting artifacts, and inconsistent whitespace that would pollute feed output. The feed generator applies automatic sanitization to every text field before writing it to any feed format. These rules are enforced in code and documented here so they are consistently applied across all sites.

10.1 Text Sanitization Pipeline

Every text field (title, description, category, brand) passes through the sanitize_for_feed() function before being written to any feed output. The pipeline runs in this exact order:

1. Strip HTML tags — Remove all HTML tags (<strong>, <em>, <br>, etc.). Feed platforms require plain text and will reject or misrender HTML.
2. Decode HTML entities — Convert all numeric and named entities to their UTF-8 characters:

   Entity	Character	Common Source
   ″	″ (double prime / inch mark)	WordPress smart quotes on measurements like 4″
   ’	’ (right single quote / apostrophe)	WordPress smart apostrophes in possessives
   “ / ”	“ / ” (smart double quotes)	WordPress content editor
    	(non-breaking space)	Rich text editors, copy-paste from Word
   &	&	Double-encoded ampersands
   –	– (en dash)	WordPress auto-typography
   —	— (em dash)	WordPress auto-typography

3. Normalize whitespace — Collapse all runs of spaces, tabs, newlines, and non-breaking spaces into a single space character.
4. Trim — Remove leading and trailing whitespace.

10.2 Description Length Rules

Each platform has minimum and maximum description length requirements. Descriptions that are too short get flagged or reduce product visibility. The feed generator enforces these rules automatically:

Description Cascade Priority

1. custom_description (per-channel override from Distribution tab)
      ↓ if NULL
2. short_description (if ≥ 50 characters after sanitization)
      ↓ if under 50 chars
3. full_description (truncated to 5,000 characters)
      ↓ if also empty
4. Empty string (product may be disapproved)

Platform Minimum Recommendations

10.3 Image Validation Rules

The feed generator enforces image requirements at the product level. These rules ensure no feed entry is submitted without the required image data.

Image URL Construction

# Relative path in database:
images/gallery/air-shock-hero.jpg

# Constructed feed URL:
https://patriotchassis.com/images/gallery/air-shock-hero.jpg

# Resolution priority for primary image:
1. is_primary = 1 flag on portal_product_images row
      ↓ if no primary flag set
2. role = 'hero' on any image row
      ↓ if no hero role
3. Lowest sort_order value (first image uploaded)

10.4 Price Validation

10.5 Identifier Fallback Logic

# Identifier resolution for each product:
IF gtin IS NOT NULL → output g:gtin
IF mpn IS NOT NULL  → output g:mpn
IF both NULL        → output g:identifier_exists = false

# Brand fallback:
IF brand IS NOT NULL → use brand
ELSE                 → use site_name from portal_sites
ELSE                 → "Unknown"

10.6 Data Quality Audit Query

Run this query against any site to identify feed-readiness gaps before generating feeds. Replace ? with the site_id.

SELECT
  COUNT(*) as total_products,
  SUM(CASE WHEN status IN ('approved','live') THEN 1 ELSE 0 END) as feed_eligible,
  SUM(CASE WHEN price_type = 'fixed' AND price_cents IS NOT NULL THEN 1 ELSE 0 END) as has_price,
  SUM(CASE WHEN gtin IS NOT NULL AND gtin != '' THEN 1 ELSE 0 END) as has_gtin,
  SUM(CASE WHEN mpn IS NOT NULL AND mpn != '' THEN 1 ELSE 0 END) as has_mpn,
  SUM(CASE WHEN weight_lbs IS NOT NULL THEN 1 ELSE 0 END) as has_weight,
  SUM(CASE WHEN LENGTH(short_description) >= 50 THEN 1 ELSE 0 END) as desc_adequate,
  SUM(CASE WHEN LENGTH(short_description) < 50 THEN 1 ELSE 0 END) as desc_thin
FROM portal_products
WHERE site_id = ? AND active = 1;

-- Image coverage:
SELECT p.id, p.name, COUNT(i.id) as image_count
FROM portal_products p
LEFT JOIN portal_product_images i ON i.product_id = p.id
WHERE p.site_id = ? AND p.active = 1
GROUP BY p.id
HAVING image_count = 0;

Appendix A: Quick Reference

Appendix B: Database Schema Reference

All feed distribution tables live in the jj_wordpress database (or the site-specific database for the current DevHub user) alongside the other portal_ tables. The schema is designed for multi-site operation — every table references portal_sites.id or portal_products.id as the site/product foreign key.

B.1 portal_feed_channels (Master Channel Registry)

Seeded with 10 channels. Rarely modified after initial creation. Shared across all sites.

B.2 portal_site_channels (Per-Site Channel Config)

Which channels are enabled for each site, plus platform-specific credentials.

B.3 portal_product_channels (Per-Product Channel Assignments)

The checkbox data — which products go on which channels, with optional per-channel overrides.

B.4 portal_feed_generations (Generation History/Log)

Every feed generation event is logged here for audit trail and monitoring.

B.5 Seed Data (10 Channels)

| channel_key        | label                       | category    | feed_format   | phase |
|--------------------|-----------------------------|-------------|---------------|-------|
| google-shopping    | Google Shopping              | search      | google-xml    | 1     |
| bing-shopping      | Bing / Microsoft Shopping   | search      | bing-xml      | 1     |
| facebook-instagram | Facebook & Instagram        | social      | meta-csv      | 1     |
| pinterest          | Pinterest                   | social      | pinterest-csv | 1     |
| youtube-shopping   | YouTube Shopping             | social      | google-xml    | 2     |
| tiktok-shop        | TikTok Shop                 | social      | google-xml    | 2     |
| ebay-motors        | eBay Motors                 | marketplace | custom        | 2     |
| amazon-auto        | Amazon Automotive           | marketplace | custom        | 2     |
| walmart            | Walmart Marketplace         | marketplace | custom        | 2     |
| shareasale         | ShareASale                  | affiliate   | custom        | 2     |

B.6 Related Schema Modifications

• portal_product_section_status.section ENUM — 'distribution' added as 10th section
• portal_permissions — manage_feeds permission added (category: admin, sort_order: 5)
• products.php line 83 — section divisor changed from /9 to /10 for completion percentage

Appendix C: API Endpoint Reference

All feed distribution APIs follow the same patterns as other portal APIs: JSON request/response, same database config (portal/api/config.php), same error format.

C.1 Portal API — Product Channel Assignments

File: /portal/api/product-channels.php

C.2 Hub API — Channel Management

File: /hub/api/feed-channels.php

C.3 Hub API — Feed Generation

File: /hub/api/feed-generate.php

C.4 Hub API — Generation History

File: /hub/api/feed-history.php

C.5 Feed Generator Engine (Internal)

File: /hub/api/feed-generator.php — included by feed-generate.php, never called directly via HTTP.

Helper Functions

C.6 .htaccess Allowlist

The Hub API directory uses a deny-by-default .htaccess. The following feed-related files are explicitly allowed:

<Files "feed-channels.php">
    Require all granted
</Files>

<Files "feed-generate.php">
    Require all granted
</Files>

<Files "feed-history.php">
    Require all granted
</Files>

feed-generator.php is intentionally NOT in the allowlist — it is an internal include file and must never be accessible via HTTP.

Appendix D: Sources & References