Gift Cards v26.1+

Maho's built-in Gift Card module provides a complete solution for selling, managing, and redeeming gift cards in your e-commerce store. Gift cards can be purchased as products, sent to recipients via email, and used as payment during checkout.

Overview

The Gift Card module enables:

• Selling gift cards as virtual products with fixed or custom amounts
• Multi-channel delivery via email with optional scheduling, QR codes, and barcodes
• Flexible redemption at checkout with partial balance support
• Full order lifecycle integration including invoices, credit memos, and refunds
• Complete admin management with history tracking and batch operations
• Multi-store and multi-currency support with automatic currency conversion

Key Benefits

For Store Owners

• Increased revenue through gift card sales and breakage (unused balances)
• Customer acquisition as gift recipients become new customers
• Cash flow improvement with upfront payment before redemption
• Reduced fraud compared to discount codes through unique, trackable codes

For Customers

• Easy gifting with personalized messages and scheduled delivery
• Flexible spending with partial redemption and balance tracking
• Multiple payment options by combining gift cards with other payment methods
• Instant delivery via email for last-minute gifts

For Administrators

• Complete visibility with audit trails and balance history
• Bulk operations for creating, printing, and managing gift cards
• Automatic expiration handling via scheduled cron jobs
• Seamless integration with existing order and payment workflows

Configuration

Navigate to System > Configuration > Sales > Gift Cards to configure the module.

General Settings

Email Settings

Creating Gift Card Products

Gift cards are a special product type that generates redeemable codes when purchased.

Step 1: Create the Product

1. Go to Catalog > Manage Products
2. Click Add Product
3. Select Gift Card as the product type
4. Complete the standard product information (name, SKU, description, etc.)

Step 2: Configure Gift Card Options

In the Gift Card tab, configure these settings:

Amount Type

Amount Settings

Additional Options

Step 3: Set Pricing and Inventory

• Price: Set to the minimum available amount (displayed as "From $X")
• Stock: Configure inventory quantity as needed
• Tax Class: Configure based on your jurisdiction's gift card tax rules

Purchasing Gift Cards (Customer Experience)

Adding to Cart

When customers view a gift card product, they see:

1. Amount selection - Dropdown of fixed amounts or custom entry field
2. Recipient information - Name and email for delivery
3. Sender information - Name and optional email
4. Gift message - Personal message (if enabled)
5. Delivery date - Optional scheduled delivery

┌─────────────────────────────────────────┐
│  Gift Card Amount: [▼ $50.00        ]   │
│                                         │
│  Recipient Name:   [________________]   │
│  Recipient Email:  [________________]   │
│                                         │
│  Your Name:        [________________]   │
│  Your Email:       [________________]   │
│                                         │
│  Gift Message:                          │
│  [                                  ]   │
│  [                                  ]   │
│                                         │
│  Delivery Date:    [____/____/____]     │
│                                         │
│         [ Add to Cart ]                 │
└─────────────────────────────────────────┘

Cart and Checkout Display

Gift cards appear in the cart with their selected options:

• Amount selected
• Recipient name and email
• Sender name
• Gift message (if provided)
• Scheduled delivery date (if set)

Gift Card Delivery

After the order is invoiced:

1. Immediate delivery: Email sent right away if no delivery date specified
2. Scheduled delivery: Email sent on the specified date via cron job

Email contents:

• Gift card code
• Current balance
• Sender name and message
• QR code and/or barcode (if enabled)
• Store information and redemption instructions

Redeeming Gift Cards (Customer Experience)

Applying at Checkout

Customers can apply gift cards in multiple locations:

Cart Page

A gift card entry form appears in the cart totals section:

┌─────────────────────────────────────────┐
│  Gift Card Code: [________________]     │
│                  [ Apply ]              │
│                                         │
│  Applied Gift Cards:                    │
│  ✓ GC-XXXX-XXXX-XXXX  $50.00 [Remove]  │
│                                         │
│  Gift Card Total:          -$50.00      │
└─────────────────────────────────────────┘

Checkout Payment Step

Gift cards can also be applied during the payment step:

┌─────────────────────────────────────────┐
│  Have a Gift Card?                      │
│  [________________] [ Apply ]           │
│                                         │
│  Applied:                               │
│  • GC-XX...XXXX: $50.00                │
│                                         │
│  Subtotal:              $175.00         │
│  Gift Card Discount:    -$50.00         │
│  Amount Due:            $125.00         │
└─────────────────────────────────────────┘

Balance Check

Customers can check their gift card balance without applying it:

1. Enter the gift card code
2. Click "Check Balance"
3. View current balance and expiration date

Partial Redemption

Gift cards support partial redemption:

• If the gift card balance exceeds the order total, only the needed amount is deducted
• Remaining balance stays on the gift card for future use
• Multiple gift cards can be combined on a single order

Full Coverage

When gift cards fully cover the order total (remaining balance ≤ $0.01):

