POS data migration guide
Import products from Excel or CSV into Posnic
Prepare the file, test a representative batch and reconcile every result before changing systems. Choose the route that matches who will own the work.
Preparing it yourself? Start with the seven release templates, then follow the controlled trial.
- 1PreserveKeep the untouched export.
- 2PrepareMatch the release template.
- 3ReconcileCheck records and stock.
What is released, tested and observed
For the published v1.6.1 source, seven shipped CSV templates passed 6/6 tests under the application's CSV row parser; those tests were structural.
Structure
Each nonblank row had the same number of fields as its header, including quoted values containing commas.
Usable examples
Every template contained a worked row and no entirely blank record that could become an empty import.
Safe sample data
Example email addresses used reserved example domains and known leftover test strings were absent.
Post-release source correction and runtime observation
Source commit c403ab8 replaces the old file gate and silent item plan truncation. Later source adds a shared standards-aware CSV parser and whole-file duplicate rejection. These changes are tested source, but they are not in the published archived evidence run download.
10 MiB file guard
The browser now checks a numeric 10 MiB ceiling, accepts .CSV case-insensitively and explains when a file must be split.
10,000 data rows
The browser and item API enforce the same ceiling. The API returns HTTP 413 before item repository import when a request contains more rows.
Whole-file plan decision
If an item-import plan limit is lower than the submitted count, Posnic reports submitted and allowed rows and imports none instead of quietly keeping only the first rows.
At source commit 5803f20, a reproducible runner used the same CSV parser as the browser import, the real item repository and an isolated MongoDB 7.0.14 database. The worktree was clean; 926/926 product tests passed. The latest complete API run passed 9,425 tests, skipped 13 and failed none.
| Submitted rows | CSV bytes | Shared parser | Repository + MongoDB | Persisted and reconciled |
|---|---|---|---|---|
| 100 | 14,718 | 1.193 ms | 281.397 ms | 100 |
| 1,000 | 146,259 | 4.596 ms | 1,771.779 ms | 1,000 |
| 10,000 | 1,470,601 | 32.916 ms | 15,269.858 ms | 10,000 |
Every scale preserved distinct IDs, leading-zero item IDs and barcodes, quoted commas and quote marks, a quoted multiline field, Unicode text and zero quantity. Separate plan-limit, duplicate-key and required-field cases produced zero database writes. A matched-row reimport updated price while preserving the image and behavior flag and writing price history.
Current release source: 567a176b · archived template evidence: source snapshot · runtime source: 5803f20 · Read the six stable template tests
The seven supplied CSV templates
Start with the file downloaded from the same Posnic release you will use. Keep its header spelling and column order unchanged.
| Template | Fields | Important preparation check |
|---|---|---|
items.csv | Name, item ID, barcode, category, supplier, discounts, HSN, tax, MRP, cost, selling price, quantity, unit and sort order. | Make item IDs and barcodes unique; decide whether tax is inclusive or exclusive; confirm cost and selling-price units. |
categories.csv | Name, fixed discount, percentage discount and description. | Create categories before items and avoid near-duplicates such as "Soft Drink" and "Soft Drinks". |
customerCategory.csv | Name and description. | Use categories that support a real pricing, credit or reporting workflow. |
customers.csv | Name, phone, email and address. | Normalize phone numbers and decide which field is the duplicate-matching key. |
suppliers.csv | Name, phone, email, address, country, state and city. | Use supplier names that exactly match the values referenced from item rows. |
employees.csv | ID, name, phone, email, address, country, state and city. | Use stable employee IDs; assign permissions separately after import. |
expenses.csv | Amount, type, category, recipient, approver and description. | Confirm the opening date range and debit/credit convention before including historical records. |
Prepare the spreadsheet before export
One row per sellable unit
Represent each size, colour or pack with its own item ID when it has a separate barcode, price or stock quantity.
Use plain values
Replace formulas with their calculated values. Remove merged cells, subtotals, comments, hidden headings and decorative blank rows.
Protect identifiers
Format barcodes, item IDs and phone numbers as text before CSV export so leading zeroes and long digits are preserved.
Standardise names
Choose one spelling for every category, supplier, unit and tax name. A trailing space can create a separate value.
Resolve duplicates
Check duplicate barcodes and item IDs, then decide which row is authoritative instead of importing both.
Choose an encoding
Export UTF-8 CSV and reopen the saved file to verify accented or non-Latin names before importing.
Controlled import workflow
- Freeze the source. Record the extraction time and stop parallel edits while the final file is prepared.
- Keep the original. Store an untouched export from the old system plus a human-readable report of item, customer and supplier totals.
- Back up Posnic. Create a recovery point before importing or changing an existing shop. See the backup and restore checklist.
- Import dependencies first. Load categories and suppliers before items when item rows refer to their names.
- Use a representative trial. Include taxed and untaxed items, discounts, long names, non-ASCII text, leading-zero barcodes, zero stock and decimal prices.
- Read every result. Save import warnings and rejected-row details. Correct the source file rather than patching many records manually.
- Reconcile the trial. Compare source and Posnic counts, open individual records and run a sale, return and stock adjustment.
- Load approved batches. Stay inside the exact tested version's file, row and subscription boundaries. Repeat the same reconciliation and record who approved the cutover.
Reconciliation that catches quiet errors
| Check | Compare | Failure to investigate |
|---|---|---|
| Record counts | Source rows, accepted rows, rejected rows and records visible in Posnic. | The numbers do not reconcile exactly. |
| Identifiers | Unique item IDs, barcode count and leading-zero examples. | Duplicates, scientific notation or shortened digits. |
| Commercial values | Cost, MRP, selling price, discount and tax mode for a sample from every category. | Decimal shifts, tax applied twice or inclusive tax treated as exclusive. |
| Opening stock | Total quantity and a sample of zero, negative, fractional and high-quantity items. | Pack quantities imported as individual units or unexpected rounding. |
| Relationships | Item category and supplier assignments. | Unassigned records caused by spelling or whitespace differences. |
| Till workflow | Search, scan, receipt total, payment, return and resulting stock movement. | An item exists but cannot be sold or changes stock incorrectly. |
Common questions
Can Excel data be imported into Posnic?
Prepare the worksheet as CSV using Posnic's supplied header names and order. Back up first, import a small representative batch and reconcile it before loading the full dataset.
How large can a Posnic item CSV import be?
The published archived source rejects files of 337,920 bytes or more before reading them. Post-release source adds a 10 MiB browser guard and a 10,000-data-row ceiling. A clean source run persisted and reconciled generated 100, 1,000 and 10,000-row files, but it bypassed the packaged UI and HTTP path and is not evidence about the archived evidence run download.
Should old transaction history be imported?
Only when the supported importer and a business requirement justify it. Many migrations preserve the old system or export as a read-only archive, then bring clean master data and verified opening balances into the new POS.
What should happen after import?
Verify counts and samples, complete a test sale and return, check tax and stock movement, print or preview a receipt, close the test shift and retain the reconciliation record.