Ecommerce Module Reference
| Field | Value |
|---|---|
| Audience | public |
| Area | sg-module |
| Pillar | SG-Modules |
| Updated | 2026-05-27 |
What is this for?
Overview
The Ecommerce module is the product selling surface inside SGEN.
It provides the product catalog (fields, variants, inventory), the order management interface (lifecycle states, status transitions), the checkout flow (steps, validation, guest vs account), and connections to payment gateways.
This page is a field-level reference for the module's surfaces.
The tables below document what each field is, what it controls, and where it appears.
Scope
What the Ecommerce module covers
- Product catalog — a structured record for each product: name, description, price, images, SKU, categories, tags, and SEO fields. Variants (e.g. size or color options) and inventory counts per variant.
- Orders — the full order record from placement through fulfillment. Order lifecycle states, status transitions, line items, customer details, shipping details, and notes.
- Checkout — the steps a buyer moves through: cart review, address collection, shipping method selection, payment. Guest checkout and account-required checkout configuration.
- Payment gateways — connections to supported payment processors. Configuration is per-site. See platform/integrations/payment-gateways.md for the full list of supported gateways and integration instructions.
What the Ecommerce module does NOT cover
- Email marketing automation triggered by purchase events — that is an Integrations concern.
- Subscription or recurring billing product types — not a current module surface.
- Multi-currency display — the module records prices in the configured site currency; multi-currency conversion is not a current module feature.
- Physical fulfillment or shipping carrier integration — SGEN records shipping method and address but does not connect to carrier APIs for label generation.
- Returns processing beyond order status update — returns are tracked as a manual status change on the order record.
- Tax calculation engines — the module supports manual tax rate configuration; it does not connect to automated tax calculation services.
Where to find it
Navigate to SG-Modules > Ecommerce in the admin sidebar.
The Ecommerce panel has four top-level sections: Products, Orders, Checkout Settings, and Payment Gateways.
Fields
Product catalog fields
| Field | What it is | Notes |
|---|---|---|
| Product name | The product's public-facing name. | Appears in catalog listings, product page title, and order line items. |
| Slug | The URL path segment for the product page. | Auto-generated from the product name. Editable. Changing after publication creates a broken URL — create a redirect in the Redirects module. |
| Description (short) | A brief summary displayed in catalog listings and product cards. | Plain text, recommended ≤160 characters. |
| Description (full) | The detailed product description on the product page. | Rich text — supports headings, lists, images. |
| SKU | Stock Keeping Unit — internal identifier for the product. | Must be unique per product. Required for inventory tracking. |
| Price | The base selling price in the site's configured currency. | Shown to buyers. Does not include tax unless the site is configured to display tax-inclusive prices. |
| Compare-at price | An optional original price shown as struck-through to indicate a discount. | When set, displays alongside the current price as a visual indicator of reduced price. Leave blank if not applicable. |
| Product images | One or more images associated with the product. | First image is the primary listing image. Subsequent images appear in the product gallery. Uploaded from the media library. |
| Product categories | Category taxonomy applied to the product. | Used for catalog filtering and navigation. Managed in the Categories taxonomy (shared with blog categories or separate, depending on configuration). |
| Product tags | Free-form tags for the product. | Used for search and filtering. Not navigational. |
| Status | Whether the product is visible on the public site. | Published / Draft / Archived. Only Published products are visible to buyers. |
| SEO fields | Meta title, meta description, and OG image for the product page. | These are the per-product SEO overrides. If blank, the SEO module's global defaults apply. |
Variant fields
Variants represent purchasable options within a single product (e.g. a shirt sold in three sizes).
Each variant is a distinct purchasable unit with its own price, SKU, and inventory count.
| Field | What it is | Notes |
|---|---|---|
| Variant name | The label for this variant, combining its option values (e.g. "Small / Red"). | Auto-generated from option selections. Editable. |
| Option type | The dimension this variant represents — Size, Color, Material, or a custom option name. | Up to 3 option dimensions per product. |
| Option value | The specific value for this option dimension (e.g. "Small", "Red"). | Multiple values per option type create multiple variants. |
| Variant price | The price for this specific variant. | When set, overrides the base product price for this variant. Leave blank to inherit the base price. |
| Variant SKU | Unique identifier for this variant. | Required when inventory tracking is enabled per-variant. |
| Inventory count | The number of units available for purchase. | Decremented automatically on each order that includes this variant. |
| Allow overselling | Whether buyers can purchase this variant when inventory reaches zero. | When off, the variant shows as out-of-stock and cannot be added to cart. |
| Variant image | An image specific to this variant. | Shown when the buyer selects this variant option on the product page. |
# Example: product with two option dimensionsproduct:name: "Classic Cotton Tee"sku: "CCT-BASE"price: 29.00variants:- name: "Small / White"options: {size: Small, color: White}sku: "CCT-S-WHT"inventory: 24allow_overselling: false- name: "Medium / White"options: {size: Medium, color: White}sku: "CCT-M-WHT"inventory: 18allow_overselling: false- name: "Large / Navy"options: {size: Large, color: Navy}sku: "CCT-L-NVY"inventory: 0allow_overselling: false# will show as out-of-stock in the storefrontOrder lifecycle and status fields
An order record is created when a buyer completes checkout.
Orders move through a defined set of status values.
| Status | What it means | Typical trigger |
|---|---|---|
| Pending | Order placed but payment not yet confirmed. | Buyer completes checkout form; payment processing has not responded. |
| Payment received | Payment confirmed by the payment gateway. | Gateway webhook confirms successful charge. |
| Processing | The order is being prepared for fulfillment. | Manual update by the site team, or automated transition from Payment received. |
| Fulfilled | The order has been shipped or delivered. | Manual update when the team marks it shipped. Tracking number can be added at this stage. |
| Partially fulfilled | Some items in the order have been shipped; others have not. | Manual update when a split shipment is sent. |
| On hold | The order is paused — awaiting stock, customer response, or review. | Manual update. |
| Cancelled | The order has been cancelled before fulfillment. | Manual update or payment failure beyond retry window. Inventory is restored on cancellation. |
| Refunded | The order has been fully refunded. | Manual update after issuing a refund through the payment gateway. |
| Partially refunded | The order has been partially refunded. | Manual update after a partial refund. |
Order record fields
| Field | What it records |
|---|---|
| Order ID | Auto-generated unique identifier for the order. |
| Order date | Date and time the order was placed. |
| Customer name | Name provided during checkout. For guest orders, this is entered at checkout. For account orders, this is the account holder's name. |
| Customer email | Email address for order confirmation and correspondence. |
| Billing address | Address fields provided at checkout for billing. |
| Shipping address | Address for delivery. May differ from billing address. |
| Line items | List of products (with variant and quantity) in the order. |
| Subtotal | Sum of line item prices before shipping and tax. |
| Shipping charge | The shipping fee applied at checkout based on the selected shipping method. |
| Tax | Tax amount calculated based on the configured tax rate. |
| Total | Sum of subtotal + shipping + tax. |
| Payment method | The payment gateway used and the last 4 digits of the card (or equivalent gateway-reported identifier). |
| Shipping method | The shipping option the buyer selected at checkout. |
| Tracking number | Manually entered by the site team after fulfillment. Displayed to the customer in the order confirmation area. |
| Order notes | Internal notes added by the site team. Not visible to the buyer. |
| Status | Current order lifecycle status (see Order lifecycle above). |
Checkout configuration fields
| Field | Location | What it controls |
|---|---|---|
| Guest checkout | Checkout Settings → Accounts | Whether buyers can complete purchase without creating an account. On = guest allowed. Off = account required. |
| Account creation at checkout | Checkout Settings → Accounts | Whether the checkout offers an optional account creation step after payment. |
| Checkout steps | Read-only display | Cart → Address → Shipping → Payment → Confirmation. Step sequence is fixed. |
| Required address fields | Checkout Settings → Address | Which address fields are required at checkout. First name, last name, email, and country are always required. Phone, company, address line 2, and state/region are configurable. |
| Shipping methods | Checkout Settings → Shipping → Methods | List of shipping options shown to buyers (e.g. Standard, Express). Each method has a name, price, and optional delivery estimate. |
| Free shipping threshold | Checkout Settings → Shipping → Free shipping | Order subtotal above which free shipping is applied automatically. Leave blank to disable. |
| Checkout terms | Checkout Settings → Terms | Whether buyers must agree to terms and conditions before placing an order. Requires a URL to the terms page. |
| Order confirmation page | Checkout Settings → Confirmation | The page the buyer lands on after completing checkout. Default: the platform's built-in confirmation page. Can be set to a custom page. |
Payment gateway fields
Payment gateway configuration lives in SG-Modules > Ecommerce > Payment Gateways.
Multiple gateways can be active simultaneously.
| Field | What it controls |
|---|---|
| Gateway name | Display label for this gateway configuration. Shown to buyers at the payment step if multiple payment options are presented. |
| Gateway type | The payment processor being connected. See platform/integrations/payment-gateways.md for the full list of supported types. |
| Test mode | When on, the gateway processes test transactions using the gateway's sandbox credentials. No real charges occur. |
| API credentials | The keys or tokens provided by the payment gateway when you created your account with them. The specific fields depend on the gateway type. |
| Active | Whether this gateway is available to buyers at checkout. Multiple gateways can be active. The buyer sees all active gateways as payment options. |
| Display order | The order in which active gateways appear to the buyer at the payment step. Lower number = higher position. |
# Example: payment gateway configuration stategateways:- label: "Credit / Debit Card"type: stripetest_mode: falseactive: truedisplay_order: 1- label: "Pay Later"type: afterpaytest_mode: falseactive: truedisplay_order: 2When to use this
When to use this
Use the product catalog whenever the site sells physical or digital goods.
Products must be Published to be visible on the public site.
Variants are the correct structure for any product that comes in more than one purchasable option — do not create separate products for size or color variations.
Use inventory tracking when stock levels matter for the business.
Set inventory counts on individual variants.
Set Allow overselling to off when selling out is meaningful (limited edition, pre-order with a cap).
Use order status updates to communicate fulfillment progress.
The status is visible in the buyer's account order history.
Add a tracking number to the order record when the shipment is dispatched — this surfaces in the buyer's confirmation view.
Use guest checkout when conversion rate on the checkout is the priority.
Requiring account creation adds friction.
Guest checkout still captures name, email, and address — sufficient for order management and fulfillment.
Use test mode on the payment gateway when building or testing the checkout flow.
No real funds move in test mode.
Switch test mode off before going live.
Configuration
Configuration
See subsections below for each configuration task.
Adding a product
- Open SG-Modules > Ecommerce > Products.
- Click Add Product.
- Enter the Product name and Full description.
- Upload at least one Product image from the media library.
- Set the Price.
- Enter the SKU.
- If the product has variants: open the Variants section, add option types and values, and set variant-level price and SKU where they differ from the base.
- Set inventory counts per variant if inventory tracking is needed.
- Assign the product to Categories and add Tags.
- Set the product Status to Published to make it visible on the site.
- Save.
Processing an order update
- Open SG-Modules > Ecommerce > Orders.
- Locate the order using the search or filter (by status, date range, or customer name).
- Click the Order ID to open the order record.
- Update the Status — for example, from Processing to Fulfilled.
- If shipping: enter the Tracking number in the tracking field.
- Add an internal Note if the update requires context for the team.
- Save.
Connecting a payment gateway
- Open SG-Modules > Ecommerce > Payment Gateways.
- Click Add Gateway.
- Select the Gateway type.
- Enter the API credentials from the payment provider dashboard.
- Enable Test mode and place a test order to confirm the connection works.
- Disable Test mode when confirmed.
- Set the gateway to Active.
- Save.
Examples
Examples
Example 1 — A clothing retailer sets up a product with size variants.
The team creates a product "Linen Blazer" with two option dimensions: Size (XS, S, M, L, XL) and Color (Sand, Slate).
SGEN generates 10 variants (5 sizes × 2 colors).
The team sets a unique SKU and inventory count for each variant.
Three variants have inventory of 0 and Allow overselling is off — those variants display as out-of-stock in the storefront.
Example 2 — Tracking orders through fulfillment.
After a run of weekend orders, the team opens the Orders list filtered to Payment received status.
They print the packing slips, dispatch the packages, and for each order update the status to Fulfilled and enter the carrier tracking number.
Buyers with accounts can see the tracking number in their order history.
The team adds an internal note on one order flagging a damaged outer box for the warehouse team.
Example 3 — Configuring a guest checkout flow with a free shipping threshold.
The site is a gift store where buyer accounts add friction.
The team enables Guest checkout in Checkout Settings.
They set a Free shipping threshold of $75 — orders above that amount automatically receive free shipping.
They configure two shipping methods: Standard ($8, 5–7 business days) and Express ($18, 2–3 business days).
At checkout, buyers see both methods for orders under $75, and both with free shipping applied for orders over $75.
Example 4 — Retiring a product and preserving its URL.
A product is discontinued.
The team sets its status to Archived — it is removed from the storefront catalog.
The product URL now returns 404.
The team creates a 301 redirect in the Redirects module pointing the old product URL to the best available alternative in the current catalog.
Search engines index the redirect target rather than the discontinued URL.
Edge cases
Edge cases
Inventory count goes negative.
If Allow overselling is on and orders arrive simultaneously for the last unit, the inventory count can reach negative values.
The site team must resolve this by contacting buyers and updating the order status manually.
Set Allow overselling to off for products where running out of stock is not acceptable.
Variant price not overriding base price.
A blank variant price field means the variant inherits the base product price.
If a variant is priced differently, set the variant price explicitly — do not leave it blank expecting it to inherit a different value.
Checkout not showing a shipping method.
Confirm at least one shipping method is configured and active in Checkout Settings → Shipping.
If all shipping methods have a minimum order value that the buyer's cart does not meet, the checkout may block progression.
Review shipping method conditions.
Payment gateway in test mode on a live site.
A gateway in test mode does not process real payments.
A common oversight is launching a site without disabling test mode on the payment gateway.
Before launch: confirm test mode is off on all active gateways and place a live test transaction with a real card.
Order status not updating buyer-visible confirmation.
Order status changes update the order record in the admin.
The buyer sees their order status in their account order history (for account orders) or in the confirmation email.
If the buyer reports their order status is not updated, confirm the status was saved in the admin and that the email notification (if configured) was sent.
Product slug change breaking existing links.
SGEN does not automatically create a redirect when a product slug changes.
Changing a published product's slug creates a 404 at the old URL.
Create a 301 redirect in the Redirects module before or immediately after changing a published product's slug.
Tax display discrepancy.
The Ecommerce module displays prices exclusive of tax by default.
If the site requires tax-inclusive pricing (common for consumer-facing retail in some regions), configure the tax display setting in Checkout Settings.
The tax rate is applied at the basket level — SGEN does not calculate tax by jurisdiction automatically.
Related features
Related
- SEO module — product pages output Product schema (JSON-LD) when the SEO module's Product schema type is enabled. Product SEO fields in the catalog feed into that schema.
- Redirects module — when products are discontinued or slugs change, create redirects to prevent broken URLs in the catalog.
- Tracking & Consent module — conversion tracking scripts (ad pixels, analytics events) related to purchase events are gated by consent categories. Assign those scripts to the Marketing or Analytics category as appropriate.
- Payment gateways reference — the full list of supported payment processors, credential locations, and gateway-specific configuration steps.
Related reading
| Topic |
|---|
| SEO Module Reference |
| Redirects Module Reference |
| Tracking & Consent Module Reference |
| Payment Gateways |