Sales

Transaction history data specification

For sales analytics, elasticity modeling, and retail intelligence. Check the sample sample_transactions.

You can also load transaction 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

Use this dataset for:

Sales performance analytics
Price elasticity modeling
Demand curve estimation
Price optimization
Promotion impact analysis
Store performance benchmarking

You must provide data at transaction line level.

2. Data granularity requirement

Each row must represent:

One product in one transaction

Correct:

transaction_id	item_id	quantity
TRX_001	SKU-1001	2
TRX_001	SKU-1002	1

Incorrect:

Daily aggregated totals
Store-level summaries
Pivoted exports

3. Transaction history — unified data specification

Field Name	Required	Type	Format	Description	Example	Alternative Names
transaction_id	✅ Yes	string	Unique	Unique identifier of the transaction. Must be stable and not reused.	TRX_000123	order id, receipt id, invoice id, ticket id
store_id	✅ Yes	string	Text	Identifier of store or sales location.	S001	location id, branch id, outlet id
item_id	✅ Yes	string	Text	Unique SKU-level identifier. Must match `item_id` in the Product Master file.	SKU-1001	product id, sku id, article id
transaction_timestamp	✅ Yes	datetime	YYYY-MM-DD HH:MM:SS	Date and time of transaction in ISO 8601 format. Preferably UTC.	2026-02-18 14:22:05	sale timestamp, order datetime, event time
quantity	✅ Yes	decimal(12,2) or integer	Positive for sales, negative for returns	Units sold (positive) or returned (negative). Must not be zero.	3 / -1	units, qty, quantity sold, units sold
selling_price	✅ Yes	decimal(12,2)	Dot separator	Actual price paid per unit in that transaction (after discount).	129.99	unit price, final price, transaction price
regular_price	⬜ Optional	decimal(12,2)	Dot separator	Standard non-discounted product price at time of sale.	139.99	base price, list price, shelf price
unit_cost	⬜ Optional	decimal(12,2)	2 decimals	Cost per unit at time of transaction (for margin calculation).	80.00	cost price, cogs unit, purchase cost
discount_rate	⬜ Optional	decimal(5,4)	0–1	Discount applied as a rate (0.15 = 15%).	0.15	discount pct, promo rate
sales_value	⬜ Optional	decimal(12,2)	Dot separator	Total transaction value per row. If provided, must equal `quantity × selling_price`.	389.97	revenue, line revenue, gross sales
gross_profit	⬜ Optional	decimal(12,2)	Dot separator	Gross profit per row. If provided, must equal `(selling_price - unit_cost) × quantity`.	149.97	margin value, contribution margin
stock_after_sale	⬜ Optional	integer	≥ 0	Inventory level after transaction occurred.	37	stock on_hand, inventory after
currency	⬜ Optional*	string(3)	ISO 4217	Currency code used for price fields. Required if multi-currency.	EUR	currency code
tax_rate	⬜ Optional	decimal(5,4)	0–1	VAT/tax rate applied (0.20 = 20%).	0.20	vat rate, tax percentage
transaction_type	⬜ Optional	string	sale / return	Type of transaction. If return, quantity must be negative.	sale	order type, operation type

4. Return handling policy (mandatory if returns exist)

Returns must be provided as separate transaction rows.

4.1 Format for returns

Field	Value
transaction_type	return
quantity	Negative value
selling_price	Positive
transaction_timestamp	Actual return time
item_id	Same as original sale

4.2 Example

Original Sale

transaction_id	item_id	quantity	selling_price	transaction_type
TRX_1001	SKU-1001	2	129.99	sale

Return

transaction_id	item_id	quantity	selling_price	transaction_type
TRX_1055	SKU-1001	-1	129.99	return

4.3 Important rules

Do NOT delete original sale rows
Do NOT aggregate net values before export
Do NOT use positive quantity for returns
unit_price must remain positive
Returns must reflect the actual return date

5. Data format requirements (strict)

5.1 Timestamp

Must follow ISO 8601:

YYYY-MM-DD HH:MM:SS

Example:

2026-02-18 14:22:05

Timezone:

Preferably UTC
Or timezone must be clearly specified

5.2 Numeric fields

Decimal separator: .
No thousand separators
No currency symbols
No localized formats

Correct:

129.99

Incorrect:

129,99
1 299.99
$129.99

5.3 Discount format

Must be a rate:

0.15  = 15%
0.00  = no discount

Not:

15%
-20

6. File format

Accepted:

CSV (UTF-8 encoding) — preferred
XLSX

No pivot tables
No formulas
Raw data only

7. Historical data requirements

Minimum:

6–12 months of history
Preferably 24 months

Recommended minimum volume:

10,000+ transaction rows per store

8. Data validation rules

quantity ≠ 0
quantity > 0 for sales
quantity < 0 for returns
unit_price ≥ 0
discount_rate between 0 and 1
transaction_timestamp not null
item_id must exist in product master file

9. SQL schema example

CREATE TABLE transaction_history (
    transaction_id VARCHAR(64) NOT NULL,
    store_id VARCHAR(32) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    transaction_timestamp TIMESTAMP NOT NULL,
    quantity INT NOT NULL,
    unit_price DECIMAL(12,2) NOT NULL,
    unit_cost DECIMAL(12,2),
    discount_rate DECIMAL(5,4),
    stock_after_sale INT,
    currency CHAR(3),
    transaction_type VARCHAR(16),
    sales_channel VARCHAR(16)
);

10. Minimal dataset (if system limitations exist)

If the system cannot provide full structure, minimum required:

transaction_id
store_id
item_id
transaction_timestamp
quantity
selling_price

Returns must still follow negative quantity logic.

11. Loading via the API

The public REST API accepts the same data through POST /v1/transactions/bulk (JSON records) or POST /v1/imports/transactions (CSV import), with two differences from the CSV schema:

There is no transaction_id field in the API. Use the optional external_transaction_id to carry your own transaction identifier — the API does not require one.
Required fields in API payloads: item_id, store_id, transaction_timestamp, quantity, selling_price.

API-only optional fields: sku, region, promo_type, zone_price.

The JSON API rejects unknown fields — payloads containing fields outside the schema fail validation.

Data specs

Glossary

Transaction history data specification

1. Objective

2. Data granularity requirement

3. Transaction history — unified data specification

4. Return handling policy (mandatory if returns exist)

4.1 Format for returns

4.2 Example

4.3 Important rules

5. Data format requirements (strict)

5.1 Timestamp

5.2 Numeric fields

5.3 Discount format

6. File format

7. Historical data requirements

8. Data validation rules

9. SQL schema example

10. Minimal dataset (if system limitations exist)

11. Loading via the API

​Transaction history data specification

​1. Objective

​2. Data granularity requirement

​3. Transaction history — unified data specification

​4. Return handling policy (mandatory if returns exist)

​4.1 Format for returns

​4.2 Example

​4.3 Important rules

​5. Data format requirements (strict)

​5.1 Timestamp

​5.2 Numeric fields

​5.3 Discount format

​6. File format

​7. Historical data requirements

​8. Data validation rules

​9. SQL schema example

​10. Minimal dataset (if system limitations exist)

​11. Loading via the API

Transaction history data specification

1. Objective

2. Data granularity requirement

3. Transaction history — unified data specification

4. Return handling policy (mandatory if returns exist)

4.1 Format for returns

4.2 Example

4.3 Important rules

5. Data format requirements (strict)

5.1 Timestamp

5.2 Numeric fields

5.3 Discount format

6. File format

7. Historical data requirements

8. Data validation rules

9. SQL schema example

10. Minimal dataset (if system limitations exist)

11. Loading via the API