Adding an inventory item

Quick reference

• Open /inventory/new from the + New Item button on the inventory page.
• Fill the form top-down — basic info, pricing, metal and stone, certificates, stock and location, consignment (only if the piece is on consignment), and finally photos.
• The Auto-categorize button uses AI to fill metal type, stone type, and category from the piece name. Verify what it picked before saving.
• If retail price is below cost, you get a confirm prompt (loss-per-unit). Cancel and fix the price, or confirm to save anyway.
• Multi-location stores must pick a specific location in the header pill before submitting — “All Locations” blocks the save and a banner explains why.
• Save lands you on the item's detail page at /inventory/<id>. Edit anything later from Edit on that page.

Walkthrough

1. Open the new-item form

Click + New Item from the top of /inventory, or visit /inventory/new directly. The form takes the full page and scrolls; there's no modal version, by design — you have enough fields to fill that a dedicated page reads better.

If you're on a multi-location tenant and your header location pill reads All Locations, the page renders a red banner up top: “Please select a specific location before creating this record.” The Add Item button stays disabled until you switch to a specific location. Switch from the pill in the header and the banner clears in place.

2. Step 01 — Basic info

Name first (e.g. “18ct Yellow Gold Solitaire Ring, 0.50ct Diamond”). Pick an Item type: Finished Piece, Loose Stone, Finding, Raw Material, or Packaging. Pick a Jewellery type (Ring, Necklace, Bracelet, Earring, Pendant, Bangle, Brooch, Other) — only relevant on Finished Piece.

The Category dropdown is your tenant's own categories — Engagement, Wedding, Vintage, etc. Click + New Category beside it to add one on the fly.

Tap the Auto-categorize sparkle button at the top of the section to call the AI categorisation helper — it reads the name (plus description if you've filled it) and fills metal type, metal colour, metal purity, stone type, stone colour, and stone clarity. The output lands directly in the metal and stone fields below. Check the values before saving; the AI is well-calibrated on common pieces and less so on unusual ones.

3. Step 02 — Pricing

Three fields: Cost price, Wholesale price, Retail price. Cost is what you paid (visible only to users with the view_cost_price permission). Wholesale is what you charge trade customers. Retail is what you charge walk-in customers; this is the one the POS uses by default.

If you set retail below cost, the form pops a confirm: “Retail price is below cost. You'll lose $X per unit sold. Continue anyway?” Cancel and fix the prices, or confirm if you're intentionally clearing stock at a loss.

4. Step 03 — Metal & stone

Metal type (Gold, Silver, Platinum, Palladium, Titanium, Steel, Other), colour (Yellow, White, Rose, Two-tone, N/A), purity (9ct, 14ct, 18ct, 22ct, 24ct, 925, 950, 999, Other), and weight in grams. Metal form captures whether the metal is finished (a ring) or raw (a sheet, a wire) — most stores leave it default.

For stones: type (Diamond, Sapphire, Ruby, Emerald, etc.), carat, colour, clarity (FL through I3 for diamonds; the same picker applies for coloured stones, where the convention is looser). If a piece has secondary stones — pavé, halo, accent gems — click + Add secondary stone to capture each separately.

5. Step 04 — Certificates & documents

Optional. Certificate number, Grading lab (GIA, IGI, AGS, in-house, other), Grade (free text — pick whatever the cert says), and Report URL — paste the link to the lab's online verification page if it has one. None of these are required, but for certified diamonds and high-value coloured stones they're what makes the piece traceable from the price tag through to the sale.

If you have a PDF of the cert, the photos section below also accepts non-image attachments — drop the PDF in alongside the photos of the piece. The Verify Passport surface (see /docs/verify-passport/issue-passport) reads from the same fields, so anything you fill here flows straight through if you later issue a digital passport.

6. Step 06 — Stock & location

Initial quantity (default 0; for a finished one-of-a-kind piece set this to 1, for a finding you buy in packs of 50 set this to 50). Low-stock threshold (default 1) — when quantity drops to or below this number, the item shows in the low-stock KPI and gets a coloured pill in the list.

Track quantity toggle: on by default. Off means quantity-style accounting doesn't apply — useful for services or made-to-order items where there's no physical pack to count. See Serialized one-of-a-kind vs variant items for when to turn it off.

Stock location (display cabinet, safe, workshop, warehouse, on consignment) — this is a within-store position label, not the multi-location pin. The location pin is set automatically from the header pill. Supplier name, Supplier SKU, and Supplier invoice ref are optional traceability fields; the invoice scanner (see receive a supplier shipment) fills these automatically when you intake stock that way.

7. Step 07 — Consignment (optional)

Only relevant if the piece is on consignment from a vendor. Flip status to Consignment in step 01 and the section unlocks. Fields: Consignor name and contact (who you owe the money back to), Start and End dates of the consignment window, and Commission % — the cut you take on a sale.

When status is consignment, the item's stock number is assigned with prefix C instead of S. The full memo and consignment workflow is documented at /docs/memo-and-consignment/overview (a later batch).

8. Photos and save

Drop photos into the image-upload block at the bottom. The first photo becomes the primary image (shown on the inventory list, the POS, and your storefront if you've listed the piece on the web). You can drag photos to reorder; the leftmost is primary. The photos sit in a private storage bucket and render via signed URLs that rotate every seven days.

Click Add Item up top or at the bottom of the form. The submit button shows Saving… while the row inserts; on success you're redirected to the item's detail page at /inventory/<id>. From there you can print a tag, adjust stock, or edit any field that needs fixing.

Common questions

Troubleshooting