• The "Free" payment method is automatically activated
• Gift cards work as a pre-payment discount, not a selectable payment method
• No additional payment is required
• Order completes with the free payment method

Admin Gift Card Management

The admin interface for gift cards is located in the Sales menu:

• Sales > Gift Cards > Manage Gift Cards - Create, view, edit, and manage individual gift cards
• Sales > Gift Cards > Gift Card History - View transaction history for all gift cards

Gift card configuration settings are found at: - System > Configuration > Sales > Gift Cards - Module settings, code format, expiration defaults

Gift card information also appears within order, invoice, and credit memo views when applicable.

Managing Gift Cards

Navigate to Sales > Gift Cards > Manage Gift Cards to access the gift card grid.

Grid Columns

Available Actions

• View/Edit - Open gift card details
• Delete - Remove gift card permanently
• Mass Delete - Delete multiple selected gift cards
• Mass Status Change - Change status of multiple gift cards
• Print PDF - Generate printable PDF
• Send Email - Send or resend notification email

Creating Gift Cards Manually

Administrators can create gift cards without a purchase:

1. Click Add New Gift Card
2. Fill in the details:
3. Code: Leave blank for auto-generation or enter custom code
4. Status: Set to Active for immediate use
5. Website: Select the website (cannot be changed later)
6. Balance: Enter the gift card value
7. Recipient/Sender Info: Optional delivery details
8. Expiration Date: Optional expiration
9. Comment: Internal note for audit trail

Editing Gift Cards

Open any gift card from the grid to access the edit form.

Form Fields

Action Buttons

When viewing an existing gift card, these buttons are available:

• Save Gift Card - Save changes and return to grid
• Delete Gift Card - Permanently remove the gift card
• Save and Continue Edit - Save and stay on the edit page
• Print PDF - Generate printable PDF with code, QR code, and barcode
• Send Email - Send notification email to recipient (only if recipient email is set)

Viewing Gift Card History

Navigate to Sales > Gift Cards > Gift Card History to view transaction history for all gift cards.

The history grid shows all gift card transactions across your store. Click any row to jump to that gift card's edit page.

History Grid Columns

History Entry Types

Printing Gift Cards

Generate printable PDFs for physical delivery:

Single Gift Card

1. Open the gift card in edit mode
2. Click Print PDF button
3. PDF downloads with code, balance, QR code, and barcode

Batch Printing

1. Select multiple gift cards in the grid
2. Choose Print PDF from the mass actions dropdown
3. Single PDF downloads with all selected gift cards

Sending Emails

Trigger gift card notification emails:

Immediate Send

1. Open the gift card
2. Click Send Email
3. Email sent immediately to the recipient

Scheduled Send

1. Open the gift card
2. Set the Scheduled Email Date
3. Save the gift card
4. Email will be sent by the cron job at the scheduled time

Order Integration

Viewing Gift Cards in Orders

Gift card information appears in several places when viewing orders in the admin panel:

Order View Page (Sales > Orders > View Order)

When viewing an order that was paid with gift cards, you'll see:

• Order Totals Section: Gift card discount line showing the applied amount

  Subtotal:                    $175.00
  Shipping & Handling:          $10.00
  Tax:                          $15.00
  Gift Card (GC-XX...XXXX):    -$50.00
  ─────────────────────────────────────
  Grand Total:                 $150.00
  

• Payment Information Section: Lists the applied gift card codes with amounts

• Multiple gift cards are shown individually if more than one was used

Invoice View

Invoices display the gift card amount in the totals section, showing how much of the invoice was covered by gift cards.

Credit Memo View

Credit memos show: - The proportional gift card refund amount in the totals - "Refund to Gift Card" field when creating the credit memo

Invoice Processing

When creating an invoice for an order with gift cards:

• Gift card purchases: New gift cards are generated when the invoice is paid
• Gift card payments: The applied amount is shown in invoice totals

Credit Memo Processing

When creating a credit memo:

Orders Paid Partially with Gift Cards

• Refund is proportionally distributed between gift card and other payment methods
• Gift card balance is restored for the gift card portion

Orders Fully Paid with Gift Cards

• Enter the refund amount in the Refund to Gift Card field
• Amount is added back to the customer's gift card balance
• Gift card status changes from "Used" back to "Active" if applicable

Expiration Handling on Refunds

When refunding to a gift card, the system automatically extends the expiration date if needed:

• If the gift card is expired or will expire within the configured extension period, the expiration is extended
• The extension ensures the customer has at least the configured number of days (default: 30) to use the refunded balance
• Gift cards with more time remaining than the extension period keep their original expiration date
• The extension is recorded in the gift card history for audit purposes

┌─────────────────────────────────────────┐
│  Credit Memo Totals                     │
│                                         │
│  Subtotal:                    $100.00   │
│  Refund to Gift Card:        [$50.00]   │
│  Refund to Store Credit:     [$50.00]   │
│                                         │
│  Grand Total:                 $100.00   │
└─────────────────────────────────────────┘

