Orders — Reference
The Orders surface is the transactional core of every SGEN ecommerce site. It owns the order record, the status workflow that moves an order from creation to fulfillment, the financial side (totals, taxes, refunds), and the artifacts produced for the operator (exports, packing slips, customer notifications). Anything that represents a customer purchase 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 modeling reporting against the data shape. 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
Orders live under the Orders module in SG-Admin, inside the ecommerce sub-tree. The module renders four primary views — the order list, the order detail page, the order edit form, and the export builder — and exposes a small set of write operations for status transitions, line-item edits, refunds, and soft deletes.
The module is paired by convention with the Products surface — order line items hold references to product records but capture a snapshot of the product state at purchase time. That snapshot is what an order shows on the detail page, not the live product record. This matters for reporting: editing a product after the sale does not rewrite history on existing orders.
Refunds are a sub-surface inside Orders. They produce their own records, linked back to the parent order, and may be partial (one line, partial quantity, fixed amount) or full. Refund processing is gated by the configured payment provider — the order surface initiates the refund; the provider determines whether the operation completes.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Ecommerce → Orders
- URL prefix:
/sg-admin/orders/ - View templates:
application/views/Admin/Orders/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Ecommerce → Orders [Export ▼] │├──────────────────────────────────────────────────────────────────────┤│ # Customer Total Status Placed ││ ──── ─────────────────── ──────── ────────────── ───────────────││ 1042 Maria Reyes $148.00 Fulfilled 2 min ago ││ 1041 Sandbox Buyer $ 32.50 Awaiting pay 18 min ago ││ 1040 Jerome Cruz $612.75 Partial refund 3 hours ago ││ 1039 James Compton $ 89.00 Processing yesterday ││ 1038 Anonymous (guest) $ 14.99 Cancelled 2 days ago ││ ││ Filter: [Status ▼] [Date range] [Customer] Bulk: [Mark fulfilled] │└──────────────────────────────────────────────────────────────────────┘Actions
The Orders 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 order records visible to the current operator, paginated, with customer, total, status, and placed-at columns. Supports column sort, free-text filter, status filter, date-range filter, and per-page count. Driven by the data-table contract used across SG-Admin modules — responses arrive as a row collection plus a total count, suitable for direct binding to a paged grid.
Engineering note: the order list is the single hottest read in the ecommerce surface. The query is cached per-operator with a short TTL and invalidated on any write that touches an order in the visible window.
View order detail
Loads the full order record into a read-mostly detail page — customer block, line items, totals breakdown, status history, payment events, fulfillment events, and the refund ledger. Editable fields are gated behind separate actions; the detail page itself does not write.
Create order (manual / draft)
Opens an empty order form for operator-entered sales (phone orders, in-person, comped orders). Required at minimum: customer (or guest contact), at least one line item, currency. Optional fields cover shipping address, billing address, discount, tax override, and operator note. On submit, the surface validates customer existence, freezes the line-item snapshot, computes totals, and persists the record with status draft until explicitly advanced.
Edit order
Loads an existing record into the same form shape used for create, pre-populated. Line items, addresses, and operator notes are editable; status is not (status moves through the transition action, not the edit form). The form is partial-update by default — fields left blank do not clear server-side values.
Engineering note: editing an order after capture rewrites totals but does NOT re-call the payment provider. Operators reconciling a captured order against an edit need to either issue a refund for the difference or capture an additional payment through the adjacent Payments surface.
Advance status
Moves the order through the configured status workflow. Default transitions cover draft → awaiting-payment → processing → fulfilled → completed, with branches for cancelled and refunded. Each transition can be gated by a capability check (see Permissions), can fire a customer notification, and writes an entry to the status history log.
The status workflow is configurable under Settings → Ecommerce → Order Statuses. Custom statuses + custom transitions are supported; the action surface validates that the requested transition is allowed from the current state.
Issue refund
Opens the refund composer. Operator picks scope (full / partial-line / partial-amount), enters the refund reason, and confirms. The surface validates the refund against the captured amount remaining, calls the configured payment provider, writes the refund record, and updates the parent order's refund ledger and remaining-refundable total. Failed provider calls leave the refund record in failed status with the provider error attached — no partial state on the order itself.
Engineering note: refund records are append-only. A failed refund does not block subsequent refund attempts on the same line; it records a failure and leaves the refundable balance unchanged.
Mark fulfilled / unfulfilled
Toggles fulfillment state on the line items. Optional tracking fields cover carrier, tracking number, and shipped-at timestamp. Fulfilling all lines advances the parent order's status to fulfilled; un-fulfilling drops back to processing.
Export
Generates a flat-file export of the current filter selection. Supported formats: CSV, JSON, and the platform's .sgen archive format for re-import into another SGEN site. Export is server-rendered to a temp artifact and delivered via download URL — the operator does not block on generation for large selections.
Soft delete
Marks the record cancelled-archived without removing it from the database. Soft-deleted orders disappear from the default list view but remain queryable via the archive filter and continue to back reporting queries. Refund obligations against soft-deleted orders are preserved.
Restore
Reverses a soft delete. The record returns to the active list with its prior status intact. Restore does not re-run customer notifications.
Data model
An order 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. |
order_number | string | Customer-facing identifier. Configurable prefix. |
customer_id | integer | References the customer record. Nullable for guest orders. |
customer_snapshot | object | Frozen contact block at order time — name, email, phone. |
line_items | array | Frozen product snapshots — sku, name, qty, unit_price, line_total. |
currency | string | ISO 4217 code. Set at create, immutable. |
subtotal | decimal | Sum of line totals before tax and shipping. |
tax_total | decimal | Computed from tax rules at order time. |
shipping_total | decimal | From the configured shipping rate. |
discount_total | decimal | From the applied discount, if any. |
grand_total | decimal | Final amount charged. |
refunded_total | decimal | Sum of completed refunds. |
status | enum | One of the configured workflow statuses. |
placed_at | timestamp | Set when the order leaves draft. |
fulfilled_at | timestamp | Set when all lines are fulfilled. |
payment_events | array | Append-only ledger — capture, refund, void records. |
status_history | array | Append-only ledger — every transition with operator id. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on any edit. |
Soft-delete semantics: status = cancelled-archived is the soft-deleted state. Soft-deleted orders retain all other fields and continue to back the refund ledger.
Authored events: every status transition, refund, fulfillment event, and edit writes to the order's append-only event ledgers. The order detail page renders these in reverse chronological order.
ORDER RECORD├── id integer primary key├── order_number string customer-facing├── customer_id integer nullable for guest orders├── customer_snapshot object frozen contact at order time├── line_items array frozen product snapshots├── currency string immutable after create├── totals decimal × 6 subtotal/tax/shipping/discount/grand/refunded├── status enum configurable workflow├── timestamps placed_at, fulfilled_at, created_at, updated_at├── payment_events append-only capture/refund/void├── status_history append-only every transition + operator id└── on permanent delete cascade refund records preserved as orphansPermissions
Access to the Orders 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 Orders surface.
Layer 2 — per-action capability. Within SG-Admin, each Orders action checks a capability associated with the calling operator's role. The default role configuration ships with four ecommerce-specific roles — Store Manager, Fulfillment Operator, Support Operator, Read-only Auditor — layered on top of the platform's base roles. The capability map is:
| Capability | Store Manager | Fulfillment | Support | Auditor |
|---|---|---|---|---|
| List orders | ✔ | ✔ | ✔ | ✔ |
| View detail | ✔ | ✔ | ✔ | ✔ |
| Create manual order | ✔ | — | — | — |
| Edit order | ✔ | — | — | — |
| Advance status (non-fulfillment) | ✔ | — | ✔ | — |
| Mark fulfilled / unfulfilled | ✔ | ✔ | — | — |
| Issue refund | ✔ | — | ✔ | — |
| Soft delete | ✔ | — | — | — |
| Restore | ✔ | — | — | — |
| Export | ✔ | ✔ | ✔ | ✔ |
Self-protection rules. Refunds cannot exceed the captured amount remaining on the order. Status transitions that are not part of the configured workflow are rejected. An operator cannot soft-delete an order that has un-refunded line items unless the override capability is held.
Audit. Every write — create, edit, status transition, refund, fulfillment update, soft delete, restore — emits an Activity Log entry and an entry to the order's own append-only status history. The log records the acting operator, the target order, and the change shape (field-level diff for edits). Activity Log retention is governed by the site's general settings.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action, per-role) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Workflow + financial │ transition not allowed,│ guard rules │ refund > remaining → reject└─────────────┬─────────────┘│ passes▼action executes│▼Append-only ledgers updatedActivity Log entry writtenRelated references
- Products — Reference. Owns the catalog records that order line items snapshot at purchase time. Editing a product does not rewrite history on existing orders.
- Users — Reference. Customer records — order
customer_idreferences this surface. Re-attribution rules apply on permanent customer delete. - Settings — Reference. Owns the order status workflow definition, the payment provider configuration, tax rules, and shipping rates. Changes there reshape what an order can contain and how it transitions.
- Forms — Reference. The checkout flow that produces orders is built on top of the Forms surface. Submission records and order records are linked via order id.
- Media — Reference. Product images referenced on the order detail page resolve against the Media library.
- Custom Codes — Reference. Order confirmation emails, packing slip templates, and storefront order pages can be themed through the platform's template surfaces.
/docs/orders.