Migrating Data

If you are moving from spreadsheets, another inventory system, or a self-hosted OpenBoxes instance, this guide explains how to get your existing data into OpenBoxes on Lift.

Two Ways to Import#

There are two tools, and they suit different situations:

  1. The Lift import wizard (recommended) — Import Data in the portal sidebar. It detects your source, maps columns for you, validates everything before anything is written, walks you through fixing what it could not resolve, and can bring over transaction history as well as reference data. Use it for any migration of real size.
  2. OpenBoxes' built-in Excel/CSV import — inside the OpenBoxes application itself. Handy as a fallback for small, one-off lists (a few dozen products, a handful of locations) once you are up and running. See Using the In-App Importer at the end of this guide.

Choosing Your Path#

The signup wizard asks where your data is coming from (the Import / Migrate step). After signup, the Import Data page in the portal offers the first three paths as cards — Self-hosted OpenBoxes, Another system, and Spreadsheet or file — so you can change your mind at any time. Starting fresh is a signup-wizard choice only; once you have an instance there is simply nothing to import.

Your situation Path What it takes
You already run OpenBoxes on your own server Migrate from self-hosted OpenBoxes A database dump of your existing instance (we provide an export tool and a guide)
You use another inventory or supply chain system Migrate from another inventory system An export from that system — mSupply, OpenLMIS, DHIS2, ERPNext, Odoo, Shopify, QuickBooks, Xero, and others
Your data lives in spreadsheets Import from a spreadsheet or file One or more CSV or Excel files; the wizard auto-detects and maps the columns
You are starting from nothing Start with a fresh instance Nothing — you get an empty instance and a guided getting-started checklist

Migrating from Self-Hosted OpenBoxes#

This is a full migration of your existing instance — products, locations, inventory, users, and transaction history — not a partial re-keying:

  1. Choose Migrate from self-hosted OpenBoxes (in the signup wizard or under Import Data).
  2. Follow the in-portal export guide to take a dump of your current database with the export tool we provide, and upload it. Large dumps can be staged during signup and resumed later.
  3. The wizard previews what it found — table counts, OpenBoxes version, any schema differences from the version Lift runs — and reconciles them against the export's own manifest.
  4. Confirm, and the data is loaded into your Lift instance. You can plan the cutover so your team keeps working on the old system until the new one is verified.

If your self-hosted instance is on an older OpenBoxes release, the wizard tells you what it can and cannot carry across before anything is written. Email support@openboxes.cloud if you would like help planning the cutover.

Migrating from Another System#

  1. Export your data from the source system. The wizard has export guides for the systems it recognises (mSupply, OpenLMIS, DHIS2, ERPNext, Odoo, Shopify, QuickBooks, Xero, and more).
  2. Choose Migrate from another inventory system and upload the export files.
  3. The wizard detects the source and maps its columns onto OpenBoxes fields. Where the mapping is uncertain it says so and asks you rather than guessing.
  4. Review the validation report, resolve anything flagged (unknown categories, units, locations), and confirm the load.

Where the source provides it, stock movement history comes across too; where it does not, you start with current stock balances.

Importing from Spreadsheets#

  1. Choose Import from a spreadsheet or file and upload your CSV or Excel files. You do not need to reshape them into a fixed template first — the wizard reads your headers and proposes a mapping.
  2. Check the proposed mapping and adjust any column it got wrong.
  3. Review the validation report. Rows it cannot resolve (a category that does not exist, an unrecognised unit of measure, an ambiguous location) are parked for you to fix in a guided resolution step — they are never silently dropped.
  4. Confirm the load, then spot-check the results in OpenBoxes.

Downloadable templates are available from the wizard if you would rather start from a clean layout.

What Can Be Imported#

Through the wizard, anything that belongs in an OpenBoxes database can come across when your source has it:

  • Reference data — products, product categories, units of measure, locations (warehouses, depots, suppliers, customers), organizations, and people
  • Inventory — current stock balances by location, lot, and expiry
  • Transaction history — stock movements, receipts, issues, adjustments, and cycle counts, when the source provides them
  • Users — carried over from a self-hosted OpenBoxes migration; otherwise, invite team members from Users in the portal sidebar

