Retailer Academy | PC Part Comparator

Manage your feed and mapping results

Mon, 01 Jan 0001 00:00:00 +0000

Manage your feed and mapping results

The Comparator uses an assisted onboarding and operational management workflow. We do not operate a self-service merchant portal or login dashboard at this time.

This guide explains how your store interacts with our integration team, how to read your CSV Mapping Reports, and how to submit corrections.

1. Operational Workflow Overview

Because hardware matching requires strict technical accuracy, our engineering team manages the ingest pipeline.

[1. Submit Feed] ➔ [2. Ingestion & Validation] ➔ [3. CSV Mapping Report] ➔ [4. Submit Corrections] ➔ [5. Live Sync]

Submit Application & Feed: You submit your store application and feed URL via .
Initial Pipeline Ingestion: Our system fetches your feed, validates schema rules, and attempts matching against our hardware reference database (ref_specs.json).
Receive CSV Mapping Report: Our integration team emails you a CSV report detailing matched, ambiguous, and rejected items.
Review & Correct: You review the CSV, update missing MPNs/GTINs in your feed or annotate corrections, and email it back to retailers@thecomparator.tech.
Live Publication & Sync: We apply your mapping overrides to our pipeline configuration (corrections.json). Your matched products appear live in the comparison tables.

2. Onboarding Interface & Screenshots

Retailer Application Interface (`/retailers/apply/`)

When you register your store, you submit your details through our partner application form:

Figure 1: The partner application form. Confirmation text verifies that no portal login or setup call is required at this stage.

Feed Requirements Reference (`/retailers/feed-requirements/`)

Technical guidelines for feed formats can be reviewed at any time:

Figure 2: The technical feed requirements page detailing accepted CSV, JSON, and XML structures.

3. Reading the Mapping Report (CSV Format)

When your feed is processed, our team generates a Mapping Report (CSV format).

Structure of the CSV Mapping Report

Header	Example Value	Description
`sku`	`GPU-4070S-01`	Your internal product ID.
`feed_title`	`ASUS TUF Gaming GeForce RTX 4070 Ti SUPER OC 16GB`	Original title string from your feed.
`matched_model`	`NVIDIA GeForce RTX 4070 Ti SUPER`	Canonical hardware model in The Comparator DB.
`status`	`Matched`	Processing outcome (`Matched`, `Ambiguous`, `Review`, `Rejected`).
`issue_code`	`NONE`	Diagnostic code for warnings or rejections.
`live_url`	`https://thecomparator.tech/gpu/rtx-4070-ti-super/`	Target page on The Comparator where offer appears.

4. Status Meanings & Issue Codes

Mapping Status Definitions

✅ Matched: The item was successfully identified and matched to a canonical hardware model. It will appear live when in_stock.
⚠️ Ambiguous: Our algorithm found multiple possible hardware matches (e.g., could not distinguish between a 12GB and 16GB variant due to vague title). Requires manual correction.
🔍 Review: The offer was flagged for manual review (e.g., price is 40% below market average). Held until verified.
❌ Rejected: The offer cannot be imported (e.g., unsupported category or bundle).

Diagnostic Issue Codes

NON_COMPONENT_ACCESSORY: Item is a PC case, water block, or bracket. (Safely ignored by importer).
PRICE_ANOMALY: Price is significantly outside expected hardware bounds.
ERR_NO_IDENTIFIER: Title is vague and no GTIN/MPN was provided.
COMBO_OR_BUNDLE: Item contains multiple components (rejected by isComboListing filter).

5. How to Submit Mapping Corrections

If an item was marked Ambiguous or matched to the wrong hardware variant:

