Products

Manage the items your food bank offers to recipients, including pricing, images, categories, barcodes, bundles, and stock levels.

Overview

Products are the core of your food bank catalogue. Each product represents an item that recipients can add to their order. You manage products under Catalogue > Products in the sidebar.

Each food bank has its own catalogue, so you only see your own products. Products have a name, a code, a main category, pricing in points, a maximum order quantity, one or more barcodes, and one or more variants. Most food bank products are "simple" products with a single variant, but you can also create bundle products that group several items together.

The product grid is also the inventory view. Alongside name and pricing it can show on-hand stock, reserved (on-hold) quantities, on-checkout quantities, predicted stockout dates, and barcodes — every inventory column is opt-in from the Columns dropdown above the grid. Receiving stock, running a verbal AI stocktake, and importing a catalogue are separate pages reached from the Catalogue section of the sidebar.

Key Concepts

Catalogue

• Simple product — A standalone item with a single variant. This is the most common product type for food banks.
• Bundle product — A product that groups several other products together. Each bundle item has a minimum and maximum quantity, and optional extra points or currency costs. Bundles let you offer composite parcels such as "Breakfast Pack" containing cereal, milk, and toast.
• Product variant — The purchasable unit of a product. A simple product has exactly one variant. The variant holds the code, price, inventory tracking settings, and stock levels.
• Points — The cost of a product expressed in points rather than currency. Recipients allocate points from their allowance when placing an order.
• Max quantity — The maximum number of units a recipient can add to a single order.
• Product code — A unique identifier for the product, often prefixed with a supermarket code when imported from an external catalogue.
• Category — The category tree that organises products for browsing. Every product has a main category and can belong to additional categories.
• Soft delete — When a product that has been ordered is deleted, it is soft-deleted (hidden) rather than permanently removed, preserving order history.

Inventory

• On hand — The total physical quantity of a variant currently in your warehouse. This is the number you count on the shelf.
• On hold (reserved) — The quantity reserved by orders that have been placed but not yet fulfilled. These units are committed to specific orders.
• On checkout — The quantity sitting in active shopping carts that have not yet completed checkout. Informational; helps explain discrepancies between on-hand and available stock.
• Available stock — Calculated as on-hand minus on-hold minus on-checkout. This is the quantity actually available for new orders.
• Tracked variant — A variant where inventory tracking is enabled. Only tracked variants have on-hand and on-hold values. Untracked variants are treated as always in stock.
• Predicted stockout — A date calculated from the daily sales rate and current available stock. Colour-coded badges indicate urgency: red for out-of-stock or fewer than 7 days, amber for 7 to 14 days, blue for more than 14 days.
• Daily sales rate — The average number of units sold per day, used to calculate the predicted stockout date.
• Barcode — A scannable code (EAN, UPC, or internal) linked to a product. A product can have multiple barcodes. Each barcode can optionally record a quantity-per-box value for bulk receiving.
• Quantity per box — An optional value on a barcode record that records how many individual units are in a box with that barcode. When scanning a box barcode, the system can multiply by this value.

How It Works

Product lifecycle

1. An admin creates a product (simple or bundle) and assigns it a name, code, category, points value, price, and maximum quantity.
2. The product is enabled or disabled. Disabled products do not appear in the shop.
3. Recipients browse enabled products, add them to their cart, and place orders.
4. When a product is deleted, the system checks whether it has any associated order items. If it does, the product is soft-deleted (marked with a deleted_at timestamp) so that historical orders remain intact. If it has never been ordered, it is permanently removed.

Inventory lifecycle

Stock levels change automatically through the order workflow:

1. Order placed — When a recipient completes checkout, the ordered quantity is added to the variant's on-hold count. On-hand does not change yet.
2. Order fulfilled — When an admin marks an order as fulfilled, the sell-inventory listener runs. It reduces both on-hold and on-hand by the ordered quantity. This represents the stock physically leaving the warehouse.
3. Order cancelled — When an order is cancelled, the give-back-inventory listener runs. It reduces on-hold by the ordered quantity, effectively releasing the reserved stock. On-hand is not changed because the stock was never physically removed.

Tracked versus untracked variants

Each product variant has a Tracked toggle on the product edit page (in the Inventory section). When tracked is enabled:

