- 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_idis present - the file is treated as matched data and published against your Products catalog.item_idis 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 withcompetitor_. 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. Sendcompetitor_variant_sku whenever the page exposes one: it is the most reliable variant signal.
Example file
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_statusand 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
- 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. - 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.
- Publication. Accepted matches appear on the Competitor matching page.
- Review. Matches wait in Review matches for approval, unless an auto-approval policy approves them.
- Pricing. Approved direct matches that are in stock (or whose availability is unknown) feed competitor prices in Grids, CPI metrics and Price Match rules.
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 withoutitem_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_priceis the active selling price.- If
competitor_regular_priceis present, Retailgrid calculates discount %, promo depth, price gap vs your price and price index from the pair. - If only
competitor_priceis present, it is used as both the active and the regular price.
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.Competitor Prices dataset schema
Competitor Prices dataset schema
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.Related
- Competitor matching - validate a delivery
- Review and approve competitor matches
- Matching uploads API
- Products data spec

