Reference → Inventory — Reference

Inventory — Reference

The Inventory surface is the stock-tracking plane for every SGEN ecommerce site. It owns the per-SKU stock record, the multi-location breakdown that backs it, the low-stock alert configuration, the reorder-point logic, the manual-adjustment audit ledger, and the cascade hooks that fire when orders capture stock or refunds restock it. Anything that represents a quantity-on-hand for a sellable SKU traces back to a record managed here.

This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or reconciling against an external warehouse system. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.

Overview

Inventory lives under the Inventory module in SG-Admin, inside the ecommerce sub-tree. The module renders four primary views — the SKU inventory list, the per-SKU detail page (location breakdown, alert config, adjustment history), the location management view, and the adjustment composer — and exposes a small set of write operations for adjust, transfer, set reorder point, set alert threshold, and audit-export.

The module is paired by convention with the Products surface but is intentionally distinct. A product is the catalog record (description, price, variants, images); a SKU on that product carries an inventory record per location. One product can produce many SKUs (one per variant); one SKU can carry stock across many locations (warehouse, retail floor, drop-ship partner, virtual reservation).

A second surface — adjustment history — lives inside each inventory record. Every movement — order capture, refund restock, manual increase, manual decrease, transfer in, transfer out, audit reconciliation — writes an append-only entry. The history is the source of truth for reconciliation; the running quantity-on-hand is computed from it.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Ecommerce → Inventory
URL prefix: /sg-admin/inventory/
View templates: application/views/Admin/Inventory/

The module surface is broad enough to support both single-location simple-store inventory (one SKU, one quantity) and multi-location operations (per-location stock, transfers between locations, location-aware fulfillment routing). Adjacent surfaces (Products, Orders, Refunds, Settings → Locations) shape what an inventory record represents and how it cascades; this page covers only the inventory record and the operations that act on it.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Ecommerce → Inventory [Adjust] [Export] │├──────────────────────────────────────────────────────────────────────┤│ SKU Product Locations On hand Status ││ ───────────── ──────────────────── ───────── ─────── ───────────││ TSHIRT-BLK-M Classic Tee (M, Black) 3 47 OK ││ TSHIRT-BLK-L Classic Tee (L, Black) 3 12 Low ││ TSHIRT-WHT-S Classic Tee (S, White) 2 0 Out ││ MUG-LOGO Logo Mug 1 284 OK ││ STICKER-PK-3 Sticker Pack (3-up) 2 8 Reorder ││ ││ Filter: [Location ▼] [Status ▼] [Low stock] Bulk: [Set threshold] │└──────────────────────────────────────────────────────────────────────┘

Actions

The Inventory surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.

List and search

Returns the inventory records visible to the current operator, paginated, with SKU, product name, location count, on-hand total, and status columns. Supports column sort, free-text filter on SKU and product name, location filter, status filter (OK / Low / Out / Reorder), and a "below threshold" filter. Driven by the data-table contract used across SG-Admin modules.

Engineering note: status is computed at read time from on_hand versus alert_threshold and reorder_point. The fields themselves are not stored on the inventory record — they're derived from the running quantity and the configured thresholds. Changing a threshold causes status to re-evaluate without rewriting any history.

View SKU detail

Loads the full inventory record into a read-mostly detail page — per-location breakdown, alert and reorder configuration, recent adjustment history, and the linked product / variant. Editable fields are gated behind separate actions; the detail page itself does not write.

Adjust stock

Opens the adjustment composer against a named SKU and location. Operator picks adjustment type (increase / decrease / set-absolute), enters quantity and reason from the configured taxonomy, and optionally adds an operator note. On submit, the surface validates the resulting on-hand against zero (no negative inventory unless the override capability is held), writes an append-only entry to the adjustment ledger, recomputes the running quantity, and emits any threshold-crossing alerts.

Engineering note: increases and decreases are delta entries; set-absolute is a calibration entry that records the prior quantity, the new quantity, and the implied delta. Reconciliation queries can replay deltas to verify the running quantity; set-absolute entries are calibration points that reset the chain.

Transfer between locations

