Products

Product master data specification. Check the sample Sample_products.csv.

You can also load product data programmatically via the public Retailgrid REST API. API payloads use slightly different field names and required fields — see Loading via the API below.

1. Objective

The Product Master dataset supports:

Linking transactions to products
Margin calculation (via unit_cost)
Category-level analytics
Brand & assortment analysis
Elasticity modeling
Price corridor analysis

Each row represents:

One sellable item (SKU level)

2. Referential integrity (critical)

The following fields must match exactly with Transaction history:

Product File	Transaction File
item_id	item_id

If item_id does not match, transactions cannot be linked.

3. Product master — unified specification

Field Name	Required	Type	Format	Description	Example	Alternative Names
item_id	✅ Yes	string	Unique	Unique SKU-level identifier. Links transactions, store, and competitor data to this item.	SKU-1001	item id, sku id, article id
product_id	⬜ Optional	string	Text	Product-level code grouping related items / variants under one product.	P001	product code, style code, product group code
product_name	✅ Yes	string	Text	Full product name	Cordless Drill 18V Blue	SKU Name, Product Title, Product Variant Name
price	✅ Yes	decimal(12,2)	Dot separator	The actual selling price. Current Price	129.99	Current Price, Actual Price
unit_cost	✅ Yes	decimal(12,2)	2 decimals	Cost per unit at time of sale	80.00	Cost Price, Purchase Cost, Purchase Price
sku	⬜ Optional	string	Text	Stock Keeping Unit	SKU-1001	SKU Code
barcode	⬜ Optional	string	EAN/UPC	Barcode value	5901234123457	EAN, UPC, GTIN
brand	⬜ Optional	string	Text	Brand name	Bosch	Brand Name, Label, Trademark
manufacturer	⬜ Optional	string	Text	Manufacturer name	Bosch	Producer, Vendor, Supplier
product_group	⬜ Optional	string	Text	Logical product group	Drill-18V	Pricing group, Assortment Group, Product family
status	⬜ Optional	string	active / inactive	Product lifecycle status	active	Lifecycle Status, Availability status
stock	⬜ Optional	integer	≥ 0	Current stock level	125	Inventory level, Stock_on_hand, Available quantity
product_type	⬜ Optional	string	Text	Product classification	Power Tools	Item type
category1	⬜ Optional	string	Text	Top-level category	Tools	Department
category2	⬜ Optional	string	Text	Subcategory	Power Tools
category3	⬜ Optional	string	Text	Subcategory level 3	Drills
category4	⬜ Optional	string	Text	Subcategory level 4	Cordless
category5	⬜ Optional	string	Text	Subcategory level 5	18V
image_url	⬜ Optional	string	URL	Product image URL	https://…
product_url	⬜ Optional	string	URL	Product page URL	https://…
rrp	⬜ Optional	decimal(12,2)	2 decimals	Recommended retail price	129.99	MSRP, List Price, Recommended Price
regular_price	⬜ Optional	decimal(12,2)	Dot separator	The standard, non-discounted price of the product	139.99	Base price, Normal price, Standard price
product_created_date	⬜ Optional	date	YYYY-MM-DD	Product creation date	2024-01-15	Product Launch date
price_effective_date	⬜ Optional	date	YYYY-MM-DD	Price effective date	2026-02-01	Price start date, Price valid from
cost_effective_date	⬜ Optional	date	YYYY-MM-DD	Cost effective date	2026-01-15	Cost start date, Cost valid from
size	⬜ Optional	decimal or string	Numeric or text	Size value	12	Variant size
uom	⬜ Optional	string	Unit code	Unit of measure	pcs	Unit, Measurement unit
tax_rate	⬜ Optional	decimal(5,4)	0–1	VAT rate (0.20 = 20%)	0.20	Tax rate, Vat percentage
currency	⬜ Optional	string(3)	ISO code	Currency	EUR	Currency code, Iso currency

4. Alignment with transaction schema

4.1 Keys Mandatory alignment:

transaction.item_id = product.item_id

