📦 Admin
Import / Export
Data Export & Import lets you pull your core business data out into Excel, CSV or a JSON bundle, and bring bulk data — products, customers, suppliers, expenses, categories — back in from a spreadsheet.
📍 Menu path: Admin → Import / Export
👤 Who uses it: Admin and Manager (with create/export permission) — requires the Advanced plan tier or above
🏷️ Plan tier: advanced+
Overview
Eight entity types are supported: Products, Customers, Sales, Inventory, Suppliers, Expenses, Purchase Orders, and Categories. Sales, Inventory and Purchase Orders are export-only — they are generated by the system and not meant to be bulk-created from a spreadsheet.
Export supports three formats: an Excel workbook with one sheet per entity, a set of individual CSV files (one per selected entity), or a single machine-readable JSON bundle intended for backup or migration between installations.
Import accepts .xlsx/.xls (each sheet mapped automatically to an entity by name), a single-entity .csv (you tell it which entity the file represents), or a .json bundle previously exported from this same screen.
Before You Start
- Requires the
data_portfeature at theAdvancedplan tier or above. - Importing requires a specific branch to be selected from the header scope dropdown — Admins/Managers viewing at a company-wide or unit level must first switch to a single branch before importing.
- Export requires export permission; import requires create permission on this page.
Step-by-Step Guide
1 Export selected data
- Open the Export Data tab (default).
- Choose a format: Excel (.xlsx) for one file with multiple sheets, CSV (.csv) for one file per dataset, or JSON Bundle (.json) for a single machine-readable file best suited to backup/migration.
- Tick the datasets you want under Select Datasets, or use the All/None shortcuts.
- If Sales, Expenses or Purchase Orders are selected, set a date range — quick buttons for This Month, This Year, and All Time are provided.
- Click Export to Excel/CSV/JSON. Progress is shown per-dataset while exporting; the file(s) download automatically when done.
2 Download a blank import template
- Click Import Template in the page header to download a blank Excel workbook with one correctly-headed sheet per importable entity.
- Fill in your data under the existing column headers, keeping one row per record.
3 Import data from Excel, CSV or JSON
- Switch to the Import Data tab.
- Make sure a specific branch is selected in the header scope dropdown — the page shows a warning banner if it is not.
- Drag your file onto the drop zone, or click it to browse — .xlsx, .xls, .csv and .json are all supported.
- For a multi-sheet Excel file, each sheet is automatically matched to an entity by its name (e.g. "Products", "Customers"); unrecognised sheet names are flagged so you can rename them to match.
- For a single-entity CSV, choose which entity type the file represents from the buttons shown (e.g. Products, Customers, Suppliers, Expenses, Categories).
- Click a sheet's row to expand a live preview of its first few rows before importing.
- Click Import N Dataset(s). A per-sheet result list shows how many rows were successfully imported vs. skipped, with an error message for any sheet that failed.
💡 Products are matched/created by SKU, and Suppliers/Categories are matched by name for updates instead of creating duplicates — re-importing the same file is safe.
Every Field & Button, Explained
| Field / Button | What it does |
|---|---|
Export Format (Excel / CSV / JSON) | Excel bundles every selected dataset as separate sheets in one file; CSV downloads one file per dataset; JSON bundles everything into one machine-readable file for backup or migration. |
Select Datasets | Checkbox grid of Products, Customers, Sales, Inventory, Suppliers, Expenses, Purchase Orders, Categories; entities marked "Export only" cannot be re-imported. |
Date Range (Sales/Expenses/POs) | From/To dates restricting the export window for the three date-sensitive entities, with This Month / This Year / All Time quick-select buttons. |
Import Template button | Downloads a blank .xlsx with correctly labelled columns for every importable entity, ready to fill in. |
Drop zone | Drag-and-drop or click-to-browse file picker accepting .xlsx, .xls, .csv, and .json. |
CSV entity selector | Appears only for single-sheet CSV uploads — tells the importer which entity (Products, Customers, Suppliers, Expenses, Categories) the rows represent. |
Sheet preview | Expandable row-level preview (first few rows) of each detected sheet before committing to import. |
Import results list | Per-sheet outcome after import: rows read vs. records actually imported, or an error message if that sheet failed. |
No-branch warning banner | Blocks importing until a specific branch (not "all branches"/company view) is selected in the header scope dropdown. |
Tips & Best Practices
- Always download the Import Template first rather than hand-building your own spreadsheet — the column headers must match exactly (or use the plain lower-case field name as a fallback) for the importer to recognise them.
- When migrating between installations, prefer the JSON Bundle format — it is the most complete, faithful representation of your data and is what the importer parses most reliably.
- Re-running an import with updated rows is safe for Products (matched by SKU) and Suppliers/Categories (matched by name) — existing records are updated in place rather than duplicated.
Troubleshooting & FAQ
Import button is disabled and shows a branch warning.
You must select one specific branch from the header scope dropdown before importing — company-wide or unit-level views are not valid import targets.
Some sheets say "Entity not recognized".
Rename the Excel sheet to one of the recognised names (Products, Customers, Suppliers, Expenses, Categories, Purchase Orders) — matching is case-insensitive but must contain the recognised keyword.
Sales, Inventory or Purchase Orders won't import.
These three are export-only by design — they reflect data generated through normal POS operation and are not meant to be bulk-created from a spreadsheet.
Some rows were skipped during import.
Rows missing a required field (e.g. a product without a Name or SKU, a customer without a Name) are silently skipped — check the Import Results count against your file's row count and fix any incomplete rows.
🧑💻 Developer Notes
Source component(s):
frontend-app/packages/pos-react-lib/src/pages/DataPortPage.jsx
Backend endpoints used:
GET /products, GET /customers, GET /sales, GET /inventory, GET /ledger/suppliers, GET /accounting/expenses, GET /purchase-orders, GET /products/categoriesPOST /sync/importPOST /suppliers, PUT /suppliers/:idPOST /accounting/expensesPOST /products/categories, PUT /products/categories/:id
Related tables (db-core repositories):
ProductCustomerSaleInventorySupplierExpensePurchaseOrderCategory
Redux slices:
scopeSlice (selectCurrentScope / getScopeQueryParams)auth (selectedStoreId, businessId, user.role)
Feature flag key: data_port (requires advanced plan tier or above)
Uses the xlsx (SheetJS) library entirely client-side for parsing/generating Excel files — no server round-trip is needed just to read an uploaded workbook. Product and Customer imports also push newly-created records into the local dataSyncEngine so LAN/cloud-synced devices pick them up without a full re-sync.