• The variant has on-hand and on-hold values.
• The system enforces stock availability — recipients cannot order more than the available quantity.
• The variant's stock columns are populated on the Products grid.

When tracked is disabled:

• The variant is treated as always in stock.
• No stock checks are performed during checkout.
• Its stock columns on the grid are blank.

You can change a variant from untracked to tracked at any time by editing the product and enabling the toggle, then setting the initial on-hand quantity.

Product grid

The product grid at Catalogue > Products lists every product in your catalogue. The available columns are:

| Column | Description | Default | |--------|-------------|---------| | Image | Thumbnail of the first product image | Visible | | Name | Product name (sortable) | Visible | | Main Category | The primary category (sortable) | Visible | | Enabled | Whether the product is visible in the shop | Visible | | Points | Points value for the default variant | Visible (channel-dependent) | | Price | Currency price for the default variant | Visible (channel-dependent) | | Cost | Internal cost per unit | Visible (channel-dependent) | | Max Qty | Maximum quantity per order | Visible | | Add Boxes | Quick "+1 box" action (channel-dependent) | Hidden | | Add Stock | Quick "+/- on-hand" action | Hidden | | On Hand | Current physical stock | Hidden | | In Reserve | Quantity reserved by placed orders | Hidden | | On Checkout | Quantity in active shopping carts | Hidden | | Stock Remaining | Available = on-hand − on-hold − on-checkout | Hidden | | Predicted Stockout | Estimated date stock will run out, with daily sales rate | Hidden | | Barcode | Comma-separated list of linked barcodes | Hidden | | Position | Drag-handle for manual ordering | Visible | | Actions | Edit / view / delete / variants | Visible |

Each row also has action buttons: reorder (drag handle), view details, edit, delete, and a variants sub-menu.

Showing and hiding columns

The Columns dropdown above the grid lets you tick exactly which columns you want visible. The choice is per-browser (stored in localStorage), so each admin can tune their own view without affecting anyone else. Useful patterns:

• Tick On Hand, In Reserve, On Checkout, and Predicted Stockout to turn the Products grid into a stock-overview report.
• Tick Barcode when associating barcodes with products in bulk.
• Tick Add Stock to expose an inline "+/- on-hand" control for fast adjustments without leaving the grid.
• Click Reset at the bottom of the dropdown to return to the defaults.

Some columns have dependencies — toggling certain stock columns on automatically turns on the supporting columns they depend on; toggling them off again puts everything back.

Reserved orders drill-down

When the In Reserve column is visible, clicking a green Reserved badge on a row opens a popup listing the specific orders holding that stock. Each entry shows the order number, customer name, quantity reserved, and when the order was placed. This helps you understand why stock is on hold.

Filtering

Expand the Filters panel at the top of the grid to narrow results by:

• Search — matches against product code and name (contains search).
• Enabled — filter to enabled or disabled products only.
• Category — filter by any category in the category tree.
• Main category — filter by the primary category only.
• Tags — filter by product tags.

Drag-and-drop reordering

Each product row has a drag handle icon. Drag rows to reorder products within their main category. The new positions are saved automatically via an AJAX call.

Common Tasks

Create a simple product

1. Go to Catalogue > Products.
2. Click + Create. If your food bank has bundles enabled, a dropdown appears — choose Simple product.
3. Fill in the Name and Slug fields.
4. Optionally add a Short description and Description.
5. In the General section, enter a unique Code. Set the Enabled toggle.
6. In the Inventory section, set whether the variant is Tracked. If tracked, enter the initial On hand quantity.
7. In the Categories section, select the Main category and any additional categories.
8. In the Attributes section, set any product attributes.
9. In the Media section, upload one or more product images.
10. In the Pricing section, set the Points value and optionally a Price in currency. Set the Max quantity per order.
11. Click Create.

Edit a product

1. Go to Catalogue > Products and click the edit (pencil) icon on the product row.
2. The edit page shows a side navigation with sections: Name, General, Inventory, Categories, Attributes, Media, and Pricing.
3. Make your changes and click Update.

The edit page also provides buttons to Show the product detail page, View in store (opens the shop-facing product page), and manage Variants.

Create a bundle product

