> ## 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. # Sales > Upload transaction-level sales data to power analytics, elasticity modeling, and price optimization in Retailgrid. ## Transaction history data specification For sales analytics, elasticity modeling, and retail intelligence. Check the sample [**sample\_transactions**](https://drive.google.com/file/d/1Q6ew53Np9Bj8WG_NzVOBNxYL9n1UCqM9/view?usp=sharing). You can also load transaction data programmatically via the public **Retailgrid REST API** instead of CSV upload. The same field constraints below apply to API payloads. ## 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: ```text theme={null} YYYY-MM-DD HH:MM:SS ``` Example: ```text theme={null} 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: ```text theme={null} 129.99 ``` Incorrect: ```text theme={null} 129,99 1 299.99 $129.99 ``` ### 5.3 Discount format Must be a rate: ```text theme={null} 0.15 = 15% 0.00 = no discount ``` Not: ```text theme={null} 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 ```text theme={null} 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: ```text theme={null} transaction_id store_id item_id transaction_timestamp quantity selling_price ``` Returns must still follow negative quantity logic.