Skip to main content
Competitor prices reach Retailgrid as matched data: one row per link between one of your products and one competitor listing, with the competitor’s price on that listing. Matched data is the main way to load competitor prices. Every row goes through Competitor matching, where you check coverage and quality, then review and approve the matches. Approved matches become the competitor prices your Grids, CPI metrics and Price Match rules read. Matched competitor prices power:
  • Competitive positioning analysis
  • Price gap and price index calculations
  • Dynamic pricing automation
  • Promo monitoring
  • AI elasticity and competitive pressure modeling

How to load matched data

Both accept the same UTF-8 CSV, run the same validation and publish the same way. The API takes one file per request, up to 25 MiB in total. See Matching uploads for coverage options, progress polling and error handling. The header decides how a file is processed:
  • item_id is present - the file is treated as matched data and published against your Products catalog.
  • item_id is absent - the file is treated as a raw competitor export, and Retailgrid matches it to your catalog first. See Raw competitor exports.
Upload the complete matched set on a regular cadence (daily works well), not a delta. Unchanged rows keep their history, and changed prices are recorded as a new observation on the same match.

Matched data schema

Column names are exact and case-sensitive. Every column that describes the competitor’s listing starts with competitor_. Unprefixed columns describe your product (item_id) or the match itself (match_*).

Required columns

Match columns

These describe the match: which of your products the listing is, and on what grounds. They are optional, but send them. The review queue filters and sorts by them, and auto-approval policies use confidence and match type to decide which matches skip manual review.

Price and availability columns

Competitor listing columns

Variant columns

When one competitor page sells several sizes or variants, these columns tell them apart. Send competitor_variant_sku whenever the page exposes one: it is the most reliable variant signal.

Example file

One product matched at two competitors is two rows with the same item_id.

File rules

  • UTF-8 CSV with one header row. The header must fit within 64 KiB.
  • One row = one of your products x one competitor listing.
  • An empty cell means “not stated”. It never means zero.
  • Prices are plain decimals with a dot separator and no thousands separator or currency symbol.
  • All prices in a row share the currency in competitor_currency.
  • Columns not listed on this page are refused. Put extra data in attributes.
  • confidence, verified, matched_by, assurance, review_status and similar review fields are reserved. Retailgrid sets them during validation and review, so a file cannot.
  • Each column may appear only once.

What happens after upload

  1. Header check. The whole file is refused if it has an unknown, reserved or duplicated column, or no item_id. Every problem column is named at once.
  2. Row validation. Each row is checked against the rules above. Refused rows are reported with their line number and a reason code; the rest continue. If too many rows are refused, the whole delivery fails and nothing is published.
  3. Publication. Accepted matches appear on the Competitor matching page.
  4. Review. Matches wait in Review matches for approval, unless an auto-approval policy approves them.
  5. Pricing. Approved direct matches that are in stock (or whose availability is unknown) feed competitor prices in Grids, CPI metrics and Price Match rules.
Coverage controls which existing matches a delivery may retire. The default, partial, never removes competitors the file does not name. full declares the file is everything and retires what it omits. See Matching uploads.

Validation rules

Common reasons a row is refused: A row whose item_id is not in your Products catalog is also refused. Some problems refuse the whole delivery rather than one row:
  • Two rows describe the same match (same item_id, URL and variant).
  • The same competitor URL is variant-specific in one row but not in another.
  • A product’s name, barcode, MPN or size changed in your catalog after the upload started. Re-export those rows and upload again.

Raw competitor exports

If you have competitor listings but no matches yet, upload the same file without item_id and without the match columns (external_match_id, match_relation, match_method, match_confidence). Retailgrid matches each listing to your catalog using the barcode and product name, then publishes the results to Competitor matching for review like any matched file. For the best raw match rate, fill competitor_barcode and competitor_product_name on every row.

Competitor scope

By default every competitor applies to all of your stores. If different stores, pricing zones or sales channels face different rivals, scope each competitor to where it competes - see Assign competitors to stores, zones, and channels. Scoping drives which competitors per-store pricing rules and competitor-gap metrics use.

Price interpretation logic

  • competitor_price is the active selling price.
  • If competitor_regular_price is present, Retailgrid calculates discount %, promo depth, price gap vs your price and price index from the pair.
  • If only competitor_price is present, it is used as both the active and the regular price.
Upload competitor prices in the same currency as your product prices where possible. If several currencies are present, configure FX conversion rules.

Price history

Every delivery is stored. Each match keeps a stable identity across uploads, so a price change on the same listing extends that match’s history instead of creating a new row. This enables:
  • Price change tracking
  • Promo frequency analysis
  • Volatility scoring
  • Price war detection
  • EDLP vs Hi-Lo classification
  • AI elasticity modeling

Other ways to load competitor prices

The Competitor Prices dataset imports price observations directly, without Competitor matching. Use it to backfill historical prices (6-24 months recommended) or when you only have SKU-level observations and no listing URLs. Rows loaded this way are not reviewed in Competitor matching.
Each row is one competitor price observation for one product at a point in time.* At least one identifier (itemId, barcode or sku) is required. Retailgrid links each row to your products by itemId first, then barcode, then sku. Provide itemId for the fewest unlinked rows.Supported formats are CSV (recommended) and XLSX, UTF-8, with a dot decimal separator. One row = one product x one competitor x one timestamp. Extra attributes may be added as columns in CSV / XLSX uploads.Upload fails if datetime, competitorName or regularPrice is missing, no identifier is present, datetime or regularPrice is invalid, rows cannot be linked to your Products dataset, or identical rows are duplicated.API: POST /v1/competitor_prices/bulk (JSON records) or POST /v1/imports/competitor_prices (CSV). JSON uses snake_case names: item_id, observed_at (required), competitor_name (required), regular_price (required), promo_price, source_url, competitor_sku, stock_on_hand, barcode, status, currency. The JSON API rejects unknown fields.