1. Go to Catalogue > Products and click the + Create dropdown, then choose Bundle product.
2. Fill in the product details as for a simple product.
3. In the Bundle section, add bundle items. For each item:
   • Select the product to include.
   • Set the Quantity (minimum units included).
   • Set the Max quantity multiplier (how many times the base quantity the recipient may request).
   • Optionally set Points value and Currency value for removable items — items with a points or currency value can be removed by the recipient at checkout.
   • Optionally set Extra points and Extra currency for adding more than the base quantity.
4. Click Create.

Check stock levels

1. Go to Catalogue > Products.
2. Click the Columns dropdown above the grid and tick On Hand, In Reserve, On Checkout, Stock Remaining, and Predicted Stockout.
3. Sort by Predicted Stockout to put items running low at the top, or use the filters to narrow to a single category.
4. Red on-hand badges indicate zero stock. Amber or red stockout badges indicate items running low.

Adjust stock manually

1. Go to Catalogue > Products and click the edit (pencil) icon on the product.
2. Scroll to the Inventory section (or click Inventory in the side navigation).
3. Change the On hand value to the correct count.
4. Click Update.

For fast inline adjustments without leaving the grid, tick Add Stock in the Columns dropdown — each row then exposes a +/- control that updates on-hand directly.

For bulk adjustments use the barcode scanner or the verbal AI stocktake described below.

Receive goods with the barcode scanner

1. Open Catalogue > Barcode Scanner in the sidebar (or navigate to /admin/scan).
2. The scanner page shows a form where you can enter barcode and quantity pairs.
3. For each item received:
   • Enter or scan the Barcode.
   • Select the Product if the barcode is not yet linked to a product.
   • Enter the Quantity received.
   • Optionally enter Qty per box if scanning box barcodes.
4. Choose the mode: Add quantities (default) adds the scanned quantity to the current on-hand value. Remove quantities subtracts from on-hand.
5. Click Save.
6. The system processes each row:
   • If the barcode is new, it creates a barcode record and links it to the selected product.
   • If the barcode already exists for the selected product, it updates inventory directly.
   • If the barcode belongs to a different product, an error is shown with an option to unlink the barcode from the other product.
   • If the product variant is not tracked, a warning is shown and inventory is not updated.
7. Success and error messages appear as flash notifications summarising what was processed.

Failed items remain in the form so you can correct and resubmit them.

Run a verbal AI stocktake

1. Open Catalogue > Verbal AI Stocktake in the sidebar (or navigate to /admin/verbal-ai-stocktake).
2. Record an audio file listing your stock counts (for example, "Honey five, Reduced Cream two, Cheese Block nine").
3. Upload the audio file. The system transcribes it using AI.
4. Review the transcript and click to process it. The AI parses item names and quantities from the transcript.
5. Review the parsed results. For each item:
   • The system attempts to match the spoken name to a product in your catalogue.
   • Use the Matched product dropdown to correct any mismatches.
   • Verify the Quantity.
6. Click Save to update the on-hand values for all matched products.
7. Optionally download a CSV of the stocktake results.

The stocktake sets the on-hand value directly (it does not add to the existing count). Only tracked variants are updated. Untracked variants are skipped with a warning.

Manage product barcodes

Barcodes are displayed in the Barcodes section of the product edit page when the product has associated barcodes. Each barcode card shows:

• The barcode string.
• An editable Qty per box field, which records how many individual units are in a box with that barcode.

Most barcodes are created through the Barcode Scanner rather than directly on the product edit form. Tick the Barcode column on the Products grid to see at a glance which products are linked to which barcodes.

View which orders are holding stock

1. Go to Catalogue > Products and tick the In Reserve column in the Columns dropdown.
2. Click the green Reserved badge on a product row.
3. A popup lists the orders reserving that stock, including order number, customer name, quantity, and order date.

Bulk delete products

1. Go to Catalogue > Products.
2. Select the checkboxes on the left of each product you want to remove.
3. Click the red Delete button above the grid.
4. Products with existing orders are soft-deleted (hidden but preserved for historical records). Products with no orders are permanently removed.

Import products from an external catalogue

1. Open Catalogue > Import Products in the sidebar (or navigate to /admin/catalogue-import).
2. Use the Supermarket and Category dropdowns to browse available products from the external catalogue.
3. Use the Search field to find specific items.
4. For each product you want to import, configure:
   • Points — the points value.
   • Max quantity — per-order limit.
   • Stock on hand — initial inventory.
   • Main category — the primary category in your catalogue.
   • Other category — an optional secondary category.
   • Box quantity and Per box — for bulk receiving.
   • Name and Price — override the defaults from the external source if needed.
