Skip to content

README.md

Latest commit

 

History

History
198 lines (156 loc) · 7.63 KB

README.md

File metadata and controls

198 lines (156 loc) · 7.63 KB

Market_GiftCard

Warning

This module is currently under active development and is not yet complete. It is not recommended for use in production environments. APIs, database schema, and behaviour may change without notice until a stable release is published.

Magento 2 module that adds a dedicated Gift Card product type. Merchants can create gift card products with fixed or custom amounts. Customers purchase gift cards, enter recipient details, and the system tracks balances and usage history across orders.

Overview

The giftcard product type extends Virtual and introduces three buy-request options: recipient name, recipient email, and amount. When custom amounts are enabled via the is_custom_allowed attribute, the customer enters their own value at purchase time and the observer overrides the product price before totals are collected.

The module also:

  • Registers giftcard as a first-class product type via product_types.xml.
  • Provides a custom price template (final_price.phtml) that shows "Custom Amount" when the attribute is enabled.
  • Persists gift card options from quote to order via MoveQuoteItemOptionsToOrderItem plugin.
  • Bypasses inventory and qty validation for gift card items since they are generated on demand.
  • Exposes a full repository layer with SearchCriteria support for REST/GraphQL API consumption.
  • Supports GraphQL addProductsToCart via a custom BuyRequestDataProvider using entered_options with a giftcard/ UID prefix.

Architecture

Product Type (giftcard) extends Virtual
    |
    +-- Model\Type\GiftCard                   <- prepareForCartAdvanced, assigns buy request options
    |
    +-- Observer\SetGiftCardCustomPrice       <- sets custom price on sales_quote_collect_totals_before
    |
    +-- Model\Cart\BuyRequest\GiftCardDataProvider  <- GraphQL entered_options -> buy request
    |
    +-- Plugin
    |       +-- MoveQuoteItemOptionsToOrderItem     <- persists options quote -> order
    |       +-- PreventInventoryForGiftCard          <- skips inventory salability check
    |       +-- PreventQtyLookupForGiftCard          <- skips qty validation
    |
    +-- Frontend
    |       +-- templates/product/price/final_price.phtml   <- price display
    |       +-- templates/product/view/type/giftcard.phtml  <- product options form
    |       +-- templates/cart/item/giftcard.phtml           <- cart item renderer
    |
    +-- API
            +-- GiftCardRepositoryInterface          <- CRUD for gift cards
            +-- GiftCardUsageRepositoryInterface      <- usage/redemption history

Installation

Manual

  1. Copy the module to app/code/Market/GiftCard/
  2. Run the following commands:
bin/magento module:enable Market_GiftCard
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

Verify Installation

bin/magento module:status Market_GiftCard

Attribute Details

Property Value
Attribute code is_custom_allowed
Type int
Input select (Yes/No)
Scope Global
Group General
Required Yes
Used in product listing Yes
Apply to giftcard only

Gift Card Options

Each gift card purchase captures three options via the buy request:

Option Constant Description
recipient_name Attributes::OPTION_RECIPIENT_NAME Name of the gift card recipient
recipient_email Attributes::OPTION_RECIPIENT_EMAIL Email of the gift card recipient
amount Attributes::OPTION_AMOUNT Custom amount (when allowed)

Custom Price Handling

When is_custom_allowed is enabled, the SetGiftCardCustomPrice observer listens to sales_quote_collect_totals_before and:

  1. Iterates all quote address items of type giftcard
  2. Reads the amount custom option value
  3. Sets custom_price and original_custom_price on the item
  4. Enables super mode on the product to bypass price validation

GraphQL Support

Gift cards can be added to cart via the standard addProductsToCart mutation using entered_options with a giftcard/ UID prefix:

mutation {
  addProductsToCart(
    cartId: "CART_ID"
    cartItems: [
      {
        sku: "gift-card-sku"
        quantity: 1
        entered_options: [
          {
            uid: "Z2lmdGNhcmQvcmVjaXBpZW50X25hbWU="
            value: "John Doe"
          }
          {
            uid: "Z2lmdGNhcmQvcmVjaXBpZW50X2VtYWls"
            value: "john@example.com"
          }
          {
            uid: "Z2lmdGNhcmQvYW1vdW50"
            value: "50.00"
          }
        ]
      }
    ]
  ) {
    cart {
      items { id quantity product { sku name } }
    }
    user_errors { code message }
  }
}

UID Encoding

Field Raw String Base64 UID
Recipient Name giftcard/recipient_name Z2lmdGNhcmQvcmVjaXBpZW50X25hbWU=
Recipient Email giftcard/recipient_email Z2lmdGNhcmQvcmVjaXBpZW50X2VtYWls
Amount giftcard/amount Z2lmdGNhcmQvYW1vdW50

Database Changes

market_gift_card

Column Type Description
id int Primary key
assigned_customer_id int FK to customer_entity
code varchar(255) Unique gift card code
status int Card status
initial_value decimal(12,4) Original card value
current_value decimal(12,4) Remaining balance
recipient_email varchar(255) Recipient email
recipient_name varchar(255) Recipient name
created_at timestamp Creation timestamp
updated_at timestamp Last update timestamp

market_gift_card_usage

Column Type Description
id int Primary key
gift_card_id int FK to market_gift_card
order_id int FK to sales_order
value_change decimal(20,6) Amount used
notes text Usage notes
created_at timestamp Creation timestamp

Uninstalling

bin/magento module:uninstall Market_GiftCard
bin/magento setup:upgrade
bin/magento cache:flush

This will trigger the revert() method on data patches, removing the is_custom_allowed product attribute. Database tables added via db_schema.xml will also be removed automatically.

Dependencies

  • Magento_Catalog
  • Magento_Sales

License

This module is proprietary software. Unauthorized copying, modification, distribution, or use of this software, in whole or in part, is strictly prohibited without prior written permission from Market.

Copyright (c) 2026 Market. All rights reserved.