🔢 electronics

IMEI Registry

IMEI Registry is a serialised device ledger — one row per physical unit identified by its IMEI — used to track condition grade, included accessories, supplier/purchase-order origin, and sale status separately from generic product-quantity stock.

📍 Menu path: /electronics/imei

👤 Who uses it: Owner,Manager,Staff

Overview

Each entry records both IMEI numbers (for dual-SIM handsets), serial number, product name, brand, model, color, storage, a Condition/Grade (New, Grade A/B/C), purchase date, supplier name, purchase order/batch reference, an accessories checklist, and notes.

Status moves through IN_STOCK, SOLD, RETURNED or DEFECTIVE; editing a SOLD unit reveals Sold To, Buyer Phone and Sale Date fields.

A Bulk Import tool lets you upload a CSV of many IMEIs at once — download a starter template, choose a file, preview the parsed rows, then import in one click with a created/already-exists/errors summary.

IMEI and Product Name are the only two required fields; everything else (grade, accessories, supplier, dates) is optional metadata layered on top of the core identifier.

Before You Start

No plan-tier restriction beyond the route's general "billing" feature gate.
IMEI is enforced unique in the database — attempting to register or bulk-import a duplicate IMEI will be rejected/skipped rather than overwritten.
Bulk Import requires a CSV with at minimum an "imei" and "productName" column per row; rows missing either are silently dropped from the preview before import.

Step-by-Step Guide

1 Register a single device

Click Register IMEI.
Enter IMEI 1 * (required, up to 20 characters) and, for dual-SIM devices, IMEI 2.
Enter Product Name * (required), Brand, Model Number, Serial Number, Color and Storage.
Pick Condition/Grade — New, Grade A (Like New), Grade B (Good), or Grade C (Fair/Parts).
Enter Purchase/Received Date, Supplier Name and Purchase Order/Batch Ref.
Tick every Accessory Included from the checklist — Box, Charger, USB Cable, Earphones, Screen Protector, Case, Manual, SIM Eject Tool.
Add any Notes and click Register.

2 Bulk import many devices from CSV

Click Bulk Import.
Click Download Template for a starter CSV with the correct columns (imei, imei2, serialNumber, productName, brand, modelNumber, color, storage, grade, purchaseDate, supplierName, purchaseOrderRef, notes) and two sample rows.
Fill in your own rows in the same format and save as CSV.
Click Choose CSV File and select it — a preview table shows every row that has both an IMEI and a Product Name.
Click Import N Records — a summary shows how many were Created, how many were Already Exist (skipped as duplicate IMEIs), and any row-level Errors with the specific IMEI and reason.

💡 The CSV parser is a simple comma split with basic quote-stripping — it does not handle values that themselves contain commas (e.g. a product name like "Galaxy S24, Black"); keep such fields comma-free or wrap them carefully.

3 Edit a device or mark it sold

Click the edit icon on any row.
Update any field, including Status (In Stock, Sold, Returned, Defective).
If Status is changed to Sold, Sold To, Buyer Phone and Sale Date fields appear — fill them in and save.

4 Search, filter and delete

Use the search box to filter by IMEI, product name, serial number, buyer name or brand.
Use the status chips (All, In Stock, Sold, Returned, Defective) to narrow the table.
Click the trash icon to permanently delete a record — this option is hidden once a device's status is Sold, to prevent losing the record of a completed sale.

Every Field & Button, Explained

