Importing Assets to Shelf: CSV Guide

Shelf supports two CSV workflows for assets:

• Create new assets — this guide covers importing a CSV file to add new asset records to your inventory.
• Update existing assets — if you want to bulk-edit records already in Shelf, use the Bulk Updating Assets via CSV workflow instead.

Both read the header keys this guide describes (title, valuation, assetModel, quantity), so one Import-ready export serves either flow: upload it to create assets in another workspace, or upload it to the update flow to edit the assets it came from. The update flow additionally accepts the display labels a Standard export writes (Name, Value, Asset model, Quantity), and it matches rows on the id, ID, or Asset ID column.

Shelf imports assets from CSV (Comma-Separated Values) files. You can start from Shelf's template, or upload the CSV export of another tool or spreadsheet as it is: before anything is imported, Shelf proposes which Shelf field each of your columns goes to, and you check that in one table. The whole file is then validated before a single asset is created.

Quick Start

To begin importing assets:

1. Download the CSV template or barcode-enabled version from Shelf, or use the CSV export of the tool or spreadsheet you are moving from, unchanged (or, if you're moving assets in from another Shelf workspace, use an Import-ready export instead: Exporting Data from Shelf). An Import-ready file carries an id column, which this flow ignores, so the destination workspace issues its own ids. The same file can be re-uploaded to update the assets it came from instead of creating new ones
2. Add your asset information following the provided format. A file from another tool can keep its own column names
3. Save the file with UTF-8 encoding
4. Navigate to Assets then Import in your workspace
5. Choose the file and click Continue. Under Check how your columns map, each of your columns goes to the Shelf field on its right. Change any that look wrong, or set them to Skip. See Checking How Your Columns Map
6. Click Preview import. Shelf checks the whole file and shows a preview, without creating anything yet
7. Click Import N assets, type "I AGREE" and click Import. The import runs in the background: you can leave the page, and Shelf emails you when it finishes

Important: Do not upload a file from the old workspace backup download under Workspace settings → General, which was retired in October 2026. It produces corrupted data. To move assets from another Shelf workspace, use an Import-ready export.

Where to find the import. Assets → Import is always there for members whose role and plan allow importing. While a workspace has no assets yet, the empty Assets page also shows Import a spreadsheet next to Create your first asset, and the onboarding checklist on Home has an Import your assets item. Both are shown only to members whose role and plan allow importing, and the checklist item goes away once the workspace has its first asset, however it was added.

I'm moving my equipment list into Shelf (shelf.nu), an asset management app. I've attached my spreadsheet. Help me turn it into a CSV that Shelf's importer accepts.

Work in three steps. Use code (for example Python with the csv module) to read my file and to write the CSV. Don't type the CSV out by hand.

STEP 1: CHECK MY FILE, THEN ASK ME
Before writing anything, reply with:
1. How many items (rows) you found, and in which sheet. If the file has several sheets, ask which ones to use.
2. A table mapping each of my columns to a Shelf column from the list in step 2, or to "leave out".
3. Your questions. Always cover:
- Dates. For each date column, say which format you detected and why (e.g. "row 14 has 25/03/2024, so it's day/month"). If every value would make sense either way, because both numbers are 12 or lower, don't guess: show me three examples and ask. Also ask before converting spreadsheet date numbers (like 45123) or two-digit years.
- Money. Which currency the values in my file are in, and which currency my Shelf workspace uses. New workspaces start in US dollars (USD), so if I've only just set up Shelf, it's probably USD. Shelf shows every amount in the workspace currency and never converts. If my file uses one other currency, suggest I switch the workspace currency under Settings → General before importing and keep the numbers as they are. If the file mixes currencies, ask whether to convert (and at what rate) or leave those cells empty.
- Custom fields. Which columns should become custom fields, and the type you'd give each.
- Bulk stock. Which items are counted rather than tracked one by one (cables, batteries, consumables).
- Merges. Different spellings of the same name ("Studio A", "studio a", "Studio A "). List them and merge only the ones I approve.
- People. If the person column holds emails instead of names, ask me for names, or leave it empty.
- Missing names. List any rows with no item name and ask me what to call them, or whether to leave them out. Shelf needs a title on every row.
- Codes. Whether my items already carry Shelf QR codes from my workspace, and whether my workspace has the Alternative Barcodes add-on switched on.
Then stop and wait for my answers.

STEP 2: WRITE THE CSV
Output:
- UTF-8, comma-delimited. First row is the header row. One item per row.
- At most 10,000 rows and 10 MB per file. Split larger lists into numbered files.
- Wrap any cell that contains a comma, a double quote or a line break in double quotes, and double any quote inside it ("").

Columns. Use exactly these headers. Shelf ignores capitals, but a column it cannot match is skipped and not imported:
- title (required): the item's name.
- description: free text.
- category, kit, assetModel: plain names. Shelf creates any that don't exist yet.
- location: one place name per item. If my data splits building and room into separate columns, ask me which to use.
- tags: several labels in one cell, separated by commas, with the whole cell in double quotes, e.g. "audio,portable".
- custodian: the person who has the item, by full name. Never an email address.
- bookable: write no only for items that must never be booked. Otherwise leave it blank.
- imageUrl: a public http(s) link to a photo, only if my data has one.
- valuation: a plain number with a dot for decimals. No currency symbol, no thousands separator, e.g. 1200.50.
- type, quantity, consumptionType, minQuantity, unitOfMeasure: for bulk stock only. Set type to QUANTITY_TRACKED, quantity to the count (more than 0), and consumptionType to ONE_WAY if it gets used up or TWO_WAY if it comes back. minQuantity (low-stock alert) and unitOfMeasure are optional. Leave all five blank for ordinary one-of-a-kind items, and never give a QUANTITY_TRACKED row an assetModel.
- If you fill both kit and custodian, every item in the same kit must have the same custodian.

Custom fields, for anything that doesn't fit a column above (serial number, purchase date, warranty, supplier):
- Header: "cf:Field Name,type:TYPE", inside double quotes. TYPE is one of: text, multiline text, option, boolean, date, amount, number.
- date: YYYY-MM-DD only. boolean: yes or no only. amount and number: plain numbers with a dot for decimals.
- Keep the ID from my old tool in "cf:Old ID,type:text", not in an id column.

Codes, only when I confirmed them in step 1:
- qrId: only if my items already carry Shelf QR codes from my workspace that aren't linked to another item yet. Each code once, never shared between items.
- barcode_Code128, barcode_Code39, barcode_DataMatrix, barcode_ExternalQR, barcode_EAN13: only if the Alternative Barcodes add-on is on. Several codes of one type go in one cell, separated by commas, with the cell in double quotes. Code128: 4-40 characters. Code39: 4-43 characters, A-Z and 0-9 only. DataMatrix: 4-100 characters. ExternalQR: up to 2048 characters. EAN13: exactly 13 digits with a valid check digit.
- Otherwise leave these columns out entirely. Shelf creates a new QR code for every item.

Rules:
- Don't invent or guess data. An empty cell is better than a wrong one.
- Keep every item. If you're unsure about a row, keep it and flag it.

STEP 3: CHECK THE FILE BEFORE YOU GIVE IT TO ME
Open the CSV you wrote with a CSV parser and report the result of each check:
- The number of items in my file equals the number of rows in the CSV, or you explain every difference.
- Every header is one of: title, description, category, kit, assetModel, location, tags, custodian, bookable, imageUrl, valuation, type, quantity, consumptionType, minQuantity, unitOfMeasure, a "cf:Name,type:TYPE" header with a type from the list, or (only if I confirmed them in step 1) qrId and the barcode_ headers listed above.
- No row has an empty title, and no qrId or barcode value appears twice.
- Every date is YYYY-MM-DD, every boolean is yes or no, and every valuation, amount and number cell is a plain number.
- Every barcode value fits the length and character rules for its type.
- Every QUANTITY_TRACKED row has a quantity above 0 and a consumptionType, and no assetModel.
- Every item in the same kit has the same custodian.
- No file has more than 10,000 rows or is larger than 10 MB.
Then give me the file(s), the final column mapping, and a list of anything you weren't sure about, with row numbers.

I'll upload the file in Shelf under Assets → Import. Full guide: https://www.shelf.nu/knowledge-base/importing-assets-to-shelf-csv-guide

Checking How Your Columns Map

After you choose a file and click Continue, Shelf reads its headings and a few sample values and shows Check how your columns map: one row per column of your file, with up to three sample values, the Shelf field it will become, and a dot for how sure the match is. A green dot means a sure match and an amber dot a guess to check. A column Shelf could not place is set to Skip with an amber dot, and any row you change yourself turns green. Nothing has been imported at this point.

How Shelf proposes a field, in this order:

1. Shelf's own headings, such as title or cf:Serial number,type:text. A file made from the template, or an Import-ready export, shows the message Your file already matches Shelf's format. Every row of the template is green. The id column of an Import-ready export is always set to Skip, with an amber dot, since the new workspace issues its own ids.
2. The same name, ignoring capitals and punctuation, such as Title or Unit of measure.
3. A custom field your workspace already has with the same name. It keeps the type it already has.
4. Common headings from other tools and hand-made sheets: more than 150 of them, from Sortly, Asset Panda, Snipe-IT and spreadsheets, including common German, Spanish and French ones. For example Item Name becomes the name, Qty the quantity, Primary Folder the location, Min Level the low-stock alert, Serial No. a new Serial number custom field and Purchased a new Purchase date date field. Barcode headings are only matched when the Alternative Barcodes add-on is on.
5. Skip, for everything else. Columns that hold another system's ids, such as Sortly ID, are skipped unless you choose otherwise.

Changing a row. Every row has a dropdown with all Shelf fields, Custom field... and Skip. Custom field... opens two inputs under the dropdown for the field's name and type, so a column such as a legacy ID can come across as a text custom field.

What the review checks before you continue:

• Two columns aimed at the same field. Both rows turn red with "Another column already goes to this field. Pick a different one or Skip.", and Preview import stays disabled until you fix it.
• Values the import will refuse or leave out. Short notes under the table point out a date column written as, for example, DD/MM/YYYY: dates must be YYYY-MM-DD, and the import stops on any other date. They also point out values such as true or 1 in a yes/no field: the import does not stop for those, but the asset is created with that field empty. Fix both in the file before you import.
• How many rows come in. A line under the table says how many assets will be imported, for example "Up to 3 assets will be imported. Rows with values only in skipped columns are left out." It names any custom fields the file will create. The new categories, locations, tags, kits and custodians are listed in the preview that follows.

How should these rows be tracked? When a column goes to Quantity and no column goes to the type (a Sortly export, for example), Shelf asks how the rows come in:

• Individual assets: one asset per row. Every quantity must be 1.
• Stock, returned after use: each row is tracked by quantity and checked back in after use.
• Stock, used up: each row is tracked by quantity and consumed when checked out.

A stock answer makes every row quantity-tracked with that consumption type, unless a column of your file already gives each row its own. When every sampled quantity is 1, Individual assets is picked for you; otherwise Preview import waits for an answer.

The mapping only renames columns. It never changes a value. Every rule in the rest of this guide still applies to your data, such as dates as YYYY-MM-DD, yes/no values, barcodes and QR codes, and the whole file is still checked before anything is created. Click Back to return to the upload step with your file kept, or Preview import to go on to the preview. While another import is running in the workspace, Preview import waits.

File Requirements

Basic Format Rules

• Delimiter: Comma (,) or semicolon (;). Shelf auto-detects whichever character appears more often between cells. Commas and semicolons inside a double-quoted cell, such as a long description, are not counted, so they cannot tip the choice. Pick one delimiter and stick to it.
• Quoting: Wrap any value containing the delimiter, a double quote, or a newline in double quotes ("…"). Escape an internal " by doubling it (""). This matters for tags and multi-value barcode_* cells in a comma-delimited file, and for cf:…,type:… custom-field headers in a comma-delimited file (see Custom Fields below).
• Encoding: UTF-8 recommended. Other encodings are auto-detected and converted, and a UTF-8 BOM is accepted.
• Header row: First row must contain column headers. They do not have to be Shelf's: after you click Continue, Shelf proposes a Shelf field for each one (see Checking How Your Columns Map). A column it cannot place is set to Skip and left out of the import, unless you pick a field for it.
• Columns: At most 200 columns, each heading at most 1,000 characters. A file over either limit is refused before the mapping step, with a message saying which.
• File format: Only .csv files accepted.
• Size: Up to 10,000 assets per file, and at most 10 MB. A file with more rows is refused before anything is imported, with a message giving its row count. Split it and import the parts one at a time.

Standard Columns

Quantity-tracked rows: leave type blank for ordinary one-row-one-item assets. Set it to QUANTITY_TRACKED for consumables and bulk stock, and give the row a quantity and a consumptionType. See Quantity-Tracked Assets and Consumables for what the two consumption types mean in practice.

Auto-creation: category, kit, location, assetModel, tags, and custodian are matched by name and created automatically if they don't already exist in your workspace — you don't need to pre-create them. For custodian specifically, Shelf creates a non-registered team member (NRM) with that name. The column is matched by name, not email — using an email address will create an NRM literally named john@company.com.

bookable semantics: anything other than the literal string no (including blank, yes, true) leaves the asset bookable. Use no to opt out.

imageUrl semantics: any publicly reachable http(s) URL works — the link no longer has to end in .png, .jpg, or .jpeg. Dynamic image endpoints (for example an ASP.NET handler like https://host/GetImage.ashx?guid=… that serves image bytes from a query string) import correctly. Shelf downloads the URL and confirms the file is a real image (PNG, JPEG, GIF, WebP, or BMP) from its contents, not from the URL text, so a link that doesn't actually return an image is rejected after the download attempt.

Multi-value cells: tags (and the barcode_* columns below) hold multiple values separated by commas inside a single cell. In a comma-delimited file the cell must be double-quoted ("high-priority,fragile"); in a semicolon-delimited file no quoting is needed.

A value that contains a comma: wrap that one value in double quotes inside the cell, so Shelf reads it as one value rather than splitting it. Because those quotes sit inside the cell, the whole cell must be quoted too and the inner quotes doubled, whichever delimiter the file uses. For two tags, Berlin, DE and small, the cell is written """Berlin, DE"",small". The same rule applies to a barcode value such as SN-2024,001. Leave off the outer quotes and the row goes wrong. In a comma-delimited file, "Berlin, DE",small becomes two cells: the tag is Berlin, DE, small lands in the next column, and every value after it moves one column to the right. In a semicolon-delimited file, Shelf cannot read the file at all. In a spreadsheet application, type "Berlin, DE",small into the cell and the application adds the outer quotes when it saves as CSV. A cell with no quotes in it, like a,b,c, still means three values. An Import-ready export writes these cells correctly for you.

Advanced Features

Custom Fields

Create custom fields using the header format: cf:FieldName,type:TypeName

If the field doesn't exist in your workspace, Shelf creates it on import with the type from the header. cf: is case-insensitive; the field name is trimmed.

Supported field types (exactly seven):

• text -- Standard text input (default if type: is omitted)
• multiline text -- Extended text areas / markdown
• option -- Dropdown selections. Allowed values are collected automatically from the data in that column — you do not declare options in the header
• boolean -- Accepts yes or no only (case-insensitive). Any other value (including true, false, 1, 0) is silently skipped for that row
• date -- YYYY-MM-DD only. Any other format is a hard error
• amount -- Plain number with . decimal. Uses your organization's currency — there is no per-column currency. Currency symbols and thousands separators are rejected
• number -- Plain number, negatives allowed. Same numeric rules as amount

Example custom field CSV (comma-delimited — the headers must be double-quoted because they contain commas):

title,"cf:Purchase Date,type:date","cf:Warranty Status,type:option"
MacBook Pro,2023-12-15,Active
iPhone 14,2024-01-10,Expired

If you use semicolon (;) as the delimiter instead, the commas inside cf:…,type:… are not the delimiter, so the headers do not need to be quoted:

title;cf:Purchase Date,type:date;cf:Warranty Status,type:option
MacBook Pro;2023-12-15;Active
iPhone 14;2024-01-10;Expired

QR Code Integration

Link imported assets to existing Shelf QR codes:

• QR code must already exist in your workspace
• Each QR code must be unique
• Cannot already be linked to assets or kits
• Must belong to your organization

If no QR ID is provided, Shelf automatically generates new codes.

Barcode Support (Paid Add-on)

The Alternative Barcodes add-on must be enabled before importing any barcode_* data. The behavior when it is not enabled is asymmetric and worth knowing up front:

• A populated barcode_Code128, barcode_Code39, or barcode_DataMatrix column hard-fails the whole import with a 403 error ("Your workspace doesn't have barcodes enabled").
• A populated barcode_ExternalQR or barcode_EAN13 column is silently ignored — the import succeeds, but no barcodes are created on those rows.

Enable the add-on first if any of these columns contain data you need.

Supported barcode types (header names as in the template; the mapping step matches them regardless of capitals):

• barcode_Code128 — 4-40 characters, ASCII printable (letters, numbers, symbols)
• barcode_Code39 — 4-43 characters, A-Z and 0-9 only
• barcode_DataMatrix — 4-100 characters, ASCII printable
• barcode_ExternalQR — 1-2048 characters, any UTF-8 — case is preserved
• barcode_EAN13 — exactly 13 digits, with a valid check digit (Shelf rejects invalid check digits)

Barcode rules:

• For multiple barcodes of the same type on one asset, separate values with commas inside that single cell (e.g. LAT5550-001,LAT5550-002). In a comma-delimited file the cell must be wrapped in double quotes.
• A barcode value that itself contains a comma (Code128, DataMatrix and ExternalQR all allow one) must be quoted inside the cell, as described under multi-value cells. Otherwise it is read as two barcodes.
• Values must be unique within the file and across your workspace; duplicates are surfaced before import.
• Code128, Code39, DataMatrix, and EAN13 are upper-cased on save; ExternalQR preserves the original case.

Example barcode CSV (comma-delimited, with a valid EAN13 and a multi-value Code128 cell):

title,barcode_Code128,barcode_EAN13
Laptop,"LAP001,LAP002",9780201379624
Mouse,MOUSE001,4006381333931

Kit and Custody Management

When importing assets with custodians and kits:

• New kits automatically inherit custody from their assets
• Empty existing kits update to match asset custodian
• Kits with existing assets validate for consistency

Import Process

Pre-Import Validation

Shelf checks the whole file before it writes anything. The checks cover:

1. File format and encoding validity
2. Header accuracy against supported columns
3. The 10,000-asset limit
4. Quantity-tracked columns on every row (type, quantity, consumptionType and the rest)
5. Asset models on quantity-tracked rows, which are not allowed
6. Custom field headers: an unknown type, a type that contradicts a field already in your workspace, or two columns giving the same field different types
7. Custom field values that the column's type cannot accept
8. QR code availability and status
9. Barcode feature permissions
10. Kit-custody conflict prevention

If any check fails, nothing is created: no assets, and none of the categories, tags, locations, kits, custom fields or asset models the file names. For checks 3 to 7 the import page shows a Row / Problem table listing every problem those checks found, so one upload shows all of them at once. QR code and barcode problems (a code that does not exist, is already linked, or appears twice) are listed in the same table. The barcode add-on check and the kit-custody check still stop with a message of their own. Row numbers match your spreadsheet (the header is row 1, so the first asset is row 2). A problem with the file as a whole, such as a faulty column header, is listed once under File. When a file has more than 100 problems, the table shows the first 100 and says how many there are in total.

The Preview

When the checks pass, Shelf shows a preview of the file before anything is created:

• Counts of the assets in the file, and how many have an image, a custodian or a kit
• What will be created: the new categories, locations, tags, kits, custodians, custom fields and asset models the file names, listed by name
• A grid of the rows, with values that will create something new marked New: will be created on import. Click Load more to see further rows

If the preview is not what you expected, click Choose a different file. Nothing has been written. A preview you do not confirm expires after 24 hours; upload the file again to start over.

Running the Import

Click Import N assets, type "I AGREE" and click Import. Shelf imports the file you previewed; it is not uploaded again. You are taken to the import's own page, which shows a progress bar and what Shelf is doing: Waiting to start..., then Preparing categories, locations and tags, Importing assets and Finishing up.

You do not have to stay on the page. While the import runs, a small progress card follows you around Shelf, and the assets list shows everyone in the workspace that an import is running. When it finishes, the person who started it gets an email: Your asset import is complete, or Your asset import stopped.

One import runs in a workspace at a time. The import page holds the upload form until the running import finishes.

If the Import Stops

If the import stops, the rows already imported stay, and nothing is imported twice. Open the import with Open import in the email, or View progress on the progress card, and click Resume import to continue from the first row that was not imported. Do not upload the same file again: that creates a second copy of every row already in.

Row Warnings

Something can change in Shelf between the preview and the moment a row is written. Instead of stopping the import, those rows get a warning, listed on the import page and counted in the email:

• A QR code from the file was linked to another asset in the meantime: the asset is created with a new Shelf QR code
• A barcode is now in use by another asset: that barcode is skipped
• A custom field value no longer fits the field: that value is skipped
• An image could not be downloaded: the asset is created without it
• Kit custody could not be assigned: the asset is created without that custody

For round-trip edits to existing assets, use Bulk Updating Assets via CSV instead.

Troubleshooting

Common Error Messages

"Invalid headers in csv file"

• In the mapping step, check that each column points at the right Shelf field, or set it to Skip. Two columns pointing at the same field turn red and must be fixed first
• Check custom field format: cf:FieldName,type:TypeName
• Remove extra spaces or special characters

"Too many columns" or "Column heading too long"

• A file can have at most 200 columns, and each heading at most 1,000 characters. Delete the columns you do not need, or shorten the heading the message names, and upload again

"CSV file is empty"

• File requires minimum 2 rows (headers + 1 data row)
• Confirm file saved properly as .csv

QR Code Issues

• Duplicate codes: Each qrId must be unique in import
• Non-existent codes: Must exist in Shelf beforehand
• Already linked: Cannot link to other assets or kits
• Wrong organization: Must belong to your workspace

Kit Custody Conflicts

• All assets in a kit must share the same custodian
• Cannot assign different custodian to kit with existing assets

Data Format Issues

Date fields not importing:

• Use only YYYY-MM-DD format (e.g., 2024-01-15)
• Avoid MM/DD/YYYY or DD-MM-YYYY formats

Boolean fields incorrect:

• Custom-field booleans accept only yes or no (case-insensitive). true, false, 1, 0 are silently skipped — the value will not be saved.
• The bookable column treats anything other than the exact string no as bookable, so false, blank, and yes all leave the asset bookable. Use no to opt out.

Tags not separating:

• Separate tags with commas inside a single cell: electronics,laptop,portable. Spaces around commas are trimmed automatically, so electronics, laptop resolves to the tag laptop, not laptop.
• In a comma-delimited file the whole tags cell must be wrapped in double quotes ("electronics,laptop"); in a semicolon-delimited file no quoting is needed.
• A tag whose name contains a comma, such as Berlin, DE, is split in two unless that name is quoted inside the cell. See multi-value cells for the exact form.

Custodian not found:

• The custodian column is matched by name, not email. Use the exact display name (e.g. John Doe).
• If no team member by that name exists, Shelf creates a non-registered team member automatically — you do not need to pre-create them. Using an email address will create a team member literally named after the email.

Best Practices

Before Importing

• Clean data and remove empty rows
• Test with small batch (5-10 assets) first
• Back up existing data before large imports
• Plan your categories, locations, and kits — you don't need to create them up front (they're auto-created on import), but a clean naming scheme makes the result tidier

After Importing

• Review all imported assets for accuracy
• Verify kit, category, and location linkages
• Test QR code scanning
• Update team member permissions

Large Imports (1,000+ assets)

• Up to 10,000 assets fit in one file; split a bigger inventory into files of that size or smaller
• Start the next file once the previous import has finished, since one import runs at a time
• Image downloads take the most time; a row whose image cannot be fetched in time is imported without it, with a warning

Related Resources

• Bulk Updating Assets via CSV — edit existing asset records in bulk using an exported CSV
• Export / Exporting Workspace Data from Shelf — how to export your assets for bulk update
• Adding additional fields to Assets
• Alternative Barcodes
• Switching From Another Asset Tool to Shelf — moving a whole inventory from another tool, labels included

Contact support if you need personalized assistance with a specific CSV file.