Wishlist — Reference
The Wishlist surface is the saved-items plane for SGEN storefront customers. It owns the records that pair a customer to a set of products they've marked for later, the per-list visibility rules, the share-token for sending a list to someone else, the list-to-cart conversion path, and the abandoned-wishlist reminder schedule. Anything on the storefront that lets a customer mark, save, or share an item 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 scoping a customer-engagement model. 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
Wishlist lives under the Commerce module in SG-Admin, in the engagement group. The module renders three primary views — the global wishlist ledger (every customer, every list), the per-customer wishlist detail view, and the reminder-schedule configuration — and exposes a small set of write operations for clear list, send reminder now, configure reminder cadence, and edit the conversion-promo settings.
The module is paired by convention: one half renders the views and prepares the wishlist 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.
The storefront-facing surface — the customer-side actions that add to wishlist, share a list, or convert a list to a cart — runs against the front controller, not the admin controller. Customers do not authenticate against SG-Admin; their wishlist actions run as authenticated storefront sessions. The admin surface described here is the operator view of those records.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Commerce → Engagement → Wishlist
- URL prefix:
/sg-admin/wishlist/ - View templates:
application/views/Admin/Commerce/Wishlist/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Commerce → Engagement → Wishlist [ Send reminder ] │├──────────────────────────────────────────────────────────────────────┤│ Customer Items Value Last added Reminder state ││ ─────────────────── ───── ──────── ──────────── ──────────────││ Maria Reyes 7 ₱8,420 2 days ago next: in 5d ││ Jonas Tan 3 ₱3,150 8 days ago next: in 1d ││ Anna Cruz 12 ₱24,800 1 day ago paused ││ Reggie de Leon 1 ₱290 45 days ago next: today ││ (shared link viewer) 4 ₱5,600 shared by AR — ││ ││ Total saved items: 1,284 · Reminders due today: 12 ││ [ View list ] [ Edit cadence ] [ Send reminder now ] │└──────────────────────────────────────────────────────────────────────┘Actions
The Wishlist surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List and filter
Returns the customer-wishlist ledger paginated, with customer name, item count, total saved value (computed at current prices), last-added timestamp, reminder state (next reminder due, paused, opted out), and share-token presence. Supports filter by reminder state, by total-value threshold, by last-added range, and by free-text on customer name. Empty wishlists are excluded by default; an explicit filter surfaces them.
View customer wishlist
Returns the full record for a single customer's wishlist — the list of saved items with per-item added-timestamp, the share-token if one has been issued, the per-customer reminder-cadence override (if any), the opt-out flag, and the conversion history (which items moved from wishlist to cart, when). The item list is paginated within the detail view.
Add or remove items (storefront path)
Customer-side. A customer signed in to the storefront adds a product to their wishlist with one click; removal works the same way. The admin surface does not expose item-level write paths — operators view the records but do not curate the customer's saved items. The exception is the clear list action below.
Clear list
Empties a customer's wishlist. Available to operators with the correct capability. Used for housekeeping (test accounts, customer-service reset) and for compliance requests. The clear is hard — items are removed, not soft-deleted. The customer's reminder state is reset to "no items, no reminder due."
Issue or revoke share-token
A share-token is an opaque identifier the customer can hand to someone else; opening the share URL loads the customer's wishlist in read-only mode. The customer issues the token from the storefront; the admin surface can revoke a token (for example, on a customer service request after the URL was leaked). Revocation invalidates the URL — subsequent visits return a "list no longer shared" page.
Configure reminder cadence
Opens the per-site reminder-schedule editor. Editable fields cover the wait window after last addition (default 3 days), the maximum reminder count per list (default 3), the inter-reminder interval (default 7 days), and the global opt-out behavior (whether a customer opt-out on transactional emails also pauses wishlist reminders). Changes apply to reminders scheduled after the edit; in-flight schedules retain their original cadence.
Send reminder now
Schedules an immediate reminder for a named wishlist (or set of wishlists). Used when an operator wants to trigger a campaign outside the standard cadence — for example, when a discount rule launches that the customer's saved items would qualify for. The send-now path respects the customer's opt-out — opted-out customers are skipped with a structured response naming the count skipped.
Pause or resume reminders per customer
Toggles the per-customer reminder pause. A paused customer receives no reminders regardless of the global cadence; their wishlist is otherwise active and visible. Resume restores the customer to the global cadence.
Configure conversion-promo
The list-to-cart conversion path optionally attaches a one-time discount code generated from the Discounts engine. The conversion-promo editor toggles this behavior on or off, picks the discount rule to use, and sets the expiration window for the generated code.
Engineering note. The reminder-send path is idempotent within a window — re-running the send-now path for the same wishlist inside a configured throttle returns the cached schedule rather than duplicating the email.
Data model
A wishlist 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. |
customer_id | integer | Foreign key into Customers. One wishlist per customer (current model). |
items | json | Ordered list of saved items. Each item: product_id, added_at, notes (optional). |
share_token | string | Opaque identifier for the share URL. Null when no share is active. |
share_issued_at | timestamp | Set when share-token is issued. |
share_revoked_at | timestamp | Set when share-token is revoked. |
reminder_cadence_override | json | Per-customer cadence overrides. Null means use site default. |
reminder_count_sent | integer | Reminders already sent for the current cycle (resets on next addition). |
next_reminder_at | timestamp | When the next reminder is scheduled. Null when paused or capped. |
is_paused | boolean | Per-customer pause flag. |
opted_out_at | timestamp | Set when the customer opts out of wishlist reminders. |
created_at | timestamp | Set on first item added. |
updated_at | timestamp | Touched on any edit. |
wishlist_id, product_id, converted_at, cart_id, discount_code (if conversion-promo applied), order_outcome (paid, abandoned, refunded, null while pending). Used for engagement attribution and for diagnosing low-converting reminder cohorts.Share-token registry: share-tokens are stored alongside the wishlist record. The token is opaque and is never derived from the customer identifier — leaking the token exposes the saved list but does not expose the customer's account. Revocation flips a marker; the token row is retained for audit.
Live-price rule: the total-saved-value column in the admin view is computed at the current product price, not the price at the time the item was added. Price changes since addition are visible to the customer in the storefront view of their list (with a price-changed marker if the change is large enough to surface).
CUSTOMER on storefront│▼ click "save for later"┌───────────────────────────────────────────┐│ WISHLIST entry created / item appended ││ ▶ reminder_count_sent reset ││ ▶ next_reminder_at scheduled │└───────────────────────┬───────────────────┘│▼ cadence reached┌───────────────────────────────────────────┐│ REMINDER scheduled ││ ▶ respects opt-out + pause flags ││ ▶ optional conversion-promo code ││ ▶ email queued to send │└───────────────────────┬───────────────────┘│▼ customer returns┌───────────────────────────────────────────┐│ LIST-TO-CART conversion ││ ▶ items moved to cart ││ ▶ discount code applied if attached ││ ▶ conversion history row written ││ ▶ next_reminder_at cleared │└───────────────────────────────────────────┘Permissions
Access to the Wishlist 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 Wishlist admin surface. The storefront-side write paths run against the front controller and require an authenticated customer session — never an admin session.
Layer 2 — per-action capability. Within SG-Admin, each Wishlist 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 wishlist ledger | ✔ | ✔ | ✔ |
| View customer wishlist | ✔ | ✔ | ✔ |
| View conversion history | ✔ | ✔ | ✔ |
| Clear customer list | ✔ | — | — |
| Issue or revoke share-token | ✔ | ✔ | — |
| Pause or resume per customer | ✔ | ✔ | — |
| Send reminder now | ✔ | ✔ | — |
| Configure reminder cadence | ✔ | — | — |
| Configure conversion-promo | ✔ | — | — |
| Opt customer out (compliance request) | ✔ | — | — |
Self-protection rules. A wishlist cannot be edited at the item level by an operator — the surface returns a structured rejection. The clear-list path is the only operator-side mutation of saved items, and it is hard delete. A reminder cannot be sent to an opted-out customer — the send-now path silently skips opted-out records and reports the skip count in the response. The share-token revocation cannot be reversed — once revoked, a new token must be issued.
Audit. Every write — clear list, issue or revoke share-token, pause or resume, send reminder now, configure cadence, configure conversion-promo, compliance opt-out — emits an Activity Log entry. The log records the acting operator, the wishlist identifier (and customer identifier), and the change shape. Compliance opt-outs write a dedicated event type for audit clarity.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │ (storefront paths use customer└─────────────┬─────────────┘ session, separate controller)│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │ (custom roles override defaults)└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ item-edit / send-to-opted-out /│ │ revoke-revoke → reject or skip└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log + conversion historyRelated references
- Customers — Reference. Each wishlist binds to a customer record. The customer's opt-out flag and email-engagement state cascade here.
- Products — Reference. Wishlist items reference products. Price changes, inventory changes, and product retirement all reflect in the storefront wishlist view (with appropriate markers).
- Discounts — Reference. The conversion-promo path generates one-time discount codes from the Discounts engine. The handoff is a coupon record scoped to the conversion URL.
- Emails — Reference. Reminder templates live there. Cadence and content authoring are separate surfaces.
- Customer Segments — Reference. Send-reminder-now can target a segment rather than an individual wishlist. The segment definition lives there.
- Orders — Reference. The conversion-history rows reference order identifiers for paid outcomes. Refunds write a reversing marker into the history.
- Activity Log — Reference. Compliance opt-outs, share-token revocations, and clear-list actions surface here with dedicated event types for audit.
- Settings — Reference. Owns the global reminder cadence defaults, the share-token expiration window, and the live-price-recompute rule. Changes there reshape the Wishlist behavior.
/docs/wishlist.