A focused write path. Accepts a source location, a destination location, and a quantity. The surface writes paired transfer-out and transfer-in entries to the adjustment ledger, decrements the source on-hand, and increments the destination on-hand. Transfers are atomic — both entries succeed together or both fail.

Set reorder point

Updates the reorder-point threshold on a SKU's record (optionally per-location). When the on-hand quantity crosses below the reorder point, the SKU surfaces in the "Reorder" status filter and emits a reorder alert. Setting a reorder point does not place an order; it surfaces the signal to operators or to an external integration.

Set alert threshold

Updates the low-stock alert threshold on a SKU's record (optionally per-location). When the on-hand quantity crosses below the alert threshold, the SKU surfaces in the "Low" status filter and the configured alert recipients receive a notification. Distinct from the reorder point so that operators can model both a soft warning and a harder reorder trigger.

Snapshot audit

Generates a point-in-time snapshot of all inventory records visible to the current operator. The snapshot captures SKU, per-location on-hand, alert and reorder configuration, and the audit timestamp. Snapshots persist as separate audit records, queryable via the audit-history view. Used for periodic stock-take reconciliation and for external accounting reports.

Set tracking mode

Toggles inventory tracking on or off for a given SKU. Tracked SKUs maintain a quantity-on-hand and surface in the inventory list; untracked SKUs (typically digital goods or services) skip the inventory plane entirely and are always available for purchase. Switching from untracked to tracked seeds the SKU at zero; switching from tracked to untracked retains the historical adjustment ledger but stops new entries.

Export

Generates a flat-file export of the current filter selection. Supported formats: CSV (one row per SKU per location), JSON (nested per-SKU with location array), and the platform's .sgen archive format. Export is server-rendered to a temp artifact and delivered via download URL.

Data model

An inventory record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.

Field	Type	Notes
`sku`	string	Primary identifier. Stable across edits. References the product / variant.
`product_id`	integer	References the parent product record.
`variant_id`	integer	Optional. Set when the SKU belongs to a variant.
`tracking_enabled`	boolean	False for digital goods / services. Defaults to true.
`locations`	array	Per-location quantity-on-hand and configuration — see below.
`on_hand_total`	integer	Computed sum across locations.
`alert_threshold`	integer	Optional global default. Per-location override available.
`reorder_point`	integer	Optional global default. Per-location override available.
`allow_negative`	boolean	When true, decrements may push on-hand below zero.
`adjustment_ledger`	array	Append-only history — see below.
`last_audit_at`	timestamp	Set on the most recent snapshot.
`created_at`	timestamp	Set on create, immutable.
`updated_at`	timestamp	Touched on any adjustment or configuration edit.

Each entry in locations carries:

Field	Type	Notes
`location_id`	integer	References a configured location under Settings → Locations.
`on_hand`	integer	Running quantity at this location. Computed from the ledger.
`alert_threshold_override`	integer	Optional. Overrides the SKU-level threshold for this location.
`reorder_point_override`	integer	Optional. Overrides the SKU-level reorder point.

Each entry in adjustment_ledger carries:

Field	Type	Notes
`id`	integer	Append-only sequence.
`location_id`	integer	The affected location.
`kind`	enum	`order-capture`, `refund-restock`, `manual-increase`, `manual-decrease`, `set-absolute`, `transfer-in`, `transfer-out`, `audit-calibration`.
`delta`	integer	Signed change to on-hand. Zero for set-absolute (the new total is recorded separately).
`new_total`	integer	The on-hand at this location after the entry.
`reason_slug`	string	From the configured reason taxonomy.
`reason_note`	string	Optional operator note.
`actor_id`	integer	Operator or system identifier.
`linked_record`	string	Optional link — order id, refund id, transfer pair id, audit id.
`created_at`	timestamp	Set on entry, immutable.

Computation semantics: the on_hand at each location is the result of replaying the ledger entries for that location. set-absolute entries reset the replay baseline. The surface caches the running total and updates it on every write — clients should treat the cached value as authoritative for display and the ledger as authoritative for reconciliation.

