Item variants and families
Use variants when one product or material has several real sellable or stockable forms. The family groups the shared card details, while each variant remains a concrete item row with its own SKU, price, stock, lots, and ledger history.
The family shape
Section titled “The family shape”1
The family card
The family card holds the shared identity: name, item type, category, description, stocking unit, lot-tracking mode, and shared purchasing setup. Editing these fields on the card mirrors the change to every variant item.
2
Options and values
Options are the axes of variation — for example, Bag size with values 0.5 ft3, 1 ft3, 2 ft3. Values are ordered and unique within their option. The card UI supports up to 3 option axes.
3
Variant items
Each option-value combination produces one stockable item row with its own SKU, price, stock, lots, and ledger history. Every combination in the family must be unique.
| Variant | SKU | Price | On hand |
|---|---|---|---|
| Premium Potting Mix / 0.5 ft3 | PPM-05 | $6.50 | 220 |
| Premium Potting Mix / 1 ft3 | PPM-1 | $11.00 | 140 |
| Premium Potting Mix / 2 ft3 | PPM-2 | $19.50 | 85 |
| Rule | Detail |
|---|---|
| Shared fields are edited on the family card and mirror to all variants. | Name, item type, category, unit, lot-tracking mode, and purchasing setup are managed once. |
| Per-variant fields are independent. | SKU, barcodes, supplier code, lead time, MOQ, prices, stock quantity, and sellability belong to each concrete variant item. |
| Each option-value combination must be unique. | The API exposes duplicate-combination warnings; filled duplicate SKUs are hard-blocked. |
| The card UI supports up to 3 option axes. | Each axis holds an ordered list of values. At least one active variant must remain on the card. |
Pricing and downstream workflows
Section titled “Pricing and downstream workflows”A sales pricing schedule can target a variant option and value, such as every 2 ft3 bag. Downstream workflows still use the concrete item row: purchase orders, sales lines, lots, stocktakes, and ledger events move stock on the variant, not on the family record.