4.2 Currency Consistency If transactions include currency, product file must include currency. 4.3 VAT Consistency If VAT is included in transaction prices:

Provide vat_rate in product file
Clarify whether unit_price in transactions is gross or net

5. Data format requirements

5.1 Dates

YYYY-MM-DD

Example:

2026-02-18

5.2 Numeric Fields

Decimal separator: .
No currency symbols
No thousand separators

6. Custom attributes (extensibility model)

You can add additional attributes as extra columns. Examples:

material
color
season
gender
supplier_id
competitor_reference
margin_group
elasticity_cluster

Rules for custom attributes

Must not overwrite required column names
Must follow consistent naming
Must contain a single value per row
No nested JSON inside Excel cells
CSV / XLSX upload only — the JSON API rejects unknown fields (see Loading via the API)

Example:

item_id	product_name	material	color
SKU-1001	Tent 3P	Polyester	Green

7. File format

Accepted:

CSV (UTF-8 preferred)
XLSX

One row per SKU. No pivot tables.
No formulas.
Raw data only.

8. Minimal product dataset (absolute minimum)

If system limitations exist:

item_id
product_name
price
unit_cost

However, for pricing analytics it is strongly recommended to include:

item_id
product_name
price
unit_cost
brand
category 1–3
rrp
regular_price
vat_rate
currency

9. SQL schema example

CREATE TABLE product_master (
    item_id VARCHAR(64) PRIMARY KEY,
    product_id VARCHAR(64),
    product_name VARCHAR(255) NOT NULL,
    sku VARCHAR(64),
    barcode VARCHAR(64),
    brand VARCHAR(128),
    manufacturer VARCHAR(128),
    product_group VARCHAR(128),
    status VARCHAR(32),
    stock INT,
    product_type VARCHAR(128),
    category1 VARCHAR(128),
    category2 VARCHAR(128),
    category3 VARCHAR(128),
    category4 VARCHAR(128),
    category5 VARCHAR(128),
    image_url TEXT,
    product_url TEXT,
    size VARCHAR(64),
    uom VARCHAR(32),
    product_created_date DATE,
    rrp DECIMAL(12,2),
    regular_price DECIMAL(12,2),
    vat_rate DECIMAL(5,4),
    currency CHAR(3),
    price_effective_date DATE,
    cost_effective_date DATE
);

10. Loading via the API

The public REST API accepts the same data through POST /v1/products/bulk (JSON records) or POST /v1/imports/products (CSV import). JSON payloads use different names for some fields and a different required set. Required fields in API payloads: item_id, sku, sku_name, current_price, unit_cost.

CSV column	API field	Notes
price	`current_price`	Required. There is no `price` field in the API.
product_name	`sku_name`	Required. The API also has an optional `product_name` for a product-level name.
sku	`sku`	Required in API payloads (optional in CSV).
stock	`stock_on_hand`
category1 – category5	`category_1` – `category_5`	Underscored in the API.
—	`color`	API-only optional field.

All other fields keep the same names as the CSV columns above.

Custom attributes as extra columns are supported for CSV / XLSX upload only. The JSON API rejects unknown fields — payloads containing fields outside the schema fail validation.

Data specs

Glossary

1. Objective

2. Referential integrity (critical)

3. Product master — unified specification

4. Alignment with transaction schema

5. Data format requirements

6. Custom attributes (extensibility model)

7. File format

8. Minimal product dataset (absolute minimum)

9. SQL schema example

10. Loading via the API

​1. Objective

​2. Referential integrity (critical)

​3. Product master — unified specification

​4. Alignment with transaction schema

​5. Data format requirements

​6. Custom attributes (extensibility model)

​7. File format

​8. Minimal product dataset (absolute minimum)

​9. SQL schema example

​10. Loading via the API

1. Objective

2. Referential integrity (critical)

3. Product master — unified specification

4. Alignment with transaction schema

5. Data format requirements

6. Custom attributes (extensibility model)

7. File format

8. Minimal product dataset (absolute minimum)

9. SQL schema example

10. Loading via the API