Anything the wizard cannot place is reported, not discarded, so you always know what did and did not make it.

Before You Start#

Plan Your Import Order#

The wizard handles ordering for you within a single import. If you are importing from several separate files, load them in dependency order to avoid unresolved references:

  1. Categories — Product categories must exist before products reference them
  2. Locations — Warehouses and suppliers should be created before inventory or purchasing data
  3. Products — Requires categories to be in place
  4. Inventory — Requires both products and locations

Clean Your Data#

Time spent preparing your data before importing prevents the majority of import problems — even with automatic mapping, the wizard can only resolve what is consistent.

  • Remove duplicates. Check for products that appear more than once under slightly different names.
  • Standardize naming. Decide on a consistent convention (e.g., "Paracetamol 500mg Tablet" vs. "PARACETAMOL TAB 500MG") and apply it across the file.
  • Assign product codes. Every product needs a unique code. If your existing data does not have codes, create a scheme before importing (e.g., MED-001, SUP-001).
  • Verify categories. Map every product to a category. Products without a category will use the default "Root" category.
  • Check units of measure. Use consistent units (Each, Box, Case, Pallet) and make sure they match what OpenBoxes expects.

Best Practices#

  • Start with a small test. Import 10 to 20 products first to verify the mapping before loading your full catalog.
  • Use product codes consistently. Once imported, product codes become the unique key for future updates. Choose codes you will not need to change.
  • Record your opening balances on a specific date. Pick a date when you have accurate counts (e.g., after a physical inventory). This becomes your Day 1 in OpenBoxes.
  • Take a backup before a big load. Backups > Run backup now in the portal gives you a snapshot to restore from if an import does not go as planned.
  • Keep a copy of your source files. Store the original exports or spreadsheets so you have a reference if questions come up later.
  • Validate after import. Spot-check 10 to 15 products in OpenBoxes to confirm quantities, categories, and details match your source data, and compare the wizard's reconciliation counts against what you expected.

Common Pitfalls#

Problem Cause Fix
Rows parked as "unresolved category" Category name in the file does not match an existing OpenBoxes category Pick the matching category in the resolution step, or add the category and re-run.
Duplicate product code A product with the same code already exists Use unique codes. Check for leading/trailing spaces in the code column.
Wrong quantities after import Quantity column formatted as text instead of number Ensure the quantity column is formatted as a number in Excel.
Missing products in search Products imported but not visible Check that you are looking at the correct location. Products are global, but inventory is per-location.
Date parsing errors Expiration dates in an ambiguous format Use YYYY-MM-DD format (e.g., 2026-12-31). Avoid locale-specific formats like MM/DD/YYYY.
Header not detected The sheet has a title block or blank rows above the real header Remove the preamble so the column headers are on the first row.

Using the In-App Importer#

For small follow-up lists after you are live, OpenBoxes' own importer is still available inside the application:

  1. Log in to your OpenBoxes instance.
  2. Go to Products > Import and click Download Template for the data type you want (products, inventory, locations).
  3. Fill in the template in Excel or Google Sheets, save as .xlsx or .csv, and upload it from the same page.
  4. Review the preview — rows with errors are highlighted — fix the spreadsheet, re-upload if needed, and click Import.

Note that the in-app inventory import replaces existing balances for the products it lists rather than adding to them, and it does not offer the Lift wizard's automatic mapping, validation, or resolution steps. For anything beyond a small list, use Import Data in the portal.

Getting Help#

If you run into issues during your import:

  • Read the validation report. The wizard lists problems row by row with specific descriptions and, where it can, a suggested fix.
  • Use the support chat. Support chat is built into the portal on every plan and can see the state of your import.
  • Contact support. Email support@openboxes.cloud with a description of the error. Our team can review your data and help resolve issues.

Next Steps#