Migrating Data

If you are moving from spreadsheets, another system, or a self-hosted OpenBoxes instance, this guide walks you through importing your existing data into OpenBoxes on Lift.

What Can Be Imported

OpenBoxes supports bulk import for the following data types:

Data Type Import Method Notes
Products Excel/CSV upload Product code, name, category, unit of measure
Product categories Excel/CSV upload Category hierarchy
Locations Excel/CSV upload Warehouses, depots, suppliers, customers
Inventory Excel/CSV upload Opening stock balances by location and lot
People and organizations Excel/CSV upload Suppliers, customers, and contacts
Users Portal invitation Invite team members through the Lift portal

Stock movements, purchase orders, and transaction history are typically not imported. Most organizations start fresh with transactions and bring in reference data (products, locations) and current inventory balances.

Before You Start

Plan Your Import Order

Data in OpenBoxes has dependencies. Import in this order to avoid errors:

  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

Spend time preparing your data before importing. This single step prevents the majority of import problems.

  • 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.

Download the Import Templates

OpenBoxes provides Excel templates with the correct column headers and formatting. To download them:

  1. Log in to your OpenBoxes instance.
  2. Go to Products > Import.
  3. Click Download Template for the data type you want to import.

Using the official templates ensures your columns match what the importer expects.

Step-by-Step Import Process

Importing Products

  1. Open the product import template in Excel or Google Sheets.
  2. Fill in one row per product:
    • Product Code (required) -- Unique identifier
    • Name (required) -- Display name
    • Category (required) -- Must match an existing category name
    • Unit of Measure (required) -- e.g., Each, Box, Bottle
    • Description (optional) -- Additional detail
    • Manufacturer (optional) -- Manufacturer name
    • Brand Name (optional) -- Brand or trade name
  3. Save the file as .xlsx or .csv.
  4. In OpenBoxes, go to Products > Import.
  5. Click Choose File, select your spreadsheet, and click Upload.
  6. Review the preview screen. OpenBoxes will show any rows with errors highlighted in red.
  7. Fix errors in your spreadsheet, re-upload if needed, and click Import to confirm.

Importing Inventory Balances

After products and locations are set up, import your opening stock:

  1. Open the inventory import template.
  2. Fill in one row per inventory record:
    • Product Code (required) -- Must match an existing product
    • Location (required) -- Must match an existing location name
    • Lot Number (optional) -- For lot-tracked items
    • Expiration Date (optional) -- Format: YYYY-MM-DD
    • Quantity (required) -- Current quantity on hand
    • Bin Location (optional) -- Specific storage location within the warehouse
  3. Upload and review as described above.

Importing Locations

  1. Open the location import template.
  2. Fill in one row per location:
    • Name (required) -- Location display name
    • Location Type (required) -- Warehouse, Depot, Supplier, Customer, etc.
    • Organization (optional) -- Parent organization name
    • Address (optional) -- Street address
  3. Upload, review, and confirm.

Best Practices

  • Start with a small test. Import 10 to 20 products first to verify formatting 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.
  • Keep a backup of your import files. Store the original 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.

Common Pitfalls

Problem Cause Fix
"Category not found" error Category name in spreadsheet does not match OpenBoxes Check spelling and capitalization exactly. Import categories first.
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 wrong format Use YYYY-MM-DD format (e.g., 2026-12-31). Avoid locale-specific formats like MM/DD/YYYY.
Import hangs or times out File is very large (10,000+ rows) Split into smaller batches of 2,000 to 5,000 rows.

Migrating from Self-Hosted OpenBoxes

If you are already running a self-hosted OpenBoxes instance, contact our team at support@openboxes.cloud. We can assist with:

  • Direct database migration for a seamless transition
  • Data validation and integrity checks
  • Coordinated cutover planning to minimize downtime

Enterprise plan customers receive dedicated migration support as part of their onboarding.

Getting Help

If you run into issues during your import:

  • Check the error messages. The import preview screen highlights problems row by row with specific error descriptions.
  • Review the templates. Compare your file against the download template to catch formatting differences.
  • Contact support. Email support@openboxes.cloud with your import file attached and a description of the error. Our team can review your data and help resolve issues.

Next Steps