Open your CSV Mapping Report in Excel or Google Sheets.
Add a column titled Correction.
Enter the exact canonical hardware name or URL from The Comparator (e.g., https://thecomparator.tech/gpu/rtx-4070-super/).
Email the annotated CSV to retailers@thecomparator.tech with subject line Mapping Corrections - [Store Name].

Our team applies your corrections within 24 hours, updating cpu_corrections.json or mobo_sata_corrections.json in the live pipeline.

6. Escalating Incorrect Live Offers

If a live offer displays an incorrect price or links to the wrong landing page:

Check your source feed to ensure the SKU and price are correct.
Send an email to retailers@thecomparator.tech with subject: URGENT: Live Price Mismatch - [Store Name].
Include the SKU, wrong live URL, and correct landing page link.
Emergency escalations are processed within 4 hours.

Prepare your product feed

Mon, 01 Jan 0001 00:00:00 +0000

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.

Submission Method	Supported?	Format	Authentication	Max File Size	Refresh Frequency	Error Notification
Public Feed URL	Yes (Preferred)	CSV / JSON / XML	HTTP Basic Auth or None	50 MB	Scheduled (Daily/Hourly)	Email Mapping Report
Google Merchant XML	Yes	RSS 2.0 XML	None	50 MB	Scheduled	Email Mapping Report
Affiliate Network	Yes	Network Feed	Network Auth	Dependent on Network	Daily	Email Mapping Report
Self-Service API	Planned	REST / Webhooks	Bearer Token	N/A	Real-time	API Response

Note

Operational Note: If your feed requires authentication or IP allowlisting, provide the details during your application at .

3. Exact field reference

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

Field	Required Status	Data Type	Example	Validation Rule	Used For
`id`	Required	String	`GPU-4070S-01`	Non-empty, unique per item, max 64 chars	Tracking SKU & price history
`title`	Required	String	`ASUS TUF Gaming GeForce RTX 4070 Ti SUPER OC 16GB`	Must contain brand & hardware model	Model matching & UI display
`link`	Required	URL	`https://example.com/gpu-4070`	Valid HTTP/HTTPS URL, reachable without login	Directing buyers to purchase
`price`	Required	Decimal	`599.99`	Positive number, 2 decimal places	Value calculation & display
`currency`	Required	String	`USD`	Must be `USD` (US market active)	Price normalization
`availability`	Required	String	`in_stock`	Must match accepted stock strings	Filtering active offers
`condition`	Required	String	`New`	`New`, `Refurbished`, or `Used`	Value Engine grouping
`brand`	Required	String	`ASUS`	Non-empty manufacturer name	Hardware Fingerprinting
`gtin`	Conditionally Required	String	`4711387450889`	Valid EAN/UPC digits (12-14 digits)	Exact product matching
`mpn`	Conditionally Required	String	`90YV0J80-M0NA00`	Exact Manufacturer Part Number	Exact product matching
`image_link`	Recommended	URL	`https://example.com/img.jpg`	Valid direct image URL (HTTPS)	Fallback UI visuals
`shipping`	Optional	Decimal	`9.99`	Non-negative decimal	Total Cost of Ownership (TCO)

Important

Identifier Requirement: You must provide either a valid gtin or an mpn (or both) for reliable hardware matching. Feeds relying solely on titles have a 35% higher rejection rate due to ambiguity.

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:

Retailer Feed Value	Normalized Internal State	Published on Site?	Notes
`in_stock`, `available`, `instock`	`in_stock`	Yes	Displayed in active comparison table.
`out_of_stock`, `sold_out`, `unavailable`	`out_of_stock`	No	Hidden from default view (archived).
`preorder`, `backorder`	`preorder`	No	Temporarily held until stock arrives.

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.

Warning

Do not list refurbished or used items as New. Mislabeled conditions result in permanent store suspension.

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

Error Code	Issue Description	Bad Feed Example	Fixed Example	Blocking?
`ERR_MISSING_ID`	SKU field is empty	`""`	`"GPU-4070-01"`	🔴 Yes
`ERR_INVALID_PRICE`	Currency symbol in price	`"$599.99"`	`599.99`	🔴 Yes
`ERR_UNSUPPORTED_CURRENCY`	Currency is not USD	`"EUR"`	`"USD"`	🔴 Yes
`ERR_AMBIGUOUS_TITLE`	Title lacks model info	`"NVIDIA RTX Card"`	`"ASUS RTX 4070 SUPER 12GB"`	🔴 Yes
`ERR_COMBO_REJECTED`	Component bundle detected	`"Ryzen 7 + B650 Bundle"`	Exclude from feed	🔴 Yes
`WARN_MISSING_GTIN`	No GTIN or MPN provided	`gtin: ""`	`gtin: "4711387450889"`	🟡 No

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:

📄
📄
📄

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

node scripts/test_sample_feeds.js

Retailer Academy | PC Part Comparator

Manage your feed and mapping results

Manage your feed and mapping results

1. Operational Workflow Overview

2. Onboarding Interface & Screenshots

Retailer Application Interface (/retailers/apply/)

Feed Requirements Reference (/retailers/feed-requirements/)

3. Reading the Mapping Report (CSV Format)

Structure of the CSV Mapping Report

4. Status Meanings & Issue Codes

Mapping Status Definitions

Diagnostic Issue Codes

5. How to Submit Mapping Corrections

6. Escalating Incorrect Live Offers

Prepare your product feed

Prepare your product feed

1. What a product feed is

2. Supported submission methods

3. Exact field reference

4. Stable product ID rules

5. Hardware product titles

GPU (Graphics Cards)

CPU (Processors)

SSD (Solid State Drives)

RAM (Memory)

Motherboards

6. Product identifiers (GTIN, MPN, Brand)

7. Price and currency

8. Availability mapping

9. Condition standards

10. Product URL requirements

11. Image URL requirements

12. Variants, kits and bundles

13. Refresh and deletion semantics

14. Validation process stages

15. Troubleshooting common errors

16. Pre-submission checklist

17. Working sample files

Retailer Application Interface (`/retailers/apply/`)

Feed Requirements Reference (`/retailers/feed-requirements/`)