Field / Button	What it does
`Register IMEI`	Opens the blank device registration form.
`Bulk Import`	Opens the CSV bulk-import modal with a downloadable template.
`In Stock / Sold / Total stat tiles`	Live counts across every registered device.
`IMEI 1 *`	Required primary IMEI, up to 20 characters, shown in monospace.
`IMEI 2`	Optional second IMEI for dual-SIM devices.
`Product Name *`	Required device/product name.
`Brand / Model Number / Serial Number / Color / Storage`	Optional identifying and variant details.
`Condition / Grade`	New, Grade A (Like New), Grade B (Good), or Grade C (Fair/Parts) — shown as a colour-coded badge in the table.
`Purchase / Received Date`	The date this unit was received into stock.
`Supplier Name / Purchase Order / Batch Ref`	Origin tracking — shown under the product name in the table when set.
`Accessories Included`	Checklist of Box, Charger, USB Cable, Earphones, Screen Protector, Case, Manual, SIM Eject Tool; stored as a JSON list and summarised as "N acc" in the table.
`Status`	IN_STOCK, SOLD, RETURNED or DEFECTIVE — only editable, not settable at creation.
`Sold To / Buyer Phone / Sale Date`	Only shown in the edit form once Status is set to Sold.
`Notes`	Free-text notes on the device.
`Search box`	Filters by IMEI, IMEI2, product name, serial number, buyer name (Sold To) or brand.
`Status filter chips`	All, In Stock, Sold, Returned, Defective.
`Download Template (bulk import)`	Downloads a CSV with the correct headers and two example rows.
`Choose CSV File (bulk import)`	Parses the selected file client-side and previews valid rows (must have imei and productName).
`Import N Records`	Sends all previewed rows to the server in one request; result shows Created, Already Exist (skipped) and Errors counts.
`Edit icon`	Opens the form pre-filled for editing, including Status change.
`Delete icon`	Permanently deletes the record after a confirmation prompt; hidden once the device is Sold.

Tips & Best Practices

Use Bulk Import for a fresh stock delivery of 10+ handsets rather than registering each one by hand — download the template first so your columns line up exactly.
Tick the Accessories checklist honestly at intake — it becomes your reference if a customer later disputes what was in the box at time of sale or exchange.
Keep Purchase Order/Batch Ref consistent with your actual purchase orders — it is the fastest way to trace a defective unit back to the supplier batch it came from.
Grade devices consistently (New / A / B / C) across your whole team — the grade badge is only useful for pricing and customer trust if it means the same thing every time it is applied.

Troubleshooting & FAQ

Bulk import skipped some rows and I don't know why.

Rows without both an IMEI and a Product Name are silently dropped before you even see the preview table — check your CSV has values in both columns for every row. Rows that do reach the server but duplicate an existing IMEI show up in the "Already Exist" count instead of Created.

The CSV import garbled a product name or a whole row shifted columns.

The parser is a simple comma-delimited split with basic quote-stripping — if any field itself contains a comma (e.g. inside a product name or notes), it will break the column alignment. Remove commas from field values before importing.

I can't delete a device I registered by mistake.

The delete icon is intentionally hidden once a device's status is Sold, to protect the sales record; if it was truly registered in error before ever being sold, its status should still be In Stock and deletable.

Registering an IMEI failed with an error about it already existing.

IMEI is enforced unique — search the registry for that IMEI first; it likely already has a record (possibly Sold or Returned) that should be edited instead of duplicated.

Sold To / Buyer Phone fields aren't showing when I edit a device.

They only appear once Status is switched to Sold in the edit form — set the status first, then the extra fields will appear below it.

🧑‍💻 Developer Notes

Source component(s):

frontend-app/pos-app-electronics/src/pages/electronics/IMEIPage.jsx
frontend-app/packages/pos-react-lib/src/pages/electronics/IMEIPage.jsx

Backend endpoints used:

GET /electronics/imei
GET /electronics/imei/lookup
POST /electronics/imei
POST /electronics/imei/bulk
PUT /electronics/imei/:id
DELETE /electronics/imei/:id

Related tables (db-core repositories):

ElectronicsIMEI

Redux slices:

None — local component state only

Feature flag key: billing

The database schema enforces `imei TEXT NOT NULL UNIQUE`, so both single-record create and bulk import rely on that constraint for de-duplication rather than an explicit pre-check in the UI. The CSV parser (parseCSV) is entirely custom and naive — a straight `line.split(',')` after trimming quotes — with no support for quoted fields containing commas or embedded newlines; a more robust CSV library would be a reasonable future improvement if suppliers start sending richer export files. An unused GET /electronics/imei/lookup endpoint exists on the backend (for looking up a device by IMEI, e.g. from a barcode scan) but is not currently called anywhere in this component.