Gift Cards — Reference
The Gift Cards surface is the prepaid-credit plane for SGEN commerce. It owns the redeemable codes a customer can apply at checkout, their balances, their delivery to recipients, and the ledger of partial redemptions that runs them down over time.
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 marketing 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
Gift Cards lives under the Commerce module in SG-Admin. The module renders three primary views — the card list, the per-card detail view with its redemption ledger, and the issuance form — and exposes a small set of write operations for issue, reissue, adjust, expire, and void.
The module is paired by convention: one half renders the views and prepares the card and ledger 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 gift card is a record that carries a redeemable code and a running balance. At checkout the balance is debited; the underlying record persists across redemptions until the balance reaches zero or the expiration date passes. Partial redemption is the default — a card with a balance larger than the cart total spends what it can and retains the remainder.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Commerce → Gift Cards
- URL prefix:
/sg-admin/gift-cards/ - View templates:
application/views/Admin/Commerce/GiftCards/
┌──────────────────────────────────────────────────────────────────────┐$ SG-Admin → Commerce → Gift Cards [ + Issue card ] $├──────────────────────────────────────────────────────────────────────┤│ Code Recipient Initial Balance Status ││ ───────────── ─────────────────── ──────── ──────── ────────────││ GC-4F8A-9C1D maria@example.com $100.00 $42.50 active ││ GC-7B2E-5A39 anonymous $50.00 $0.00 spent ││ GC-1D9F-8E04 ren@example.com $200.00 $200.00 scheduled ││ GC-3C7A-6B11 jen@example.com $25.00 $25.00 expired ││ GC-9E5B-2D7C handed-out at event $75.00 $75.00 active ││ ││ Issued (30d): $4,250.00 · Redeemed (30d): $2,810.40 ││ [ View ] [ Resend ] [ Adjust ] [ Void ] │└──────────────────────────────────────────────────────────────────────┘Actions
The Gift Cards surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List gift cards
Returns the card set paginated, with code (masked except for last segment), recipient, initial value, current balance, and status. Supports filter by status (active, scheduled, spent, expired, voided), by recipient, by date range, and by issuance reason. The default view excludes spent cards older than the retention window — they remain queryable via the explicit filter.
View gift card
Returns the full record for a single card — masked code, full balance, recipient details, delivery method, scheduled-send timestamp if applicable, expiration policy, and the redemption ledger with one entry per partial spend. The unmasked code is rendered behind an explicit reveal action that records an audit event.
Issue gift card
Creates a new card. Required fields: initial value, currency, recipient (or anonymous), delivery method, expiration policy. Optional fields: scheduled-send timestamp, custom message, issuance reason, internal note. On submit the surface mints a fresh unique code, stores the hashed form alongside a masked preview, persists the record, and returns the identifier. The plaintext code is returned once in the issuance response and is not retrievable later through normal reads.
Bulk issue
Same shape as issue, scoped to a recipient list or a flat count. Used for campaigns, event hand-outs, and bulk corporate gifting. Each card gets its own unique code; the issuance response returns the full set once.
Send to recipient
For cards with a recipient email, dispatches the delivery template through the configured email channel. Includes the unmasked code, the message, and the redemption link. The send is recorded; resends are allowed and audited.
Schedule send
Holds an email-delivery card in a scheduled state until the configured timestamp. The card cannot be redeemed before the scheduled timestamp — pre-redemption attempts return a structured rejection naming the schedule.
Redeem at checkout
The runtime redemption path called by the cart surface. Accepts a code and a target cart, computes the redeemable amount as the lesser of card balance and remaining cart total, debits the card balance, records a redemption ledger entry, and returns the applied amount. Always partial-aware — a single card may cover only part of a cart, and a single cart may stack multiple cards if the storefront allows it.
Refund redemption
Reverses a redemption ledger entry. Used when an order is cancelled or refunded. Re-credits the card balance, writes a reversing ledger entry, and returns the balance to its pre-redemption state. The original entry is retained for audit; reversals are not destructive.
Adjust balance
A dedicated write path. Accepts a signed delta and a reason. Writes the new balance and records a ledger entry with the reason. Used for goodwill credits, corrections, and partner top-ups outside the redemption flow. Adjustments require explicit operator capability — they are not part of the runtime redemption path.
Expire card
Manually moves a card to the expired state ahead of its configured expiration date. Used to retire promotional cards early. Expired cards reject all redemption attempts.
Reactivate card
Reverses an expiration. Available only when the original expiration policy would still allow the card to be active. Adds a ledger entry.
Void card
Hard-disables a card. The balance is set to zero and the card cannot be redeemed, refunded, or reactivated. Used for fraud cases and for cards mailed in error. Void is irreversible and audit-logged with a mandatory reason.
Reveal code
Returns the unmasked code for a single card. Available only to operators with the dedicated reveal capability. Every reveal is audit-logged with the acting operator, the target card, and the time of disclosure.
Data model
A gift card 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. |
code_hash | string | Hashed code. Used for redemption lookup. |
code_masked | string | Display form — visible last segment only. |
initial_value | decimal | Set at issue. Immutable. |
balance | decimal | Current redeemable amount. Updated by redemption, refund, and adjustment. |
currency | string | ISO 4217 code. Set at issue. |
status | enum | scheduled, active, spent, expired, voided. |
recipient_email | string | Optional. Set for email-delivery cards. |
recipient_name | string | Optional. Used in the delivery template. |
message | string | Optional. Custom gifting message. |
delivery_method | enum | email, manual, physical. |
scheduled_send_at | timestamp | Optional. Set for scheduled sends. |
expires_at | timestamp | Optional. Null for non-expiring cards. |
issued_by | integer | Operator identifier or system for automated issuance. |
issuance_reason | string | Free-text or chosen from configured reasons. |
created_at | timestamp | Set on issue, immutable. |
updated_at | timestamp | Touched on state change. |
| Field | Type | Notes |
|---|---|---|
card_id | integer | Foreign key. |
entry_type | enum | redemption, refund, adjustment. |
delta | decimal | Signed. Negative for redemption, positive for refund and credit adjustment. |
order_id | integer | Optional. Set for redemption and refund entries. |
operator_id | integer | Optional. Set for adjustments and operator-driven actions. |
reason | string | Free-text or order reference. |
created_at | timestamp | Set on insert, immutable. |
GIFT CARD RECORD├── id├── code_hash (lookup key, never returned)├── code_masked (display only)├── initial_value (immutable after issue)├── balance (mutable via ledger)├── currency├── status scheduled | active | spent | expired | voided├── recipient email, name, message├── delivery_method email | manual | physical├── scheduled_send_at (optional)├── expires_at (optional)└── issuance metadata issued_by, issuance_reason, timestamps↓ every balance change writesREDEMPTION LEDGER├── entry_type redemption | refund | adjustment├── delta signed├── order_id (for redemptions and refunds)└── operator_id (for adjustments)Permissions
Access to the Gift Cards 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 Gift Cards surface. The runtime redemption path is the single exception — it accepts a partially authenticated session belonging to the customer at checkout.
Layer 2 — per-action capability. Within SG-Admin, each Gift Cards 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 gift cards | ✔ | ✔ | ✔ |
| View gift card (masked) | ✔ | ✔ | ✔ |
| Reveal code | ✔ | — | — |
| Issue gift card | ✔ | ✔ | — |
| Bulk issue | ✔ | — | — |
| Send to recipient | ✔ | ✔ | — |
| Schedule send | ✔ | ✔ | — |
| Refund redemption | ✔ | ✔ | — |
| Adjust balance | ✔ | — | — |
| Expire card | ✔ | — | — |
| Reactivate card | ✔ | — | — |
| Void card | ✔ | — | — |
Self-protection rules. Void cannot be applied to a card with a non-zero balance that has historical redemptions without an explicit reason field. Adjust cannot drive the balance below zero. Reactivate is rejected when the card was voided for fraud (the voiding entry carries a reason class that blocks reactivation).
Audit. Every write — issue, send, refund, adjust, expire, reactivate, void, reveal — emits an Activity Log entry. The log records the acting operator, the target card (masked), and the change shape. Reveal events are logged with a distinct event type so audit reviewers can trace code-disclosure separately from balance changes.
GIFT CARD OPERATION REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth (admin) → reject│ (or checkout session) │ checkout → redemption only└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per action) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ void with balance + no reason → reject│ │ adjust below zero → reject│ │ reactivate fraud-void → reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry + Redemption ledger (where applicable)Related references
- Orders — Reference. Redemption ledger entries reference order identifiers. Order cancellation drives the refund-redemption path on this surface.
- Cart — Reference. The runtime redemption path is invoked from the cart surface at checkout. Stacking rules — whether multiple cards may apply to one cart — are configured there.
- Products — Reference. Gift cards may be sold as products with configurable denominations. Card issuance on purchase is routed through that surface and lands here.
- Customers — Reference. Recipient details on email-delivery cards reference customer records when matched. Anonymous gifts skip the join.
- Email Templates — Reference. The recipient delivery template lives in the email templates surface. Brand and copy are managed there; the send event is recorded here.
- Activity Log — Reference. Stores audit events emitted by Gift Cards writes alongside reveal events.
/docs/commerce/gift-cards.