Docs/Products/Product Items

Product Items

Product version: 1.0.0+1 Last updated: 2026-10-02 Audience: Tenant Owners, Employees, and users with product:read

A. What Are Product Items?

A Product Item (SKU) is the purchasable unit under a product. The product is the catalog container (e.g., "T-Shirt"); each item is a specific sellable line (e.g., "T-Shirt, Size M, Color Red").

Key characteristics:

  • Each item has its own price, SKU, barcode, description, unit of measure, weight/dimensions, variation options, and images.
  • A product can have one item (single SKU) or many (variants).
  • Variation options are linked via Product Item Configuration.
  • Physical quantity is tracked in the Inventory service as an inventory item linked to this product item. See Stock Items.

B. Viewing Items for a Product

  1. Open Product Catalog > Products and select a product.
  2. Use the Items section on product detail, or open Items for that product.
  3. The table lists SKUs for the product.

Typical columns

Column Description
SKU Stock-keeping unit
Barcode Scannable identifier
Price Selling price
Variations Option summary (e.g., "Red / M")
Updated Last modification time

Stock on hand is not shown here — open inventory for quantities.

C. Creating a New Item

Required permission: product:create

  1. Open the parent product.
  2. Tap Add Item.
  3. Fill the item form:
Field Required Description
Price Yes Selling price (≥ 0)
SKU Yes Unique code for this line in your organization. Pre-filled with an editable SKU-YYYYMMDD-XXXXXX code.
Barcode Yes Unique in your organization. Pre-filled with an editable BAR-YYYYMMDD-XXXXXX code; replace it with a UPC/EAN if you have one (not inventory PL-… placards).
Unit of Measure No From the UoM catalog
Description No Item-specific text
Weight / Dimensions No Weight (g) and length / width / height (cm)
  1. Save.

On create, the form stays open after the first successful save so you can manage Variants and Images panels (unlocked after the item exists). Leaving the form returns true to the parent when a create/update succeeded so lists can refresh.

You can also create the first SKUs inside the Product Setup Wizard (Items step). See Products — Setup Wizard.

D. Editing an Item

Required permission: product:update

  1. Open the item detail page (from the product’s items table).
  2. Tap Edit.
  3. Update price, SKU, barcode, UoM, description, weight, or dimensions.
  4. Save. Variation options and images are managed on the detail panels (or on the form after the item is saved).

E. Item Detail View (unified page)

The item detail page is the single hub for a SKU. Legacy routes that opened separate “configurations” or “images” screens now open this page focused on the matching section.

Hero

  • Primary image, product name, SKU label, price, SKU/barcode
  • Create inventory item — opens the inventory stock-item form with this catalog product and item prefilled (requires inventory create permission)
  • Edit, Delete (permission-dependent)

Identity and dimensions

Overview of commercial fields plus weight and dimensions when set.

Variants panel

  • Lists linked variation options
  • Add opens a dialog to attach options (category-scoped variations first when applicable)
  • Remove options when permitted
  • Shortcut to the tenant Variations list

Images panel

  • Gallery for this SKU: add from media library/upload, set primary, reorder, edit metadata, delete
  • Permission-gated create/update/delete

Danger zone

  • Delete (product:delete) marks the item Deleted together with its linked inventory items. The page stays available with a Deleted banner.
  • Restore (product:restore) on a deleted item brings it back with its images, variation options, and linked inventory items.
  • Delete permanently on an already-deleted item removes it immediately and cannot be undone. Only the organization owner can do this.
  • Deleted items show how many days remain before they are removed automatically.

F. Item Configurations (Variation Combinations)

ProductItemConfiguration links an item to variation options.

  1. Define Variations and Options (tenant-wide or category-scoped).
  2. On the item, add options in the Variants panel (or during setup / form after save).
  3. Each selected option becomes a configuration row for that item.
  4. Combinations should uniquely identify the variant within the product.

Example

Product Item SKU Color Size
T-Shirt TSH-RED-M Red M
T-Shirt TSH-RED-L Red L
T-Shirt TSH-BLU-M Blue M

G. Images Panel

Images are attached at the product item level so each variant can have its own photos.

  1. Open item detail → Images.
  2. Add images via the media picker.
  3. Set primary, reorder, edit alt/caption, or delete as needed.

Required permission: product:image:create / product:image:update / product:image:delete (viewing needs product:image:read).

H. Product Service vs. Inventory Service

Concern Owned by Holds
Product Item Product Price, SKU, barcode, UoM, dims, variation options, images
Inventory Item Inventory Quantity on hand/reserved/incoming, cost, batch/lot/serial, bin placement

How they connect

  1. Create the product item in the catalog.
  2. From item detail, tap Create inventory item (or use Inventory Setup / stock forms with catalog pickers).
  3. Inventory stores product_item_id and stock fields; the UI can show catalog name, SKU, and images from the product item.

Barcode scanning

Inventory barcode scan looks up stock (and related catalog identifiers). Keep barcodes unique per your organization’s rules on product items.

Previous: Products Next: Brands

Related: Overview · Categories · Variations · Variation Options

See also: Stock Items · Tenant Owner Manual · Employee Manual