Gift Card Module

The Gift Card module in Maho provides a comprehensive system for selling and redeeming digital and physical gift vouchers. It introduces a specialized product type, automated code generation, balance management, and integration with the sales checkout process.

Gift Card Product Type

The module implements a custom product type that allows merchants to define how gift cards are priced and delivered. Unlike standard products, Gift Cards require additional customer input (recipient details, sender information, and optional messages) during the "Add to Cart" process.

Pricing Models

The Gift Card product supports three distinct pricing configurations:

1. Fixed: The merchant defines a set of specific amounts (e.g., $25, $50, $100) that the customer can choose from.
2. Custom: The customer enters any amount within a merchant-defined minimum and maximum range.
3. Combined: Provides a dropdown of fixed amounts plus an "Other Amount" option for custom entry.

Technical Implementation: Product View

The frontend rendering is handled by blocks that manage the logic for displaying available amounts and retrieving preconfigured values if a customer is editing a gift card already in their cart. This behavior is similar to other composite types like Configurable products app/code/core/Mage/Catalog/Model/Product/Type/Configurable.php18-20 or Bundle products app/code/core/Mage/Bundle/Model/Product/Type.php13-20 which also require custom option handling and configuration during the view and checkout phases.

Feature	Code Entity / Logic
Product Type	Maho_Giftcard_Model_Product_Type_Giftcard
Price Model	Custom price logic (similar to Mage_Catalog_Model_Product_Type_Configurable_Price)
Data Capture	Recipient Name/Email, Sender Name/Email, Message, Delivery Date
Validation	Frontend validation for required fields and email formats

Sources: app/code/core/Mage/Catalog/Model/Product/Type/Configurable.php18-20 app/code/core/Mage/Bundle/Model/Product/Type.php13-20 app/code/core/Mage/Catalog/Model/Product/Type/Configurable/Price.php23-41

Code Generation and Redemption

Gift card codes are unique identifiers generated upon order fulfillment. These codes are linked to a specific balance and can be redeemed by customers during the checkout process or added to their account balance.

Redemption Flow

When a customer applies a gift card code:

1. The system validates the code existence and active status.
2. The available balance is checked against the current quote total.
3. A "Gift Card" total is added to the quote, reducing the grand_total.
4. The balance is "held" during the checkout session to prevent double-spending.

Logic Association Diagram

The following diagram shows the relationship between the Gift Card entities and the core Sales architecture, bridging the product logic to the persistence layers.

Title: Gift Card Data Association

Sources: app/code/core/Mage/Catalog/Model/Product/Type/Configurable.php111-115 app/code/core/Mage/Bundle/Model/Product/Type.php77-84 app/code/core/Mage/Catalog/Model/Product/Type/Configurable/Price.php148-174

Balance Tracking and Order Integration

Gift cards integrate deeply with the Sales module via "Totals Collectors."

Order Totals Integration

The module registers a total collector that interacts with the Mage_Sales_Model_Quote_Address.

• Quote Calculation: As the cart is updated, the gift card amount is subtracted from the subtotal.
• Order Placement: Upon successful order placement, the gift card account balance is permanently reduced.
• Refunds: If an order paid via gift card is refunded (Credit Memo), the module can return the balance to the original gift card. This is reflected in the PDF and admin views for Credit Memos app/code/core/Mage/Sales/Block/Order/Pdf/Creditmemo.php201-215

Technical Flow: Purchase to Generation

The generation of the gift card account typically occurs during the invoicing process. The system ensures that related order objects are saved in a single transaction to maintain data integrity app/code/core/Mage/Adminhtml/controllers/Sales/Order/ShipmentController.php95-101

Title: Gift Card Lifecycle Flow

Sources: app/code/core/Mage/Adminhtml/controllers/Sales/Order/ShipmentController.php95-104 app/code/core/Mage/Sales/Block/Order/Pdf/Invoice.php177-191

Email Notifications

The module utilizes the Maho Email System to notify recipients.

1. Trigger: Notification is typically sent when the Invoice is generated and transition to a "Paid" state occurs.
2. Templates: Standard Maho email templates are used, allowing for HTML customization.
3. Variables: Templates have access to the Sender Name, Recipient Name, Gift Card Code, Balance, and the custom Message entered by the customer during the purchase.

Comparison with Composite Products

The Gift Card product type shares architectural patterns with other complex types in Maho.

Key Similarities:

• Configurable Products: Both use specialized price models to calculate the final price based on selected attributes or options app/code/core/Mage/Catalog/Model/Product/Type/Configurable/Price.php23-41
• Bundle Products: Both can influence the SKU and weight of the item in the cart based on user selection app/code/core/Mage/Bundle/Model/Product/Type.php123-142
• Virtual/Downloadable: Like Virtual products app/code/core/Mage/Downloadable/Model/Product/Type.php13-14 Gift Cards do not require physical shipping unless a physical card option is selected.

Key Differences:

• Account Generation: Unlike standard products, Gift Cards create a new record in maho_giftcard_account upon fulfillment.
• Totals Integration: Gift Cards act as a payment method in the totals collection, similar to how discounts are applied, whereas standard products only contribute to the subtotal.

Sources: app/code/core/Mage/Catalog/Model/Product/Type/Configurable.php18-76 app/code/core/Mage/Bundle/Model/Product/Type.php13-70 app/code/core/Mage/Catalog/Model/Product/Type/Configurable/Price.php13-50 app/code/core/Mage/Sales/Block/Order/Pdf/Creditmemo.php201-215