Skip to main content
A well-structured BOM (Bill of Materials) file makes imports faster and more accurate. This guide covers the columns Variable expects and best practices for formatting your data.

​
Required columns

Every BOM import must include these columns:
ColumnDescriptionExample
productSkuUnique identifier for the product or partBIKE-001
quantityAmount of this input used per unit of the parent product2.5
If your file is missing either productSku or quantity, the import will fail during validation.
These columns improve the quality of your imported data:
ColumnDescriptionExample
productNameHuman-readable name for the productFront Wheel Assembly
unitCodeUnit of measure for the quantitykg, m2, pcs
bomLevelHierarchy level (0 = root product)0, 1, 2
bomParentIdSKU of the parent product (alternative to bomLevel)BIKE-001
weightAmountWeight of the item3.2
weightUnitCodeUnit for weightkg, g, lbs
supplierNameName of the supplierRimSupply
supplierIdYour internal supplier identifierSUP-001
supplierPartIdSupplier’s part numberRS-RIM-42
materialIdIdentifier for the underlying materialALU-6061
materialNameName of the underlying materialAluminum Alloy 6061

​
Example CSV templates

​
Minimal template

The simplest valid BOM with only required columns: 
productSku,quantity
FRAME-001,1
WHEEL-ASSY-001,2
TIRE-001,2
BRAKE-PAD-001,4

​
Standard template

A typical BOM with common columns: 
bomLevel,productSku,productName,quantity,unitCode,weightAmount,weightUnitCode,supplierName
0,BIKE-001,Mountain Bike,1,pcs,,,
1,FRAME-001,Aluminum Frame,1,pcs,2.3,kg,FrameCorp
1,WHEEL-ASSY-001,Front Wheel Assembly,1,pcs,0.8,kg,WheelWorks
1,WHEEL-ASSY-002,Rear Wheel Assembly,1,pcs,0.9,kg,WheelWorks
2,TIRE-001,Mountain Tire,2,pcs,0.4,kg,TireCo
2,RIM-001,Alloy Rim,2,pcs,0.3,kg,RimSupply

​
Hierarchical template with materials

A detailed BOM with supplier parts and materials: 
bomLevel,productSku,productName,quantity,unitCode,supplierName,supplierPartId,materialId,materialName,weightAmount,weightUnitCode
0,CHAIR-001,Office Chair,1,pcs,,,,,,
1,SEAT-001,Seat Assembly,1,pcs,SeatCo,SC-SEAT-42,FOAM-01,Polyurethane Foam,1.2,kg
1,BASE-001,Chair Base,1,pcs,MetalWorks,MW-BASE-7,STEEL-01,Carbon Steel,3.5,kg
2,WHEEL-001,Caster Wheel,5,pcs,WheelCo,WC-CAST-1,NYLON-01,Nylon 6,0.08,kg
1,ARM-001,Armrest,2,pcs,PlasticPro,PP-ARM-3,ABS-01,ABS Plastic,0.25,kg

​
Hierarchy options

Variable supports two ways to define BOM hierarchy:

​
Option 1: bomLevel

Use integer levels where 0 is the root product: 
bomLevel,productSku,quantity
0,TABLE-001,1
1,TABLETOP-001,1
1,LEG-FRAME-001,1
2,LEG-001,4
The system processes rows in order. Level 2 items become children of the most recent level 1 item - here, the four legs attach to the leg frame: 
TABLE-001
├─ TABLETOP-001 (qty 1)
└─ LEG-FRAME-001 (qty 1)
   └─ LEG-001 (qty 4)

​
Option 2: bomParentId

Explicitly reference the parent product’s SKU: 
productSku,bomParentId,quantity
TABLE-001,,1
TABLETOP-001,TABLE-001,1
LEG-FRAME-001,TABLE-001,1
LEG-001,LEG-FRAME-001,4
This produces the same hierarchy as the bomLevel example above: 
TABLE-001
├─ TABLETOP-001 (qty 1)
└─ LEG-FRAME-001 (qty 1)
   └─ LEG-001 (qty 4)
Use bomParentId when your BOM rows are not in hierarchical order or when you need explicit parent-child relationships.

​
Mixed units

You can enter an input quantity in any unit the source product supports, even when it differs from that product’s declared unit. For example, if a board is declared in m2 but your BOM lists it as 2.4 m, import the row as-is — set unitCode to the unit you have. Variable converts the value to the declared unit for impact calculations and keeps your entered value in the API. No extra columns are needed. Conversion uses the length, volume, area, or weight factors set on the source product.
If a row’s unit doesn’t match the product’s declared dimension and the source product has no matching conversion factor, that row is skipped and will not appear in your imported model. Add the relevant conversion factor to the product, or use the declared unit, to import the row.

​
Best practices

​
Use consistent SKUs

SKUs are used to match and deduplicate products. Use the same SKU format throughout your file and across imports.

​
Decimal separator

Variable auto-detects decimal separators. If you use European format (comma as decimal separator), you can select this during the import mapping step. 
# US format
quantity
3.5

# European format  
quantity
"3,5"

​
Date format

Variable accepts several date formats (Day / Month / Year, Month / Day / Year, Year / Month / Day, Year Month, Month Year, ISO 8601) - you’ll select the one that matches your file on the column-mapping screen. Within a single date column, every row must use the same format. ISO 8601 (YYYY-MM-DD) is a good default if you control the export: 
startDate
2024-01-15
See Date format for the full list of accepted variations within each option.

​
Standard unit codes

Use standard unit abbreviations that Variable recognizes. Codes are case-insensitive - kg, KG, and Kg all resolve to the same unit, and Variable stores the canonical form shown:
CategoryUnits
Massmg, g, kg, t, kt, mt, Gt, oz, lbs
Lengthmm, cm, dm, m, km, in., ft, yd, mi., NM
Areamm2, cm2, m2, km2, ha, in2, ft2, yd2, acre
Volumecm3, l, hl, m3, c., pt, qt, gal
EnergyJ, Wh, kWh, MWh, MJ, GJ
PowerW, kW, MW
Times, min, h, d, wk, mo, y
Discreteitem, pcs, shts
Freighttkm, tm
Passengerpkm, pm
During import, you can map non-standard unit values (e.g., “kilograms”, “kilogrammes”, “lb”) to Variable’s standard codes.

​
Clean your data before import

  • Remove empty rows at the end of the file
  • Ensure column headers are in the first row
  • Remove any summary or total rows
  • Check for special characters that might affect parsing

​
Next steps