Prepare your product feed

This guide explains how to format your product data for The Comparator. A clean, accurate feed ensures that your offers are mapped to the correct hardware components in our normalized database.

1. What a product feed is

A product feed is a structured data file containing your store’s current inventory, prices, and stock availability.

• One record = one offer: Each row or object represents one specific variant of a hardware component.
• Stable IDs: Your product SKU/ID must not change between feed updates. This allows our system to track price history and availability without creating duplicate records.
• Value Engine independence: Submitting a feed registers your store in our “Where to Buy” comparison blocks. It does not alter the Value Score or organic ranking of any product, which is calculated strictly algorithmically.

2. Supported submission methods

Currently, integrating a new retailer requires an assisted onboarding process. You provide the feed URL or file, and our integration team configures the import mapping.

3. Exact field reference

Our import pipeline accepts the following fields. Ensure your feed columns or JSON keys map to these definitions.

4. Stable product ID rules

Your id field is the primary key linking your offer to our database.

• Do not change the ID when a product’s price or stock status updates.
• Do not reuse an old ID for a different hardware model.
• Do not use row numbers or generate random UUIDs on every export.
• Allowed characters: Alphanumeric characters, hyphens, underscores ([A-Za-z0-9_-]). Max 64 characters.

5. Hardware product titles

Hardware matching relies on title parsing when GTIN/MPN are missing. Write clear, technical titles rather than marketing slogans.

GPU (Graphics Cards)

Include Board Partner, exact GPU chip model, VRAM capacity, and suffixes (Ti, SUPER, XT, XTX).

• Good: ASUS TUF Gaming GeForce RTX 4070 Ti SUPER OC 16GB
• Poor: Awesome Gaming Graphics Card RTX 4070 - Best Deal!

CPU (Processors)

Include Brand, exact model number, and suffixes (K, KF, F, X, X3D).

• Good: AMD Ryzen 7 7800X3D Boxed
• Poor: Fast 8-Core AMD Processor for PC

SSD (Solid State Drives)

Include Brand, Series model, Capacity, Form Factor, and Interface.

• Good: Samsung 990 PRO 2TB NVMe M.2 PCIe 4.0 SSD
• Poor: Super Fast 2TB Internal Hard Drive

RAM (Memory)

Include Brand, Series, Total Capacity, Module Count, Generation, and Speed.

• Good: G.SKILL Trident Z5 RGB 32GB (2x16GB) DDR5 6000MHz CL30
• Poor: 32GB High Speed RAM Kit

Motherboards

Include Brand, Model, Chipset, Socket, and Wi-Fi revision.

• Good: MSI MAG B650 TOMAHAWK WIFI ATX AM5 Motherboard
• Poor: MSI AM5 Gaming Mainboard

6. Product identifiers (GTIN, MPN, Brand)

• GTIN (EAN / UPC): Must be valid GS1 GTINs. Do not put internal SKUs into the GTIN field.
• MPN: Include exact manufacturer part numbers (e.g., 100-100000910WOF). Do not strip hyphens or trailing suffixes.
• Brand: Canonical manufacturer name (e.g., ASUS, Gigabyte, MSI, AMD, Intel, NVIDIA, Western Digital).

7. Price and currency

• Formatting: Plain decimal number without currency symbols (e.g., 599.99, not $599.99).
• Currency: Currently, only USD is supported.
• Landing Page Match: The price in the feed must match the price on your product page. Hidden prices unlocked only via checkout promo codes are prohibited.

8. Availability mapping

We normalize store availability into standardized internal states:

9. Condition standards

The Comparator categorizes offers into three distinct condition buckets:

• New: Factory sealed, brand new item with full manufacturer warranty.
• Refurbished: Factory or seller refurbished. Must be explicitly flagged.
• Used: Second-hand or pre-owned item.

10. Product URL requirements

• Must lead directly to the individual product page (no search results or category pages).
• Must be publicly accessible without login, cookies, or captcha blocks.
• Must use clean, canonical HTTPS URLs.

11. Image URL requirements

• Direct image file URL (.jpg, .png, .webp) over HTTPS.
• Must not lead to HTML viewer pages or require authentication.

12. Variants, kits and bundles

• RAM Kits & SSDs: List exact total capacity and module breakdown (e.g., 32GB (2x16GB)).
• Component Bundles & Pre-built PCs: UNSUPPORTED. Our matching pipeline (isComboListing filter) automatically rejects CPU+Motherboard combos, PC cases, and pre-built systems. Submit individual components only.

13. Refresh and deletion semantics

• Sync Interval: Default sync occurs every 24 hours. Priority accounts sync hourly.
• Missing Rows: If a product SKU is missing from 2 consecutive feed fetches, it is marked out_of_stock.
• Stale Feeds: If a feed fetch fails for >48 hours, all offers from the store are temporarily hidden until the feed recovers.

14. Validation process stages

Our import pipeline validates data through 3 severity levels:

[Feed Retrieval] ➔ [Parsing] ➔ [Schema Validation] ➔ [Hardware Matching] ➔ [Publication]

• 🔴 Error (Blocking): Missing SKU, malformed price, or unparseable XML/JSON. Offer is rejected.
• 🟡 Warning (Non-blocking): Missing image link or missing GTIN. Offer is published, but flagged for manual review.
• 🔵 Info: Advice on improving title formatting.

15. Troubleshooting common errors

16. Pre-submission checklist

• Product IDs (SKUs) are stable, non-empty, and unique.
• Prices parse cleanly as decimals without $ symbols.
• Currency is explicitly set to USD.
• Stock availability is accurate (in_stock / out_of_stock).
• Product titles contain exact hardware specs (VRAM, Model, Suffixes).
• At least one identifier (gtin or mpn) is provided per row.
• Bundles and pre-built PCs are excluded.
• Product URLs open directly without authentication.

17. Working sample files

Download our validated sample feeds to test your export configuration:

• 📄 Download Sample CSV Feed
• 📄 Download Sample JSON Feed
• 📄 Download Sample Google Merchant XML Feed

You can validate your sample feeds locally using our validation command:

node scripts/test_sample_feeds.js