Negative-inventory semantics: allow_negative is off by default. A decrement that would push on-hand below zero is rejected unless the override capability is held. Some operations (back-order workflows, pre-order capture) deliberately set allow_negative = true per-SKU.

Tracking-toggle semantics: disabling tracking on a SKU stops new ledger entries but preserves history. Re-enabling tracking does not auto-reconcile — the on-hand resumes from the last recorded total, with an operator expected to audit-calibrate against physical stock.

INVENTORY RECORD├── sku string primary identifier├── product_id integer catalog reference├── variant_id integer optional, for variants├── tracking_enabled boolean off for digital/services├── locations array per-location on_hand + thresholds│ └── location_id, on_hand, alert_override, reorder_override├── on_hand_total integer computed sum across locations├── alert_threshold integer global default (per-loc override)├── reorder_point integer global default (per-loc override)├── allow_negative boolean back-order/pre-order flag├── adjustment_ledger append-only every movement — order capture,│ refund restock, manual, transfer, audit└── timestamps last_audit_at, created_at, updated_at↓ cascades fromORDER CAPTURE (decrements on_hand)REFUND RESTOCK (increments on_hand if restock=true)TRANSFER (paired -out / +in entries, atomic)

Permissions

Access to the Inventory surface is gated at two layers.

Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Inventory surface.

Layer 2 — per-action capability. Within SG-Admin, each Inventory action checks a capability associated with the calling operator's role. The default role configuration ships with three inventory-relevant roles — Store Manager, Warehouse Operator, Read-only Auditor — layered on top of the platform's base roles. The capability map is:

Capability	Administrator	Store Manager	Warehouse	Auditor
List inventory	✔	✔	✔	✔
View SKU detail	✔	✔	✔	✔
Adjust stock (increase)	✔	✔	✔	—
Adjust stock (decrease)	✔	✔	✔	—
Adjust stock (set-absolute)	✔	✔	—	—
Transfer between locations	✔	✔	✔	—
Set reorder point	✔	✔	—	—
Set alert threshold	✔	✔	—	—
Allow negative on a SKU	✔	—	—	—
Set tracking mode	✔	✔	—	—
Snapshot audit	✔	✔	✔	✔
Export	✔	✔	✔	✔

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

Self-protection rules. A decrement that would push on-hand below zero is rejected unless allow_negative = true on the SKU and the operator holds the override capability. A transfer with the same source and destination location is rejected. A SKU referenced by an in-progress order capture cannot have its tracking_enabled flag changed until the order completes or cancels.

Audit. Every write — adjustment, transfer, threshold change, reorder-point change, tracking toggle, snapshot — emits an Activity Log entry and an entry to the inventory record's own append-only adjustment ledger. The ledger is the authoritative reconciliation trail; the Activity Log is the cross-module operator-action trail. Both retain according to the site's general settings.

REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action, per-role) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Quantity + tracking │ decrement→negative without allow_negative → reject│ guards │ transfer same-source-dest → reject└─────────────┬─────────────┘│ passes▼action executes│▼Append-only ledger entry writtenRunning on_hand recomputedThreshold crossing → alert emittedActivity Log entry written

Related references

Products — Reference. Owns the catalog records that inventory SKUs hang off. A product is the marketing surface; a SKU on the product carries the per-location stock record.
Orders — Reference. Order capture decrements inventory at the configured fulfillment location. Order cancellation before fulfillment writes a compensating refund-restock-equivalent entry.
Refunds — Reference. Refunds with restock enabled cascade into inventory-level adjustments. The restock decision lives on the refund record; the cascade lives here.
Settings — Reference. Owns the location definitions, the reason taxonomy for manual adjustments, the alert recipient list, the snapshot retention policy, and the default thresholds for new SKUs.
Users — Reference. Operator identity on every ledger entry is the acting user_id — or a system identifier for automated cascades (order capture, refund restock).
Custom Codes — Reference. Low-stock alert email templates and reorder-trigger templates are themed through the template surfaces.

For the corresponding customer-facing walkthrough — adjusting stock, transferring between locations, setting up low-stock alerts — see the Inventory section of the customer docs at /docs/inventory.

On this page

Guides

Reference

Changelog

Roadmap