Order Cancellation

When an order paid with gift cards is canceled:

• Gift card balance is automatically restored for the full amount
• Gift card status changes from "Used" back to "Active" (if applicable)
• Expiration handling follows the same rules as credit memo refunds:
• If the gift card is expired or will expire within the configured extension period, the expiration is extended
• The extension ensures the customer has at least the configured number of days (default: 30) to use the restored balance
• Gift cards with more time remaining keep their original expiration date
• History entry is created documenting the cancellation and any expiration extension

Admin Order Creation

When creating orders in the admin panel:

1. Add products to the order
2. In the Gift Card section, enter a code and click Apply
3. Gift card discount appears in order totals
4. Complete the order with remaining balance via other payment method

Multi-Store and Multi-Currency

Website Binding

• Each gift card is permanently assigned to one website at creation
• Gift cards can only be redeemed on their assigned website
• This prevents cross-website balance exploitation

Currency Handling

Gift cards support multi-currency environments:

Example:

• Gift card created on US website: $100.00 USD (base currency)
• Viewed in UK store view: £79.00 GBP (at current exchange rate)
• Customer redeems £50.00 GBP worth
• Balance reduced by equivalent USD amount
• Remaining balance: ~$37.00 USD

Barcode Support

The module supports Code128 barcodes when the optional barcode library is installed.

Installation

Add the barcode package to your project:

composer require picqer/php-barcode-generator

Configuration

1. Enable barcodes in System > Configuration > Sales > Gift Cards > Show Barcode
2. Barcodes will appear on gift cards in emails and PDFs

Gift Card Lifecycle

Understanding how gift cards move through different states:

Statuses

Lifecycle Flow

Purchase → Invoice Paid → Gift Card Created (Active)
                              ↓
                    Customer Redeems (partial)
                              ↓
                    Balance Reduced (still Active)
                              ↓
              ┌───────────────┴───────────────┐
              ↓                               ↓
    Fully Redeemed (Used)           Expires (Expired)
              ↓
    Credit Memo → Refund (Active again)

Automatic Expiration

A daily cron job (runs at 1 AM) automatically:

• Finds all active gift cards past their expiration date
• Changes their status to "Expired"
• Records the expiration in history

Troubleshooting

Gift Card Not Applying

Problem: Customer cannot apply a gift card code.

Possible causes:

• Code is incorrect or has typos
• Gift card is assigned to a different website
• Gift card status is not "Active"
• Gift card has expired
• Gift card balance is zero
• Cart contains only gift card products (circular purchase prevention)

Solution: Check the gift card in admin to verify status, website, balance, and expiration.

Gift Cards Not Created After Purchase

Problem: Customer purchased gift cards but codes weren't generated.

Possible causes:

• Order not yet invoiced
• Invoice not yet paid
• Cron jobs not running

Solution:

1. Verify the order has been invoiced
2. Check invoice payment status
3. Verify cron is running: ./maho cron:run

Emails Not Sending

Problem: Gift card notification emails are not being delivered.

Possible causes:

• No recipient email on gift card
• Email scheduled for future delivery
• Email queue not processing
• SMTP configuration issues

Solution:

1. Check gift card has recipient email set
2. Check email_scheduled_at vs email_sent_at timestamps
3. Verify email cron job is running (every 5 minutes)
4. Check email logs for delivery errors

Balance Conversion Issues

Problem: Gift card balance appears incorrect in different currencies.

Possible causes:

• Exchange rates not configured
• Exchange rates out of date

Solution:

1. Go to System > Currency > Rates
2. Import current exchange rates
3. Verify rates are correct for your currencies

Gift Card Discount Not Applying

Problem: Gift card discount doesn't appear in order totals.

Possible causes:

• Gift card code not applied correctly
• Gift card module disabled
• Gift card assigned to different website

Solution:

1. Verify the gift card code was successfully applied in cart or checkout
2. Check that applied gift cards appear in the order totals section
3. For full coverage orders (≤ $0.01 remaining), the "Free" payment method should be available
4. Verify the gift card module is enabled in configuration

Best Practices

Security

• Never display full codes in admin grids or customer-facing areas (use masked display)
• Enable rate limiting to prevent code enumeration attacks
• Regularly audit gift card history for suspicious activity
• Set reasonable expiration dates to manage liability

Operations

• Monitor breakage (unused balances) as a business metric
• Set up alerts for high-value gift card transactions
• Regular reconciliation of gift card balances vs. revenue
• Document manual adjustments with clear comments

Customer Experience

• Clear redemption instructions in gift card emails
• Balance visibility on account dashboard
• Multiple redemption options (cart page, checkout, account)
• Prompt delivery of gift card emails

Further Reading

• Gift Cards Developer Guide - Technical reference for developers
• Email Automation
• Product Types