> ## Documentation Index > Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt > Use this file to discover all available pages before exploring further. # Competitor prices > The Competitor Prices dataset allows you to upload, monitor, and analyze competitor pricing at SKU level over time. The **Competitor Prices** dataset allows you to upload, monitor, and analyze competitor pricing at SKU level over time. This dataset powers: * Competitive positioning analysis * Price gap and price index calculations * Dynamic pricing automation * Promo monitoring * AI elasticity and competitive pressure modeling Each row represents: > **One competitor price observation for one product at a specific point in time** ## Dataset structure Competitor Prices is a **time-series dataset**. You can upload: * Historical snapshots (6–24 months recommended) * Daily / weekly price updates * Automated feeds (scraping, Google Shopping, APIs) ## Data schema All required and optional fields are listed below. | Field Name | Required | Type | Format | Description | Alternative Names | Example | | :--------------- | :------- | :------- | :------------------ | :---------------------------------------------------------- | :------------------------------------------- | :------------------------------------------------------------- | | `itemId` | ✅ Yes | string | Text | Unique SKU-level identifier linked to your Products dataset | item\_id, sku\_id, product\_code | SKU-1001 | | `datetime` | ✅ Yes | datetime | YYYY-MM-DD HH:MM:SS | Date & time of price observation | date, timestamp, observed\_at, price\_date | 2026-02-22 14:35:00 | | `competitorName` | ✅ Yes | string | Text | Competitor / retailer name | competitor, seller, shop\_name, retailer | Bauhaus | | `regularPrice` | ✅ Yes | float | Dot separator | Competitor regular (non-discounted) price | price, list\_price, base\_price | 125 | | `promoPrice` | ⬜ No | float | Dot separator | Competitor promotional price (if applicable) | sale\_price, discounted\_price, promo\_price | 119.99 | | `currency` | ⬜ No | string | ISO 4217 | Currency code | curr, currency\_code | EUR | | `url` | ⬜ No | string | URL | Source product page | link, product\_url, source\_url | [https://bauhaus.fi/product123](https://bauhaus.fi/product123) | | `barcode` | ⬜ No | string | Text | EAN / UPC barcode | ean, ean13, upc, gtin | 5901234123457 | | `sku` | ⬜ No | string | Text | Competitor SKU | competitor\_sku, seller\_sku | SKU-1001 | | `status` | ⬜ No | string | Text | Lifecycle status (active / discontinued) | availability\_status, product\_status | active | | `stock` | ⬜ No | float | Numeric | On-hand inventory quantity (if available) | inventory, stock\_qty, quantity\_available | 125 | You may add additional attributes as separate columns. ## Product matching Retailgrid matches each competitor price observation to a product in your Products dataset using this priority order: 1. `itemId` — used first when present. 2. `barcode` (EAN / UPC) — used as fallback when `itemId` is missing. 3. `sku` — used as a final fallback when neither `itemId` nor `barcode` matches. Provide all three when possible. Provide `itemId` at minimum — it gives the highest match accuracy and the fewest unmatched rows. Matching rules are configurable during dataset setup. Custom product codes and composite keys are also supported. Formatting tips: * Ensure consistent formatting between datasets. * Avoid leading/trailing spaces. * Keep barcode values numeric without formatting. ## Competitor scope By default every competitor here 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](/stores/assign-competitors). Scoping drives which competitors per-store pricing rules and competitor-gap metrics use. ## Price interpretation logic Retailgrid applies the following logic: * If `promoPrice` exists → it is treated as the active selling price * If `promoPrice` is empty → `regularPrice` is used * If both exist → system calculates: * Discount % * Promo depth * Effective price * Price gap vs your price * Price index ## Currency handling * If all data is in one currency → no conversion required * If multiple currencies are present → FX conversion rules must be configured Recommendation:\ Upload competitor prices in the same currency as your product prices. ## Time-series behavior Competitor Prices are stored historically. This enables: * Price change tracking * Promo frequency analysis * Volatility scoring * Price war detection * EDLP vs Hi-Lo classification * AI elasticity modeling Each upload should include a valid `datetime` value. Do not overwrite history. ## Data format requirements Supported formats: * CSV (recommended) * XLSX Encoding: * UTF-8 * Dot (.) as decimal separator Rules: * One row = one product × one competitor × one timestamp * Do not combine multiple competitors in one row * Do not store historical prices in multiple columns Correct example: | itemId | datetime | competitorName | regularPrice | | :----- | :------- | :------------- | :----------- | ## Validation rules Upload will fail if: * Required fields are missing * `datetime` format is invalid * `regularPrice` is empty or non-numeric * Matching with Products dataset fails * Duplicate identical rows are detected ## Example row | itemId | datetime | competitorName | regularPrice | promoPrice | currency | url | barcode | sku | status | stock | | :------- | :------------------ | :------------- | :----------- | :--------- | :------- | :------------------------------------------------------------- | :------------ | :------- | :----- | :---- | | SKU-1001 | 2026-02-22 14:35:00 | Bauhaus | 125 | 119.99 | EUR | [https://bauhaus.fi/product123](https://bauhaus.fi/product123) | 5901234123457 | SKU-1001 | active | 125 |