Skip to main content
The Product Store-Level dataset allows you to provide product information at store, market, or sales-channel level. This dataset is required if:
  • You operate multiple physical stores
  • You sell across different markets (countries)
  • You manage multiple sales channels (Online / Marketplace / Wholesale)
  • Prices, costs, tax rates, or stock differ per store
Each row represents:
One product in one specific store (or market / channel)

​
When to use store-level data

Use this dataset if:
  • Prices vary by store
  • Unit cost differs by warehouse or region
  • Stock is managed per store
  • Tax rates vary by country
  • Some products are active in certain stores only
If all stores share identical product data, you may use only the Products dataset.

​
Data schema

You may include additional attributes as separate columns (CSV / XLSX upload only — the JSON API rejects unknown fields).

​
Matching logic

  • item_id must match the Products dataset
  • store_id must match a store defined in Stores management
Matching can be configured using:
  • Exact match
  • Composite keys (item_id + store_id)
  • Custom identifiers

​
Load by CSV or by API

Store-level data can be loaded two ways:
  • CSV / XLSX upload — via the Datasets page, following the format requirements below.
  • Public API — push product-store records programmatically (POST /v1/product_store/bulk for JSON records, POST /v1/imports/product_store for CSV import), one record per product-store combination. The upsert key is (item_id, store_id); store_id is required on product-store payloads — product-level records are managed via the Products endpoints instead. See the API changelog for details.
API payloads differ from the CSV schema in a few places:
  • Required fields in API payloads: item_id, sku, store_id, current_price. Note that sku is required in API payloads even though it is not a CSV column, and the CSV price column is named current_price in the API.
  • stock is named stock_on_hand in the API.
  • API-only optional fields: store_name, country_code.
Additional 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.

​
Price interpretation logic

Retailgrid applies the following logic:
  • If regular_price exists and price < regular_price → product is considered on promotion
  • Margin is calculated as:
  • If tax_rate is provided, gross/net calculations are supported

​
Store / market / channel flexibility

store_id can represent:
  • Physical store
  • Country
  • Warehouse
  • Online shop
  • Marketplace (Amazon, Zalando, etc.)
  • B2B vs B2C channel
Retailgrid treats this as a location dimension.

​
Currency handling

If multiple stores use different currencies:
  • Currency must be provided
  • FX conversion rules must be configured
Recommended:
Keep price and cost in the same currency per row.

​
Time handling

This dataset is typically a current snapshot, not time-series. If price_effective_date is provided:
  • Future price simulations become possible
  • Scheduled price changes can be modeled

​
Data format requirements

Supported formats:
  • CSV (recommended)
  • XLSX
Encoding:
  • UTF-8
  • Dot (.) as decimal separator
Rules:
  • One row = one product × one store
  • Do not duplicate identical product-store combinations
  • Use consistent store_id formatting

​
Validation rules

Upload will fail if:
  • item_id is missing
  • store_id is missing
  • price is missing or non-numeric
  • Matching with Products dataset fails

​
Example row

​
How Retailgrid uses store-level data

This dataset powers:

​
Margin analysis per store

  • Store-level profitability
  • Margin leakage detection

​
Local price optimization

  • Dynamic pricing by store
  • Market-based pricing

​
Assortment strategy

  • Store-specific availability
  • Stock-based pricing decisions

​
Promotion strategy

  • Local promo activation
  • Regional discount benchmarking

​
Advanced recommendations

For best results:
  • Always provide unit_cost for margin optimization
  • Keep store identifiers consistent
  • Provide stock for AI-driven replenishment signals
  • Include tax_rate for cross-country operations