Short answer. A product lives at three levels. The model carries what is described and photographed: name in two languages, brand, category, supplier, description, photos; it is not sold. The variant carries the one attribute that changes, volume, size, colour, dosage, and that is where stock is counted, in base units; its reference is generated, not typed. The packaging carries what is scanned and sold: a barcode unique across the whole catalogue, a factor to the base unit, a case of 4 is worth 4, and its entry in dated price grids, retail, wholesale, promotion. Attributes are defined per category, required or variant, so that a seller cannot create “T-shirt XL blue 2” on the fly. Old codes become aliases, never duplicates. A record has a status, draft, active, end of life, archived, and a history of every change; it is not deleted. And the take-over of the old file goes through a dry run, proposed merges and lines refused in writing.
This guide is for the wholesaler whose catalogue has grown in a file for ten years, the shopkeeper opening an online store who discovers every product exists three times, the founder based in France who wants a catalogue sellable on the site, at the till and by the sales reps, and the storekeeper who scans a case and invoices a unit. It does not repeat how to keep stock right, described in the stock guide, nor how to import a file every week, described in the import guide; it describes the structure those two guides assume, and it extends our software engineering page.
One product, three levels
The figure follows a table oil from the model down to the pallet. What lives at which level is not a matter of taste, it is what decides whether scanning, stock and price are right.
The model carries what is written once: the name in French and Arabic, the brand, the category, the supplier, the description and the photos. It has no stock and no price, because nobody sells “Fleurial oil”, they sell a precise volume. The variant carries the value of its category's variant attribute, here the volume, and it is the one with stock, counted in base units in the movement ledger of the stock guide. Its reference is composed by the application from the model and the attribute, HT-FLEU-5, never typed by a seller.
The packaging is what you hold in your hand and what you scan: the bottle, the case of 4, the pallet of 112 cases. Each has its barcode, its factor to the base unit, 1, 4, 448, and its entry in the price grids. When the storekeeper scans a case at receiving, the variant's stock goes up by 4; when the till scans a bottle, it goes down by 1. Retail barcodes (GTINs) come in 8, 12, 13 and 14 digits; the 14-digit code serves logistic units, cases and pallets, and is not read at the till, according to the public documentation of the GTIN system. References, codes, factors and prices in the figure are a constructed example.
«Stock is counted at the variant, price and barcode live at the packaging, description and photos live at the model, once.»
Creating a product properly, in six steps
The order of the steps is the one the creation screen imposes, and it starts with the category, because the category says which fields exist.
Choose the category: it carries the list of required attributes, brand and supplier for an oil, dosage and form for a medicine, and the variant attribute, volume, size, colour; no category, no record. Describe the model: name in two languages, brand, supplier, description, photos; it is the only free entry, and it is done once. Declare the variants: one per value of the variant attribute, 1 L, 2 L, 5 L; the reference is generated, and a value already taken is refused. This is the accented step, because it is where Excel files manufacture their duplicates: a new line typed by hand with an invented code.
Declare the packagings: the base unit first, then the case and the pallet with their factor; a factor is checked at receiving, an opened case holding 6 instead of 4 is an anomaly, not a silent correction. Scan the codes: one barcode per packaging, read by scanner rather than typed; a code already present elsewhere in the catalogue is refused at entry with the name of the record that carries it. Set the prices: per packaging and per grid, retail, wholesale, promotion with start and end dates; a sales line reads the grid, following the rule set in the quote and invoice guide, and never retypes a price.
The catalogue, in five layers
Identifiers are the accented layer: a scanned code must find exactly one packaging, across the whole catalogue, always.
Structure. Model, variants, packagings; attributes defined per category; one generated reference per level. Identifiers. A barcode belongs to exactly one packaging across the whole catalogue, and the constraint is in the database, not in an instruction; old internal codes, HU5, HUILE5L, become aliases of the variant, so that search, old invoices and sellers' habits keep finding the product; the supplier's reference is kept for orders and for importing their files, described in the import guide. Prices. Grids per packaging, retail, wholesale, promotion; every price has a start date and an end date, and the till of the checkout guide and the portal of the B2B ordering guide read the same grid.
Content. Photos live at the model level, or at the variant when the colour changes; variants inherit the model's, and a photo is never copied twelve times. Descriptions are bilingual and indexed by the search described in the search guide. Record life. Status draft, active, end of life, archived; at end of life, the remainder is sold but no longer reordered; archived, the record stays readable from old invoices but no longer appears in sales. Every change is logged, who, when, old value, new value, and a record is not deleted.
The take-over: twelve lines become one record
The figure shows what twelve lines of an old file for the same oil become. Nothing is lost, and one line is refused.
The take-over starts with matching: lines whose label, barcode or price look alike are proposed as the same product, and the manager confirms or separates, screen by screen, not in bulk. The different internal codes become aliases of the variant; the scanned EAN is kept on the unit packaging; the Arabic label is kept on the model; the two “case” lines become one packaging with factor 4; the promo price goes into the grid, with its dates. The zero-price line is not merged silently: it is refused and raised to the manager with its reason, like any line the dry run of the import guide cannot place.
The stock of the twelve lines is added up in base units at take-over time, once, and recorded as a dated adjustment movement in the ledger of the stock guide; it will never again be split across duplicates. The same key-and-merge principle serves the customer file in the single customer guide. Lines, codes and prices in the figure are a constructed example.
«Old codes are not lost: they become aliases, and there is only one stock and one price grid behind.»
Six real situations, and what the application does
Every row of the matrix is a complaint heard at a wholesaler, a shop or a pharmacy, and the answer is the structure, not one more instruction.
The same product under three codes: one variant, three aliases; a single stock and a single price; search finds by any alias. The case sold as a unit: the case has its own barcode, factor and price; the scan cannot pick the wrong level, and stock moves 4 units. The new size created on the fly: the variant is born from an attribute value, the reference is generated, and a value already taken is refused. The price typed on the invoice: the line reads the packaging's dated grid, and an off-grid price requires an approved discount following the quote and invoice guide.
The photo missing on the site: the photo lives at the model, variants inherit it, and a list of records without photo comes out every Monday in the manager's dashboard. The discontinued product still sold: end-of-life status lets the remainder be sold without reorder, then archiving removes the record from sales without breaking old invoices. Expiry dates and lots, which concern pharmacies and food, are added at the stock movement level, not the record, as in the pharmacy guide.
Taking over a catalogue in 2027, in weeks
Seven weeks, two of them for the take-over, because it decides whether the catalogue will be clean or will reproduce the file.
- What the manager sees: one product, one record, and under it its variants and packagings; a scan that always lands on the right level; prices that come from a dated grid.
- What the seller can no longer do: create a product without a category, invent a code, type a price on the line, delete a record.
- What is measured: duplicates detected, unknown codes at scan, records without photo or price, lines refused at take-over and their fate.
Week 1, categories and attributes: with the manager and the storekeeper, the list of categories, each one's required and variant attributes, the base units; no code, and it is the week that avoids the most rework. Week 2, structure: model, variant, packaging, generated references, uniqueness constraint on barcodes, aliases. Weeks 3 and 4, take-over: matching of old lines, dry run, merges proposed screen by screen, refused lines to the manager, stock added up and recorded as an adjustment.
Week 5, prices and content: grids per packaging, photos at the model, bilingual descriptions, list of incomplete records. Week 6, sales and stock: the till and orders read the scanned packaging, movements are made in base units, the end-of-life status is respected everywhere, including offline following the offline guide. Week 7, measurement: duplicates detected per week, unknown codes at scan, records without photo, Monday review. Records, like everything else, are exposed to other software through the integration guide.
- Why three levels and not one line per product?
- Because three different things need to live in three places: the description and photos once, the stock where the attribute changes, the barcode and price where you scan and sell. One line per product forces you to copy the description twelve times, split the stock and invent a product for every case.
- Is a case a separate product?
- No. It is a packaging of the same variant, with its own barcode, a factor to the base unit, 4 for instance, and its own price. Scanning a case moves 4 units in or out of the same stock.
- What happens to our old codes?
- They become aliases of the variant. Search, old invoices and sellers' habits keep finding them, but there is only one stock and one price grid behind. An alias cannot point to two records.
- And attributes? Who defines them?
- The category, during the first week, with the manager and the storekeeper: required attributes and the variant attribute. A seller cannot create a variant outside the planned values; if a value is missing, it is added to the category, not on a line.
- How do you take over a ten-year-old file?
- Through matching proposed then confirmed screen by screen, a dry run that changes nothing, merges applied with old codes as aliases, refused lines raised to the manager in writing, and stock added up once in base units. Two weeks in the typical calendar.
- Barcodes, do we make them up?
- For retail products, you scan the manufacturer's, which is unique. For house products or products without a code, the application generates an internal one, unique across the catalogue. Public GTINs come in 8, 12, 13 and 14 digits; 14-digit codes serve cases and pallets, not the till, according to the system's public documentation.
- How long to set this up?
- Seven weeks in the typical calendar, the first without code and two for the take-over. A catalogue of a few hundred references with few variants takes less; a wholesaler with thousands of lines and multiple packagings takes all seven.