5. Select the products and click Import.
6. The system creates the products, variants, pricing, and images automatically. A success or failure message confirms the result.

Products that have already been imported are marked in the catalogue view so you can filter to see only imported or only new items.

Manage product images

1. Open the product edit page.
2. Scroll to the Media section (or click Media in the side navigation).
3. Click Add image to upload a new image.
4. Existing images are shown as thumbnails that you can reorder or remove.

Manage product categories

1. Open the product edit page.
2. Scroll to the Categories section.
3. Select a Main category from the category tree.
4. Optionally add the product to additional categories.

Manage product attributes

1. Open the product edit page.
2. Scroll to the Attributes section.
3. Set values for each attribute defined for your food bank.

FAQ

Q: What does "On hand" versus "In reserve" mean?

A: On hand is the total physical stock you have. In reserve (on hold) is the portion of that stock committed to orders that have been placed but not yet fulfilled. Available stock is on-hand minus in-reserve minus on-checkout.

Q: Why does my on-hand count seem wrong after fulfilling orders?

A: When an order is fulfilled, the system reduces both on-hand and on-hold by the order quantity. If on-hold was already out of sync (for example, due to a manual adjustment), you may see an error flash message. Check the order history and adjust on-hand manually if needed.

Q: What happens to stock when an order is cancelled?

A: The reserved (on-hold) quantity is released. On-hand does not change because the physical stock was never removed from the warehouse. The items become available for new orders.

Q: Can I use the barcode scanner to reduce stock?

A: Yes. Toggle the mode to Remove quantities before saving. The scanned quantities will be subtracted from the current on-hand values instead of added.

Q: What if I scan a barcode that belongs to a different product?

A: The system detects the conflict and shows an error message identifying the product the barcode is currently linked to. You are given the option to unlink the barcode from the other product so you can reassign it.

Q: How is the predicted stockout date calculated?

A: The system tracks a daily sales rate for each product. It divides the current available stock (on-hand minus on-hold minus on-checkout) by the daily sales rate to estimate the number of days until stockout. The result is displayed as a date with colour-coded urgency.

Q: What happens if I make a variant untracked?

A: The variant is treated as always in stock. Its stock columns on the Products grid will be empty, and the system does not enforce stock checks during checkout. Existing on-hand and on-hold values are preserved but ignored.

Q: How does the verbal AI stocktake work?

A: You record an audio file speaking your stock counts aloud. The system uses AI to transcribe the audio, then uses AI again to parse product names and quantities from the transcript. It matches spoken names to your product catalogue and lets you review and correct matches before saving. The stocktake sets on-hand values directly rather than adding to them.

Q: What happens when I delete a product that has been ordered?

A: The product is soft-deleted. It is hidden from the catalogue and the product grid, but it remains in the database so that historical order records stay intact. The product receives a deleted_at timestamp.

Q: What is the difference between points and price?

A: Points are the primary cost mechanism for food bank recipients. Each recipient has a points allocation, and products cost a certain number of points. Price in currency is an optional secondary field used for donation tracking or display purposes.

Q: Can I have multiple barcodes for the same product?

A: Yes. A product can have any number of barcodes. This is useful when the same item comes from different suppliers with different packaging or barcode formats, or when you want to track both individual-item and box-level barcodes.

Q: How does the catalogue import work?

A: The import system connects to an external product database (sourced from supermarket catalogues). You browse that database, select the products you want, configure their pricing and categories for your food bank, and import them. The system creates the product, variant, pricing, category assignments, and downloads the product image automatically.

Q: What does the max quantity multiplier on bundle items do?

A: It controls how many times the base quantity a recipient can request. For example, if a bundle item has quantity 1 and max quantity multiplier 3, the recipient can request up to 3 units of that item in the bundle.

Q: How do I reorder products in a category?

A: On the product grid, use the drag handle (arrows icon) on each row to drag products into the desired order. The positions are saved automatically. Products are ordered within their main category.

Q: How do I show extra columns on the Products grid?

A: Click the Columns dropdown above the grid and tick the columns you want. The choice is stored per-browser, so each admin can tailor the grid to their workflow. Hit Reset to return to the defaults.