Abandoned Cart — Reference
The Abandoned Cart surface is the recovery plane for SGEN commerce. It owns the detection logic that marks a cart as abandoned, the email sequence that nudges the customer back, the one-time discount minted on recovery, and the conversion ledger that tracks which carts came back and which did not.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a recovery program. 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
Abandoned Cart lives under the Commerce module in SG-Admin. The module renders three primary views — the abandoned-cart list, the per-cart detail view with its recovery timeline, and the sequence editor that configures the email cadence — and exposes a small set of write operations for trigger send, pause sequence, override discount, mark resolved, and reset detection.
The module is paired by convention: one half renders the views and prepares the cart and timeline data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
A cart enters the abandoned state when its last update time crosses the configured detection threshold and the customer has not progressed to a paid order. The detection runs on a scheduled job; carts surface in the abandoned view shortly after the threshold passes. Recovery emails fire on a separate cadence configured per site.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Commerce → Abandoned Cart
- URL prefix:
/sg-admin/abandoned-cart/ - View templates:
application/views/Admin/Commerce/AbandonedCart/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Commerce → Abandoned Cart [ Configure cadence ]│├──────────────────────────────────────────────────────────────────────┤│ Cart Customer Value Abandoned Stage ││ ────────── ──────────────────── ──────── ───────────── ──────────││ C-48201 maria@example.com $128.40 12 min ago pending ││ C-48198 ren@example.com $76.20 2 hours ago email-1 ││ C-48155 jen@example.com $245.00 1 day ago email-2 ││ C-48102 anonymous $58.10 3 days ago email-3 ││ C-48077 mark@example.com $320.00 recovered resolved ││ ││ Abandoned (30d): 428 carts · Recovered (30d): 61 carts (14%) ││ [ View ] [ Trigger now ] [ Pause ] [ Mark resolved ] │└──────────────────────────────────────────────────────────────────────┘Actions
The Abandoned Cart surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List abandoned carts
Returns the abandoned-cart set paginated, with cart identifier, customer (or anonymous), cart value, abandonment timestamp, and current stage in the recovery sequence (pending, email-1, email-2, email-3, resolved, expired). Supports filter by stage, by date range, by value range, and by customer. The default view excludes resolved carts older than the retention window — they remain queryable via the explicit filter.
Engineering note. The list view does not run the detection job. It reads the stored abandonment state written by the scheduled detection task.
View abandoned cart
Returns the full record for a single abandoned cart — items, totals, customer details, abandonment timestamp, detection signal (last activity, checkout step reached), the recovery email timeline with one entry per send, the discount code minted for the cart if any, and the conversion outcome. The cart items reference the live product records; price snapshots are stored separately.
Configure detection threshold
The detection threshold is the idle window after which a cart is marked abandoned. Configured site-wide under the Abandoned Cart settings panel. Default is 60 minutes. Changes apply to carts evaluated after the next detection run; in-flight detection state is not retroactively reclassified.
Configure recovery cadence
Opens the sequence editor. The cadence is an ordered list of email steps, each with an offset from the abandonment timestamp, a template reference, and an optional discount-on-recovery rule. The default cadence ships three steps — 1 hour, 24 hours, 72 hours — but is fully configurable. On submit, the surface validates the offset order and the template references, and persists the new sequence. Active sequences in flight retain the cadence they were started under; new abandoned carts pick up the new cadence.
Trigger send now
Forces the next scheduled email in the sequence to send immediately. Used for testing the template and for manual nudges outside the scheduled cadence. Audited as an out-of-cadence event.
Pause sequence
Pauses the recovery sequence for a single cart without resolving it. The cart remains in the abandoned state; subsequent scheduled emails are skipped until the sequence is resumed. Used when an operator is in direct contact with the customer and the automated cadence would conflict.
Override discount
Replaces the discount value attached to a cart's recovery sequence. The minted code remains the same; the value or expiry is rewritten. Used for one-off goodwill adjustments. The override is recorded in the cart's audit trail.
Mark resolved
Closes the abandoned-cart record without conversion. Used when the customer is known to have completed the purchase through a different channel, when the cart contained items that became out of stock, or when the operator no longer wants to send recovery emails. Resolved carts are excluded from the default list and from cadence evaluation.
Reset detection
Removes the abandonment marker from a cart that the operator deems active. The cart returns to the normal in-flight state; subsequent activity in the cart restarts the idle clock. Used when a customer reports they are still actively shopping but the detection threshold has fired prematurely.
Engineering note. Reset detection does not delete the cart's prior recovery emails from the audit ledger. The ledger remains visible on the next abandonment, if any, for support context.
Track conversion
Read-only. Returns the conversion outcome for a single cart — converted (paid), partial-conversion (different cart, same customer), expired, or resolved-manual. The conversion ledger correlates the abandoned cart with the eventual order by cart identifier and customer; conversions trigger the resolved state automatically.
Data model
An abandoned-cart 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. |
cart_id | integer | Reference to the live cart record. |
customer_id | integer | Optional. Null for anonymous (email-only) carts. |
recipient_email | string | Captured during checkout. Required for the sequence to fire. |
cart_value | numeric | Snapshot at abandonment time. |
abandoned_at | timestamp | When the detection task marked it. |
last_activity_at | timestamp | Cart's last write before abandonment. |
stage | enum | pending, email-1, email-2, email-3, resolved, expired. |
sequence_id | integer | Reference to the cadence definition used. |
discount_code | string | Optional. Minted on first recovery email. |
discount_expires_at | timestamp | Optional. |
resolved_outcome | enum | converted, partial, expired, manual. Null until resolved. |
order_id | integer | Optional. Set on conversion. |
created_at | timestamp | Set when the detection task fires. |
updated_at | timestamp | Touched on stage transitions. |
abandoned_cart_id, step_index, template_ref, sent_at, delivery_outcome, opened_at, clicked_at. The ledger is append-only; resends write additional entries.Detection semantics: the scheduled task runs on a configurable interval (default every 5 minutes). It selects carts where last_activity_at is older than the configured threshold and no abandoned-cart record exists yet. Carts that progress to checkout-complete are excluded automatically.
Sequence semantics: the cadence is evaluated per cart based on abandoned_at plus each step's offset. A step fires only if no later activity has happened on the cart and the cart is not resolved. Stage transitions are atomic — the surface advances stage only after the email send confirms delivery handoff.
LIVE CART│▼ (no activity for threshold window)┌──────────────────────────┐│ Detection task │ scheduled, default 5 min└─────────────┬────────────┘│▼ABANDONED (stage = pending)│▼ (cadence offset 1)email-1 (discount minted)│▼ (cadence offset 2)email-2│▼ (cadence offset 3)email-3│┌──────────┴──────────────┐│ │▼ ▼CONVERTED EXPIRED(order_id set) (after final offset)Permissions
Access to the Abandoned Cart 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 Abandoned Cart surface.
Layer 2 — per-action capability. Within SG-Admin, each Abandoned Cart action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List abandoned carts | ✔ | ✔ | ✔ |
| View cart detail | ✔ | ✔ | ✔ |
| Configure detection threshold | ✔ | — | — |
| Configure recovery cadence | ✔ | ✔ | — |
| Trigger send now | ✔ | ✔ | — |
| Pause sequence | ✔ | ✔ | — |
| Override discount | ✔ | — | — |
| Mark resolved | ✔ | ✔ | — |
| Reset detection | ✔ | ✔ | — |
| Export conversion data | ✔ | ✔ | ✔ |
Self-protection rules. A cart cannot be triggered out of cadence more than once in any single sequence step — the surface returns a structured rejection on the second attempt. Detection cannot be reset on a cart that has already converted; the conversion outcome is final. A discount override cannot extend the discount expiry beyond the cart's final cadence offset plus the configured grace window.
Audit. Every write — trigger, pause, resume, override, resolve, reset — emits an Activity Log entry. The log records the acting operator, the cart identifier, and the change shape. Recovery email sends write to the email ledger; the two records are correlated by abandoned-cart identifier.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ re-trigger / post-conversion-reset /│ │ out-of-window discount → reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry + email ledgerRelated references
- Orders — Reference. Converted abandoned carts write to the orders surface. Attribution from a recovery email back to the order is carried by the cart identifier.
- Customers — Reference. Customer record holds the email used for recovery sends. Anonymous carts carry the email on the cart record itself.
- Discounts — Reference. The discount-on-recovery option mints a coupon-like code through the Discounts engine. Stacking with other discounts at the recovered checkout is governed by the rule's stack policy.
- Email Templates — Reference. The cadence references templates defined here. Changes to a template propagate to in-flight sequences on the next scheduled send.
- Settings — Reference. Owns the detection threshold, the default cadence, the audit-log retention window, and the global email-sender configuration.
- Activity Log — Reference. Cart-trigger, pause, resume, and override events are surfaced here for cross-surface auditing.
/docs/abandoned-cart.