Products — Reference
The Products surface is the catalog plane of every SGEN ecommerce site. It owns the product record, the variant matrix that expresses the same product across options like size and color, the inventory ledger that tracks on-hand counts and reservations, the price and category models, and the per-product SEO and image attachments that ship the product to the storefront.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or building catalog imports. 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
Products live under the Products module in SG-Admin, inside the ecommerce sub-tree. The module renders four primary views — the product list, the product detail page (a composite of content + variants + inventory + SEO panes), the category tree, and the import / export view — and exposes a small set of write operations for create, edit, variant management, inventory adjust, soft delete, and restore.
The product record is intentionally rich. A single product carries operator-facing fields (name, SKU, internal notes), customer-facing fields (display name, description, gallery, SEO meta), commercial fields (price, compare-at price, tax class, shipping class), and structural fields (categories, tags, variants, inventory). The detail view splits these into panes, but a single API write touches whichever fields the operator changed.
Variants are a sub-surface inside Products. They share the parent product's content but carry their own SKU, price, inventory count, and image. The variant matrix is derived from configurable option axes (e.g., Size × Color) — the platform generates the variant grid; the operator fills in or overrides the per-cell values.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Ecommerce → Products
- URL prefix:
/sg-admin/products/ - View templates:
application/views/Admin/Products/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Ecommerce → Products [+ New product] │├──────────────────────────────────────────────────────────────────────┤│ SKU Name Price Stock State ││ ────────── ──────────────────── ──────── ─────── ───────────────││ SHIRT-001 Operator Tee $ 28.00 142 Published ││ MUG-CER-01 Recovery Mug $ 14.00 89 Published ││ KIT-START Starter Kit (bundle) $ 89.00 — Published ││ BOOK-OP-01 Field Manual $ 22.00 0 Out of stock ││ TEST-DR-99 Sandbox Draft — — Draft ││ ││ Categories: [Apparel] [Drinkware] [Bundles] Filter: [All ▼] │└──────────────────────────────────────────────────────────────────────┘Actions
The Products 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 product records visible to the current operator, paginated, with SKU, name, price, stock total, and state columns. Supports column sort, free-text filter (matches SKU, name, internal notes), category filter, state filter, and per-page count. Driven by the data-table contract used across SG-Admin modules.
View product detail
Loads the full product record into a composite detail page — content pane (name, description, gallery), variant pane (matrix + per-variant overrides), inventory pane (per-variant counts + reservation breakdown), pricing pane (base + compare-at + tax/shipping class), categories + tags pane, and SEO pane (per-product meta title, meta description, og image, schema overrides).
Create product
Opens an empty product form. Required at minimum: name, SKU (unique), state. Optional fields cover everything else. The product starts as draft and is not visible on the storefront until promoted to published. Variants and inventory can be added on initial create or in a follow-up edit.
Edit product
Loads an existing record into the same form shape used for create, pre-populated. The form is partial-update — fields left blank do not clear server-side values. Edits to the content pane, gallery, SEO, and categories take effect immediately; edits to variants or inventory follow the variant-specific actions below.
Engineering note: edits to a published product DO NOT rewrite line items on existing orders. Orders snapshot the product state at purchase time — see the Orders reference for the snapshot semantics.
Manage variants
Sub-action on the product detail. Operators define the option axes (e.g., Size, Color), the values per axis (e.g., S/M/L, Red/Blue), and the platform generates the variant grid. Each variant carries its own SKU, price, inventory count, and optional image override. The operator can:
- Bulk fill — set the same price or inventory across all variants in one operation.
- Selective override — set per-variant values that diverge from the parent.
- Disable variant — mark a specific cell unavailable without deleting it.
- Delete variant — remove a cell entirely. Soft-delete only — orders that reference the variant keep their snapshot.
Adjust inventory
Sub-action on the variant (or the product, for variant-less products). Operators enter a delta (e.g., +20, -3) and a reason (restock, damage, count correction). The platform writes to the append-only inventory ledger, updates the on-hand count, and re-computes the reservable count (on-hand minus pending order reservations).
Engineering note: inventory adjustments are append-only. A "set to 50" action is recorded as a delta from the prior count, not as an overwrite. The reason field is required for audit.
Manage categories
Categories are a tree structure managed via a separate category view inside the module. Products belong to zero or more categories. The category tree supports nested categories up to a configurable depth (default 5). Edits to a category (rename, move, delete) update all referencing products.
Manage SEO
Per-product SEO pane covers meta title, meta description, canonical URL override, OpenGraph image override, Twitter card type, and schema.org JSON-LD overrides. Empty fields fall back to the platform's global SEO defaults — see the SEO reference for the defaulting chain.
Toggle publish state
Moves the product between draft, published, and archived. Only published products are visible on the storefront. draft is pre-launch; archived removes from storefront but keeps the record queryable for reporting.
Import / export
Bulk operations via the import / export view. Supported formats: CSV with a documented column header set, JSON, and the platform's .sgen archive format. Imports validate row-by-row and emit a structured report of accepted / rejected rows. Exports include all fields and respect the current filter selection.
Soft delete
Marks the record archived without removing it from the database. Soft-deleted products leave the storefront and the default list view but remain queryable via the archive filter. Inventory counts and the ledger are preserved.
Restore
Reverses a soft delete. The record returns to the active list in its prior state (NOT auto-republished).
Permanent delete
Hard-removes the record. Available only after a soft delete. Inventory ledgers are detached and re-attributed to a system archive bucket. Variant references in order line items are preserved through the snapshot mechanism — see Orders.
Data model
A product 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 |
|---|---|---|
id | integer | Primary key. Stable across edits. |
sku | string | Unique across active products. Editable but discouraged after publish. |
name | string | Internal name. |
display_name | string | Customer-facing name. Falls back to name if empty. |
description | text | Long-form rich content. |
gallery | array | Ordered list of Media library references. |
price | decimal | Base price in the site's primary currency. |
compare_at_price | decimal | Optional strike-through price. |
tax_class | string | References a Settings → Tax class. |
shipping_class | string | References a Settings → Shipping class. |
categories | array | References to category records. |
tags | array | Free-form string tags. |
option_axes | array | Variant axis definitions — name + ordered values. |
variants | array | Per-variant records — sku, price overrides, inventory, image. |
inventory_count | integer | On-hand count for variant-less products. |
seo | object | Per-product overrides — meta_title, meta_desc, og_image, schema. |
state | enum | draft, published, archived. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
published_at | timestamp | Set on first promotion to published. |
state = archived is the soft-deleted state. Soft-deleted products retain all other fields. Permanent delete removes the row but preserves order-line-item snapshots through the Orders surface.Order snapshot reference: order line items hold a frozen copy of sku + display_name + price + image at purchase time. Editing a product does not rewrite history.
Inventory ledger: every adjustment writes an append-only entry with delta, reason, operator, and timestamp. The current inventory_count is the sum of the ledger. The reservable count subtracts pending order reservations.
PRODUCT RECORD├── id integer primary key├── identity sku, name, display_name├── content description, gallery (Media refs)├── commerce│ ├── price decimal│ ├── compare_at decimal (optional)│ ├── tax_class string│ └── shipping_class string├── taxonomy categories, tags├── variants│ ├── option_axes array e.g., Size, Color│ └── variant rows sku, price, inventory_count, image override├── seo object per-product meta overrides├── state enum draft | published | archived└── timestamps created_at, updated_at, published_at↓ on orderORDER LINE ITEM (frozen snapshot — see Orders ref)Permissions
Access to the Products 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 Products surface.
Layer 2 — per-action capability. Within SG-Admin, each Products action checks a capability associated with the calling operator's role. The default role configuration uses the platform's base roles plus the ecommerce-specific Store Manager and Catalog Editor roles. The capability map is:
| Capability | Administrator | Store Manager | Catalog Editor | Viewer |
|---|---|---|---|---|
| List products | ✔ | ✔ | ✔ | ✔ |
| View detail | ✔ | ✔ | ✔ | ✔ |
| Create product | ✔ | ✔ | ✔ | — |
| Edit content / SEO / categories | ✔ | ✔ | ✔ | — |
| Edit price / tax class / shipping class | ✔ | ✔ | — | — |
| Manage variants | ✔ | ✔ | ✔ | — |
| Adjust inventory | ✔ | ✔ | — | — |
| Toggle publish state | ✔ | ✔ | — | — |
| Soft delete | ✔ | ✔ | — | — |
| Restore | ✔ | ✔ | — | — |
| Permanent delete | ✔ | — | — | — |
| Bulk import | ✔ | ✔ | — | — |
| Export | ✔ | ✔ | ✔ | ✔ |
Self-protection rules. Products with pending order reservations cannot be permanently deleted. SKU uniqueness is enforced across draft + published states; archived products can hold a previously-used SKU. Variant deletion is rejected if the variant has un-fulfilled order line items.
Audit. Every write — create, edit, variant change, inventory adjust, state change, soft delete, restore, permanent delete, bulk import — emits an Activity Log entry and (for inventory) an entry to the inventory ledger. Activity Log retention is governed by the site's general settings.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-field, per-role) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Reference-integrity guard │ reserved variants,│ │ unique SKU, pending orders└─────────────┬─────────────┘│ passes▼action executes│┌─────┴──────────┐▼ ▼Activity Log Inventory ledger(always) (inventory writes only)Related references
- Orders — Reference. Order line items hold frozen snapshots of product state at purchase time. Inventory reservations against products are managed through Orders.
- Media — Reference. Product galleries and variant image overrides reference the Media library. Soft-deleting a media record orphans the reference but does not break the product.
- Settings — Reference. Owns the tax class definitions, shipping class definitions, default currency, and global storefront defaults. Changes there reshape what products can express.
- Categories — Reference. Sub-surface inside Products. The category tree is managed adjacent to the product list and referenced by product records.
- SEO — Reference. Per-product SEO falls back to the global SEO defaults. The defaulting chain is documented in the SEO reference.
- Discounts — Reference. Discount records target product / category / tag selectors. Catalog edits can change which products an active discount covers.
/docs/products.