Preparing your BOM file

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:

Column	Description	Example
`productSku`	Unique identifier for the product or part	`BIKE-001`
`quantity`	Amount of this input used per unit of the parent product	`2.5`

If your file is missing either productSku or quantity, the import will fail during validation.

Recommended columns

These columns improve the quality of your imported data:

Column	Description	Example
`productName`	Human-readable name for the product	`Front Wheel Assembly`
`unitCode`	Unit of measure for the quantity	`kg`, `m2`, `pcs`
`bomLevel`	Hierarchy level (0 = root product)	`0`, `1`, `2`
`bomParentId`	SKU of the parent product (alternative to bomLevel)	`BIKE-001`
`weightAmount`	Weight of the item	`3.2`
`weightUnitCode`	Unit for weight	`kg`, `g`, `lbs`
`supplierName`	Name of the supplier	`RimSupply`
`supplierId`	Your internal supplier identifier	`SUP-001`
`supplierPartId`	Supplier’s part number	`RS-RIM-42`
`materialId`	Identifier for the underlying material	`ALU-6061`
`materialName`	Name of the underlying material	`Aluminum 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:

Category	Units
Mass	`mg`, `g`, `kg`, `t`, `kt`, `mt`, `Gt`, `oz`, `lbs`
Length	`mm`, `cm`, `dm`, `m`, `km`, `in.`, `ft`, `yd`, `mi.`, `NM`
Area	`mm2`, `cm2`, `m2`, `km2`, `ha`, `in2`, `ft2`, `yd2`, `acre`
Volume	`cm3`, `l`, `hl`, `m3`, `c.`, `pt`, `qt`, `gal`
Energy	`J`, `Wh`, `kWh`, `MWh`, `MJ`, `GJ`
Power	`W`, `kW`, `MW`
Time	`s`, `min`, `h`, `d`, `wk`, `mo`, `y`
Discrete	`item`, `pcs`, `shts`
Freight	`tkm`, `tm`
Passenger	`pkm`, `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

Upload and map columns - Start the import process
What happens after upload - Understand the 3-level BOM structure

Getting started

Help articles

Data import

Concepts

Security

Preparing your BOM file

Required columns

Recommended columns

Example CSV templates

Minimal template

Standard template

Hierarchical template with materials

Hierarchy options

Option 1: bomLevel

Option 2: bomParentId

Mixed units

Best practices

Use consistent SKUs

Decimal separator

Date format

Standard unit codes

Clean your data before import

Next steps

​Required columns

​Recommended columns

​Example CSV templates

​Minimal template

​Standard template

​Hierarchical template with materials

​Hierarchy options

​Option 1: bomLevel

​Option 2: bomParentId

​Mixed units

​Best practices

​Use consistent SKUs

​Decimal separator

​Date format

​Standard unit codes

​Clean your data before import

​Next steps

Required columns

Recommended columns

Example CSV templates

Minimal template

Standard template

Hierarchical template with materials

Hierarchy options

Option 1: bomLevel

Option 2: bomParentId

Mixed units

Best practices

Use consistent SKUs

Decimal separator

Date format

Standard unit codes

Clean your data before import

Next steps