Skip to content

Magento 2 Gift Cards

Gift Cards Cover

Introduction

Magento 2 Gift Cards extension allows customers to buy gift cards of different types while merchants get the ability to configure all necessary options in a flexible and seamless way. The software also generates gift cards that can be used by registered customers and guests. The gift card codes can be redeemed in a separate block both in a shopping cart and during the checkout. The customers can spend the full or participial gift card amount to pay for the ordered items. Any amount of gift cardcodes can be pregenerate whenever needed.

Gift Card Types – choose one of the three types of gift cards:

  • Email Gift Card (a code is sent via email to a recipient)

  • Print-Out Gift Card

  • Mail Gift Card (a physical Gift Card delivered by post office).

Gift Cards Pricing – assign individual values to gift cards using one of the 3 pricing schemes:

  • a fixed price (the gift card value can't be changed)

  • a drop-down with a predefined list of prices

  • a price range (a gift card amount can be chosen within the price range set by the store admin).

Requirements and Installation

Gift Cards supports Open source (Community), Commerce (Enterprise) editions and Commerce cloud. The current version of the Magento installed on your website can be found in the lower right corner of any backend page.

SEO Suite Ultimate has 3 separate ways of installation:

1) Copy the code (ready-to-paste package);
2) Use MageWorx Repository;
3) Use local Composer.

Extension Configuration.

The Gift Card extension allows creating the Gift Card Product acting as the new product type or generate the desired amount of these cards.

Gift Card Product

Log into the Magento Admin panel and go to PRODUCTS ⟶ Inventory ⟶ Catalog. In the upper-right corner on the Add Product menu, click the triangle button and select Gift Card

General Settings

Mageworx Gift Card

It shares the same logic as the creation of the Simple Product.

Mageworx Gift Card

For the Price attribute, put the default one that will be displayed on the product grid. We will define the Gift Card prices later.

Gift Card Information

The Gift Card Product has the special tab Gift Card Information

Mageworx Gift Card Information

From the Giftcards Type drop-down, you can select one of the available gift card kinds:

  1. If Email is chosen, the code is sent via email to a recipient via email.

  2. The Print provides the gift card that can be printed out.

  3. The Offline option lets merchants send the physical gift card by post.

In the Amount field, you can add different gift card prices so your customers will be able to choose a gift card value they want to purchase.

Mageworx Gift Card Values

If several values are selected, the dropdown will appear, allowing to choose the appropriate value. The price from the General Settings will be the default one.


Available for Customer Groups lets you segment your customers’ list, and make gift cards available only for certain groups (e.g. logged in shoppers, retailers, etc).

Expiration Period is used to specify the number of days the Gift code will be valid for.

Allow Open Amount feature allows your customers to enter a custom gift card price within a specified range.

Mageworx Gift Card Types

Mageworx Gift Card Types

The minimum and maximum values for the open amount are shown here.

Mageworx Gift Card Types

If the value typed in by the customer is not included in the price range, the error will be shown.


Your customers can preview how the gift card email will be shown using the Preview link.

Mageworx Gift Card Types

Note that the code here is not shown to avoid possible frauds.



Gift Cards List

Log into the Magento Admin panel and go to MARKETING ⟶ MageWorx Gift Cards ⟶ Gift Cards List

Mageworx Gift Card Types

Please note that during the initial setup this grid will be empty. The values appear once the administrator adds the Gift Cards on this page or the customers purchase the gift card products that are described in the previous section.

To add the new Gift Card, click the Add New Gift Card button on the upper-right corner of the page.

Gift Card Info

Mageworx Gift Card Info

Gift Card Code. At first, this field is grayed out.

Once the Gift Card is saved, it is filled with the genereated code Mageworx Gift Card Info

Giftcards Type allows choosing the proper Gift Card Type:

  1. If Email is chosen, code is sent via email to a recipient.

  2. The Print provides the gift card that can be printed out.

  3. The Offline option lets merchants send the physical gift card by post.

Initial Value is used for specifying the initial balance of the gift card. Once the client starts using the gift card, its value can be decreased and the current balance is shown in the Current Balance field.

The store owner can select the store views where the customer can use the gift card in the Store Views multiselect field.

Mageworx Gift Card Info

Expire Date specifies the date after which the Gift Card becomes invalid.

Available for Customer Groups allows to restrict the ablity to purchase the product using the Gift Card.

Gift Card Status specifies the current Gift Card status:

  • Active (in use, still has some value);

  • Used (was in use, currently doesn't have any value);

  • Inactive (not in use at the moment).



Recipient Info

Mageworx Gift Card Recipient

This allows entering the recipient information. Please not that the administrator can use these options for editing the Gift Cards information as well.

To Name is for the name of the recipient.

To Email is for the email of the recipient.

From Name provides the name of the sender.

Message is a custom Gift Card message that is sent to the recipient.

Gift Cards Grid Actions

Once the Gift Card is created it is shown on the grid. The store administrator can perform several actions with them.

Mageworx Gift Card Actions

The Edit and Delete are pretty straightforward.

As for the Statistics, this provides the ability to monitor the account movements for this particular gift code

Mageworx Gift Card Stats

Once a new order with this particluar code is registered in Magento, it will be shown in this table.

The Resend option initiates the repeat sending of the gift code to the emailentered in the To Email field.

Gift Cards Generate

Log into the Magento Admin panel and go to MARKETING ⟶ MageWorx Gift Cards ⟶ Gift Cards Generate

Mageworx Gift Card Generate



Gift Cards extension allows pre-generating Gift Card codes. You can generate any amount of codes and easily manage them in the back-end.

Mageworx Gift Card Generate

Giftcards Count sets the number of cards created at a time.

Giftcards Amount is used for specifying the initial balance of the gift card.

The store owner can select the store views where the customer can use the gift card in the Store Views multiselect field.

Mageworx Gift Card Generate

Giftcards Type allows choosing the proper Gift Card Type:

  1. If Email is chosen, code is sent to a recipient via email.

  2. The Print provides the gift card that can be printed out.

  3. The Offline option lets merchants send the physical gift card by post.

Expire Date The store administrator can specify the date of the gift code expiration.

Available for Customer Groups allows to restrict the ablity to purchase the product using the Gift Card.

Gift Card Status specifies the current Gift Card status:

  • Active (in use, still has some value);

  • Used (was in use, currently doesn't have any value);

  • Inactive (not in use at the moment).

Gift Cards Configuration

Extension's configuration can be found in STORES ⟶ Configuration ⟶ MAGEWORX ⟶ Gift Cards. The configuration itself consists of 2 tabs.

Gift Cards Defaults

Mageworx Gift Card Configuration

Show on Shopping Cart Page if set to Yes renders the special block where the user can put the gift code

Mageworx Gift Card Configuration

This block provides the possibility to check the card status as well.

Activate Gift Card on Order Status provides the status of the order with the gift card product after which the client can use the Gift code.

We recommend setting the status to Complete to avoid the potential possibility of purchasing products with the gift card that had not been purchased or when the order for that gift card is still in the pending state.

Add Gift Card code to Order Item If this setting is enabled, the gift card code will be visible for the store administrator in the backend.

Mageworx Gift Card Configuration

It shows on the order page and the invoice as well.

Gift Cards Email Options



Mageworx Gift Card Configuration

Use Default Gift Card Picture for Email If no images are uploaded the default one will be provided

Mageworx Gift Card Configuration

The default image

Order Statuses for emailing Gift Card This setting may be useful in conjunction with Activate Gift Card on Order Status setting. For instance, the store owner can allow sending the emails with the gift codes when the order with the gift card product is still in the Pending State, but make the gift code Active only when the order is completed.

Templates provides the possibility to change the default email templates. For this go to MARKETING ⟶ Communications ⟶ Email Templates

Mageworx Gift Card Configuration

Click the Add New Template button.

Mageworx Gift Card Configuration

In the Template dropdown, select the desired template and click the Load Template button. Edit the Template Content and preview the changes by Preview Template button at the top of the page. Once the template is saved, it will be visible in the Templates Dropdown

Mageworx Gift Card Configuration

Frontend Experience

Gift Card Product

Below you can see how the email gift card product looks on the front-end:

Mageworx Gift Card Product

For email gift card you can enter a sender details and a message you want to add to the email with a gift card. The Delivery Date option allows you to schedule the email sending (it might be usefull if you need to send a gift card on a certain date).

Gift Cards Redeem

Gift Cards can be used both by registered customers and guests.

Mageworx Gift Card Redeem

The Gift Cards block can be showed on the cart page (as depicted on the screenshot above) and during the checkout:

Mageworx Gift Card Redeem

The customer can check the gift card status, current balance and the possible expiration date.

Once the gift card is activated, the extension shows the gift card status

Mageworx Gift Card Redeem

Gift Cards in Customer Account

Mageworx Gift Cards extension provides the possibility to check the statuses of the purchased gift cards and the orders that were purchased with the help of the gift codes. The customer should click their name in the header and hit the My Gift Crads List link

Mageworx Gift Card Redeem

Gift Cards List is the list of the gift codes that were purchased by this customer. Please note that if the customer has purchased the gift card and sent it to any other email, it won't show here.

Gift Card Statistics is the table of the orders that were made by the customer with the help of the gift codes.

Gift Cards on the Order View

Customers can observe the used gift cards on the order view pages in the totals section.

Mageworx Gift Card Redeem

This information is visible on the order page and on the Print Order as well.

Import/Export Gift Card Codes

Import/Export in Magento 2 stores

The extension allows you either to import/export the gift card codes between different Magento 2 stores or to migrate the gift card codes created in our Magento 1 extension to your Magento 2 website.

To export or import the gift card codes you should go to System ⟶ Import/Export gift cards by MageWorx section.

Mageworx Gift Card Codes Import/Export

In order to better understand the format of the CSV file with the gift card codes, you can download the example file. For this, click the “Download” link. The format of the example CSV file is as follows:

Mageworx Gift Card Codes Example File

You can export/import all the gift card information you specify in the back-end when creating the gift card code manually. For more details about these fields, please check the section Gift Cards Info.

In order to export the existing gift card codes, you click the “Export” button. The CSV file with all your existing gift card codes will be downloaded. Use this CSV file to copy the gift card codes to a different Magento 2 store (moving the gift card codes from your staging host to the live site, for example). You can also use this file as the backup feature.

If you need to import the codes to your Magento 2 store, the easiest way will be either just to download the example file or the export the existing codes ⟶ adjust the CSV file ⟶ import it.

Note that the structure of the CSV file you need to import should be the same as the one in the example file. Leave columns empty if they are not applicable to you.

The following columns are required for filling:

  • Card Code - the gift card code. If the gift card code with this code exists in your store, it will be updated with the values from the CSV file. If there is no such gift card code yet, it will be created with the parameters from the CSV file.

  • Card Amount - the inital gift card code amount;

  • Card Balance - the remaining gift card code balance;

  • Card Currency - the currency of the gift card code. Enter the currency code here;

  • Card Type - the type of the gift card code: email, offline, print;

  • Card Status - the status of the gift card code: active, inactive, used;

  • Customer ID - this column includes the ID of the customer who purchased a gift card product that generated the particular gift card code. Leave 0 if not applicable;

  • Store Code - the store view codes you want to assign the gift card code to. Add the store view codes separated with the comma here. You can enter ALL if you want to make the gift card available on all store views;

  • Group Name - the customer group names you want to assign the gift card code to. Add the customer groups separated with the comma here. You can enter ALL if you want to make the gift card available for all groups.

The remainng columns are optional for successfull import. The columns with created and modifed dates will be specified automatically during the import process.

Migrate Gift Card Codes from Magento 1

In order to migrate the gift card codes from your Magento 1 store you should follow the next steps,

  • Make sure you've updated our Gift Card extension on your Magento 1 store to the latest version;

  • Go to Customers ⟶ Gift Cards ⟶ Export Gift Cards ⟶ Choose the status, the types and the dates of the codes you need to export ⟶ Export the codes to the CSV file;

  • Go to your back-end of the Magento 2 store ⟶ System ⟶ Import and Export Gift Cards

  • Choose the exported CSV and click on the Import button.

Note that in Magento 1, you should export the gift card codes with the following settings: Value delimiter = "," Enclose Values In = "

PWA themes

The extension out of the box has the integrations with the following PWA themes:

  • Magento 2 Venia

Note

The free compatibility addon must be installed from https://github.com/mageworx/mageworx-gift-cards-veniapwa

Hyvä themes

The extension out of the box has the integrations with Hyvä themes:

Note

The free compatibility addons must be installed. See this link for more details.

GraphQL API

The GraphQL API is added by the free GiftCardsGraphQl addon.

1. The mwGiftCardInfo query returns the information about the Gift Cards.

Query attribute is defined below:

code: String! Gift Card code

By default you can use the following attributes:

status: String @doc(description: "Status")
balance: MwGiftCardBalance @doc(description: "Current Balance")
valid_till: String @doc(description: "Valid till")

MwGiftCardBalance object:

value: Float @doc(description: "Balance Value")
currency_code: String @doc(description: "A three-letter currency code, such as USD or EUR")
label: String @doc(description: "Balance Label")

Request:

{
    mwGiftCardInfo(code: "N8Q48-UWIII-8YGZ7") {
        status
        valid_till
        balance {
            value
            currency_code
            label
        }
    }
}

Response:

{
    "data": {
        "mwGiftCardInfo": {
            "status": "Active",
            "valid_till": "Unlimited",
            "balance": {
                "value": 13.4,
                "currency_code": "USD",
                "label": "$13.40"
            }
        }
    }
}

2. The applyMwGiftCardToCart mutation allows you to add any Gift Card to the cart.

Syntax:

mutation: {applyMwGiftCardToCart(input: ApplyMwGiftCardToCartInput): ApplyMwGiftCardToCartOutput}

The ApplyMwGiftCardToCartInput object must contain the following attributes:

cart_id: String! @doc(description:"The unique ID that identifies the customer's cart")
gift_card_code: String! @doc(description: "Gift Card code")

The ApplyMwGiftCardToCartOutput object contains the Cart object.

cart: Cart! @doc(description: "Describes the contents of the specified shopping cart")

Cart object:

applied_mw_gift_cards: [AppliedMwGiftCards] @doc(description:"An array of applied Gift Cards")

AppliedMwGiftCards object

code: String @doc(description: "Gift Card code")
remaining: MwGiftCardBalance @doc(description: "Remaining balance")
applied: MwGiftCardBalance @doc(description: "Applied balance to the current cart")

MwGiftCardBalance object

value: Float @doc(description: "Balance Value")
currency_code: String @doc(description: "A three-letter currency code, such as USD or EUR")
label: String @doc(description: "Balance Label")

Request:

mutation {
    applyMwGiftCardToCart(
        input: {
            cart_id: "W0UKfmRGFp62p3H47MFfVupsnq1GFUxv"
            gift_card_code: "N8Q48-UWIII-8YGZ7"
        }
    ) {
        cart {
            applied_mw_gift_cards {
                code
                remaining {
                    value
                    currency_code
                    label
                }
                applied {
                    value
                    currency_code
                    label
                }
            }
        }
    }
}

Response:

{
    "data": {
        "applyMwGiftCardToCart": {
            "cart": {
                "applied_mw_gift_cards": [
                    {
                        "code": "N8Q48-UWIII-8YGZ7",
                        "remaining": {
                            "value": 0,
                            "currency_code": "USD",
                            "label": "$0.00"
                        },
                        "applied": {
                            "value": 13.4,
                            "currency_code": "USD",
                            "label": "$13.40"
                        }
                    }
                ]
            }
        }
    }
}

3. The removeMwGiftCardFromCart mutation allows you to remove Gift Card in the cart.

Syntax:

mutation: {removeMwGiftCardFromCart(input: RemoveMwGiftCardToCartInput): RemoveMwGiftCardFromCartOutput}

The RemoveMwGiftCardToCartInput object must contain the following attributes:

cart_id: String! @doc(description:"The unique ID that identifies the customer's cart")
gift_card_code: String! @doc(description: "Gift Card code")

The RemoveMwGiftCardFromCartOutput object contains the Cart object.

cart: Cart! @doc(description: "Describes the contents of the specified shopping cart")

Cart object:

applied_mw_gift_cards: [AppliedMwGiftCards] @doc(description:"An array of applied Gift Cards")

AppliedMwGiftCards object

code: String @doc(description: "Gift Card code")
remaining: MwGiftCardBalance @doc(description: "Remaining balance")
applied: MwGiftCardBalance @doc(description: "Applied balance to the current cart") 

MwGiftCardBalance object

value: Float @doc(description: "Balance Value")
currency_code: String @doc(description: "A three-letter currency code, such as USD or EUR")
label: String @doc(description: "Balance Label")

Request:

mutation {
    removeMwGiftCardFromCart(
        input: {
            cart_id: "W0UKfmRGFp62p3H47MFfVupsnq1GFUxv"
            gift_card_code: "N8Q48-UWIII-8YGZ7"
        }
    ) {
        cart {
            applied_mw_gift_cards {
                code
                remaining {
                    value
                    currency_code
                    label
                }
                applied {
                    value
                    currency_code
                    label
                }
            }
        }
    }
}

Response:

{
    "data": {
        "removeMwGiftCardFromCart": {
            "cart": {
                "applied_mw_gift_cards": null
            }
        }
    }
}

4. Gift Card product

This request allows you to retrieve the information about Mageworx Gift card product.

MageWorxGiftCards implements ProductInterface. The MageWorxGiftCards object contains the following attributes:

mageworx_gc_type: MageWorxGiftCardTypeEnum @doc(description: "Either EMAIL, PRINT, or OFFLINE") 
mageworx_gc_additional_price: [MageWorxGiftCardAdditionalPrice] @doc(description: "Additional Prices")
mageworx_gc_customer_groups: [MageWorxGiftCardCustomerGroup] @doc(description: "Available for Customer Groups") 
mageworx_gc_allow_open_amount: Boolean @doc(description: "Allow Open Amount")
mageworx_gc_open_amount_min: Float @doc(description: "Open Amount Min Value") 
mageworx_gc_open_amount_max: Float @doc(description: "Open Amount Max Value") 
amount_display_mode: Int @doc(description: "Amount Display Mode") amount_placeholder: String @doc(description: "Custom Amount Placeholder") from_name_placeholder: String @doc(description: "From Name Placeholder") to_name_placeholder: String @doc(description: "To Name Placeholder") to_email_placeholder: String @doc(description: "To Email Placeholder") message_placeholder: String @doc(description: "Message Placeholder") 

MageWorxGiftCardAdditionalPrice attributes

value: Float @doc(description: "Additional Price")
label: String @doc(description: "Additional Price Label")

MageWorxGiftCardCustomerGroup attribute

id: Int @doc(description: "Customer Group ID")

Request:

{
  products(filter: { sku: { eq: "MWgift" } }) {
    items {
      name
      ... on MageWorxGiftCards {
      mageworx_gc_type
      mageworx_gc_additional_price 
      {
        value
        label
      }
        mageworx_gc_customer_groups
      {
        id
      }
      mageworx_gc_allow_open_amount
      mageworx_gc_open_amount_min
      mageworx_gc_open_amount_max
      amount_display_mode
      amount_placeholder
      from_name_placeholder
      to_name_placeholder
      to_email_placeholder
      message_placeholder

    }
    }
  }
}

Response:

{
  "data": {
    "products": {
      "items": [
        {
          "name": "MWgift",
          "mageworx_gc_type": "EMAIL",
          "mageworx_gc_additional_price": [
            {
              "value": 30,
              "label": "$30.00"
            }
          ],
          "mageworx_gc_customer_groups": [
            {
              "id": 0
            },
            {
              "id": 1
            }
          ],
          "mageworx_gc_allow_open_amount": false,
          "mageworx_gc_open_amount_min": 20,
          "mageworx_gc_open_amount_max": 30,
          "amount_display_mode": 0,
          "amount_placeholder": "Test amount",
          "from_name_placeholder": "Test \"From Name\" Placeholder",
          "to_name_placeholder": "Test \"To Name\" Placeholder",
          "to_email_placeholder": "Test \"To Email\" Placeholder",
          "message_placeholder": "Test message"
        }
      ]
    }

5. MageWorxGiftCardsCartItem implementation

The MageWorxGiftCardsCartItem object implements CartItemInterface. The MageWorxGiftCardsCartItem object contains the following attributes:

mail_from: String @doc(description: "From Name")
mail_to: String @doc(description: "To Name") 
mail_to_email: String @doc(description: "To E-mail") 
mail_message: String @doc(description: "Message") 
mail_delivery_date: String @doc(description: "Delivery Date") 
customizable_options: [SelectedCustomizableOption] 

Request:

{
  cart(cart_id: "kPi7RAFpz6qNJMEYDmjwXenMWvj5NqSz") {
      items {
        id
        product {
            name
            sku
        }
        quantity
        prices {
            price {
                value
                currency
            }
        }
        ... on MageWorxGiftCardsCartItem {
        mail_from,
        mail_to,
        mail_to_email,
        mail_message,
        mail_delivery_date
        }
    }    
  }
}

Response:

{
    "data": {
        "cart": {
            "items": [
                {
                    "id": "122",
                    "product": {
                        "name": "Fusion Backpack",
                        "sku": "24-MB02"
                    },
                    "quantity": 4,
                    "prices": {
                        "price": {
                            "value": 59,
                            "currency": "USD"
                        }
                    }
                },
                {
                    "id": "123",
                    "product": {
                        "name": "Strive Shoulder Pack",
                        "sku": "24-MB04"
                    },
                    "quantity": 1,
                    "prices": {
                        "price": {
                            "value": 32,
                            "currency": "USD"
                        }
                    }
                },
                {
                    "id": "126",
                    "product": {
                        "name": "MW Gift mail",
                        "sku": "MW-Gift-mail"
                    },
                    "quantity": 4,
                    "prices": {
                        "price": {
                            "value": 5,
                            "currency": "USD"
                        }
                    },
                    "mail_from": "John",
                    "mail_to": "Doe",
                    "mail_to_email": "[email protected]",
                    "mail_message": "Hello, John!!!",
                    "mail_delivery_date": "Jul 8, 2020"
                }
            ]
        }
    }
}

6. The addGiftCardProductsToCart mutation allows you to add any Gift Card Product to the cart.

Syntax:

mutation: {addGiftCardProductsToCart(input: AddGiftCardProductsToCartInput): AddGiftCardProductsToCartOutput}

The AddGiftCardProductsToCartInput object must contain the following attributes:

cart_id: String!
cart_items: [GiftCardProductCartItemInput!]!

GiftCardProductCartItemInput object:

data: CartItemInput!
gift_card_product_options: GiftCardProductOptionsInput
customizable_options:[CustomizableOptionInput!]

GiftCardProductOptionsInput object:

card_amount: String! @doc(description: "Card Value")
card_amount_other: Float @doc(description: "Other Card Value")
mail_from: String @doc(description: "From Name")
mail_to: String @doc(description: "To Name")
mail_to_email: String @doc(description: "To E-mail")
mail_message: String @doc(description: "Message")
mail_delivery_date_user_value: String @doc(description: "Delivery Date")

The AddGiftCardProductsToCartOutput object contains the Cart object:

cart: Cart!

Request:

mutation {
    addGiftCardProductsToCart( 
        input: {
            cart_id: "kPi7RAFpz6qNJMEYDmjwXenMWvj5NqSz"
            cart_items: [
                {
                    data: {
                        quantity: 1
                        sku: "MW-Gift-mail"
                    },
                    gift_card_product_options: 
                    {
                        card_amount: "other_amount"
                        card_amount_other: 5
                        mail_from: "John"
                        mail_to: "Doe"
                        mail_to_email: "[email protected]"
                        mail_message: "Hello, John!!!"
                        mail_delivery_date_user_value: "07/08/2020"
                    }           
                }
            ]
      }
  ) {
    cart {
        items {
            product {
                name
                sku
            }
            quantity
            prices {
                price {
                    value
                    currency
                }
            }
            ... on MageWorxGiftCardsCartItem {
            mail_from,
            mail_to,
            mail_to_email,
            mail_message,
            mail_delivery_date
            }
        }
    }
}
}

Response:

{
    "data": {
        "addGiftCardProductsToCart": {
            "cart": {
                "items": [
                    {
                        "product": {
                            "name": "Strive Shoulder Pack",
                            "sku": "24-MB04"
                        },
                        "quantity": 1,
                        "prices": {
                            "price": {
                                "value": 32,
                                "currency": "USD"
                            }
                        }
                    },
                    {
                        "product": {
                            "name": "MW Gift mail",
                            "sku": "MW-Gift-mail"
                        },
                        "quantity": 4,
                        "prices": {
                            "price": {
                                "value": 5,
                                "currency": "USD"
                            }
                        },
                        "mail_from": "John",
                        "mail_to": "Doe",
                        "mail_to_email": "[email protected]",
                        "mail_message": "Hello, John!!!",
                        "mail_delivery_date": "Jul 8, 2020"
                    }
                ]
            }
        }
    }
}

REST API

The Gift Card web API provides the developers with the means to use the web services that communicate with the Magento system. The list of the Gift Cards API commands can be observed in the webapi.xml file located in app/code/MageWorx/GiftCards/etc/. Note that some API requests may need authorization. Please check this article for more information. The anonymous requests do not need any authorization.

The API supports all the HTTP verbs such as GET (retrieving the information), POST (adding new resource), PUT (replacing existing resource or creating it if the resource isn't found) or DELETE.

The endpoint for these API requests is http://site.com/rest/V1/mw-giftcards/. The cURL can be used for running such requests. The cURL syntax can be found here.

According to the desired business needs, the developer can create, update or delete the particular gift card, get the gift code balance, status and the expiration date and add or remove the gift card to/from the customer.

Create gift card with the specific code

The method needs the admin authorization token.

Request Format

POST /V1/mw-giftcards

Request JSON Example

{
    "giftCard": {
        "card_code": "0XXXX-XXXXX-XXXX0",
        "card_amount": 100,
        "card_status": 1,
        "card_type": 1,
        "storeview_ids": [0],
        "card_status": 1,
        "card_balance": 90,
        "expire_date": "2019-01-31",
        "customer_group_ids": [0],
        "mail_to": "John Doe",
        "mail_to_email": "[email protected]",
        "mail_from": "Store Admin",
        "mail_message": "Thank you, John!"
    }
}

Parameters

Name Required Description
card_code yes Example: "card_code": "0XXXX-XXXXX-XXXX0"
card_amount yes Example: "card_amount": "100"
card_type no 1 for Email, 2 for Print (default value), 3 for Offline
storeview_ids no [0] for all store views (default value), comma-separated IDs for multiple values: [2,5]
card_status no 0 for inactive (default value), 1 - Active, 2 - Used
card_balance no Any numeric value. The default value is equal to the card_amount value
expire_date no Example: "expire_date": "2018-07-31". By default, the value is not set
customer_group_ids no The default Value is [] (no group selected). To enable the Gift Card, put the customer group ID from Customers ⟶ Customer Groups. Comma-separated IDs for multiple values: [0,1]
mail_to no For email gift cards only ("card_type": 1). By default, the value is not set
mail_to_email no For email gift cards only ("card_type": 1). By default, the value is not set
mail_from no For email gift cards only ("card_type": 1). By default, the value is not set
mail_message no For email gift cards only ("card_type": 1). By default, the value is not set

Response JSON example

{
    "id": 13,
    "card_code": "0XXXX-XXXXX-XXXX0",
    "card_currency": "",
    "card_amount": 100,
    "card_balance": 90,
    "card_status": 1,
    "card_type": 1,
    "mail_from": "Store Admin",
    "mail_to": "John Doe",
    "mail_to_email": "[email protected]",
    "mail_message": "Thank you, John!",
    "created_time": "2018-12-03 10:49:45",
    "updated_at": "2018-12-03 10:49:45",
    "storeview_ids": [
        "0"
    ],
    "customer_group_ids": [
        "0"
    ],
    "expire_date": "2019-01-31",
    "expired_email_send": null,
    "expiration_alert_email_send": null
}

Response Parameters

Name Description
id The ID of the created Gift Card
card_currency The currency of the Gift Card
created_time Timestamp when the Gift Card was created
updated_at Timestamp when the Gift Card was modified
expired_email_send Shows whether the expiration email was sent
expiration_alert_email_send Shows whether the expiration alert email was sent

Get gift card by card code

The method needs the admin authorization token.

Request Format

GET /V1/mw-giftcards/{card_code}

Insert the real gift card code here. Example:

GET /V1/mw-giftcards/0XXXX-XXXXX-XXXX0
The Response JSON is the same as when you create the gift card

Delete gift card by card code

The method needs the admin authorization token.

Request Format

DELETE /V1/mw-giftcards/{card_code}

Insert the real gift card code here. Example:

DELETE /V1/mw-giftcards/0XXXX-XXXXX-XXXX0
If the operation was successful, the server returns true.

Update gift card

The method needs the admin authorization token.

Request Format

PUT /V1/mw-giftcards/

The Request and the Response JSONs are the same as when you create the gift card.

When you run the GET /V1/mw-giftcards/0XXXX-XXXXX-XXXX0, you recieve the full response. Modify it according to your needs and send it via the PUT request.

If the operation was successful, the server returns the updated data.

Get gift card balance by card code

The method doesn't need any authorization tokens.

Request Format

GET /V1/mw-giftcards/{card_code}/balance

Insert the real gift card code here. Example:

GET /V1/mw-giftcards/0XXXX-XXXXX-XXXX0/balance
If the operation was successful, the server returns the current Gift Card Balance:

"90.0000"

Get gift card status label by card code

The method doesn't need any authorization token.

Request Format

GET /V1/mw-giftcards/{card_code}/status

Insert the real gift card code here. Example:

GET /V1/mw-giftcards/0XXXX-XXXXX-XXXX0/status
If the operation was successful, the server returns the current Gift Card Status:

"Active"

The Response Values can be: "Active", Inactive, Used.

Get gift card expire date by card code

The method doesn't need any authorization tokens.

Request Format

GET /V1/mw-giftcards/{card_code}/expireDate

Insert the real gift card code here. Example:

GET /V1/mw-giftcards/0XXXX-XXXXX-XXXX0/expireDate
If the operation was successful, the server returns the current Gift Card expiration date:

"2019-01-31"

Add gift card to cart

The method needs the admin authorization token.

Request Format

PUT /V1/carts/{cart_id}/mw-giftcards/{card_code}/

Insert the real gift card code here, the cart_id is the same as the quote_id. Example:

GET /V1/carts/43/mw-giftcards/0XXXX-XXXXX-XXXX0/

If the operation was successful, the server returns true. On the frontend this gift card will be applied to the cart:

Mageworx Gift Card Information

Remove gift card from cart

The method needs the admin authorization token.

Request Format

DELETE /V1/carts/{cart_id}/mw-giftcards/{card_code}/

Insert the real gift card code here, the cart_id is the same as the quote_id. Example:

DELETE /V1/carts/43/mw-giftcards/0XXXX-XXXXX-XXXX0/

If the operation was successful, the server returns true.

Add gift card to cart for some particular customer

The method needs the customer authorization token.

Request Format

PUT /V1/carts/mine/mw-giftcards/{card_code}/

Insert the real gift card code here. Example:

PUT /V1/carts/mine/mw-giftcards/0XXXX-XXXXX-XXXX0/
If the operation was successful, the server returns true. On the frontend this gift card will be applied to the cart:

Mageworx Gift Card Information

Remove gift card from cart for some particular customer

The method needs the customer authorization token.

Request Format

DELETE /V1/carts/mine/mw-giftcards/{card_code}/

Insert the real gift card code here. Example:

DELETE /V1/carts/mine/mw-giftcards/0XXXX-XXXXX-XXXX0/
If the operation was successful, the server returns true.

Add gift card to cart for guest (the customer is not logged in)

The method doesn't need any authorization tokens.

Request Format

PUT /V1/carts/guest-carts/{quote_id_mask}/mw-giftcards/{card_code}/

Insert the real gift card code here. the quote_id_mask can be taken from the quote_id_mask table. Example:

PUT /V1/carts/guest-carts/0d8e0df48c918c1ea7fab443c6c6563e/mw-giftcards/0XXXX-XXXXX-XXXX0/

If the operation was successful, the server returns true. On the frontend this gift card will be applied to the cart:

Mageworx Gift Card Information

Remove gift card from cart for guest (the customer is not logged in)

The method doesn't need any authorization tokens.

Request Format

DELETE /V1/carts/guest-carts/{quote_id_mask}/mw-giftcards/{card_code}/

Insert the real gift card code here. the quote_id_mask can be taken from the quote_id_mask table. Example:

DELETE /V1/carts/guest-carts/0d8e0df48c918c1ea7fab443c6c6563e/mw-giftcards/0XXXX-XXXXX-XXXX0/

If the operation was successful, the server returns true.

Get the gift card data from the order

Magento 2 API supports obtaining the Order Information via the GET request method (use this link and go to salesOrderRepositoryV1). Our extension adds the Gift Card information if the customer used the gift card code when comleting the order.

The endpoint for these API requests is http://site.com/rest/V1/orders/{order_id}/, where the {order_id} should be replaced with the correct ID value.

Response JSON example

{
    ...
    ...
"mageworx_giftcards_details": [
            {
                "id": 105,
                "code": "6PW8L-6EHKO-DYF8E",
                "amount": 44.63,
                "base_amount": 44.63
            }
        ],
        "mageworx_giftcards_description": " Gift Card (6PW8L-6EHKO-DYF8E)",
        "mageworx_giftcards_amount": -44.63,
        "base_mageworx_giftcards_amount": -44.63
}

Our parameters are added in the end of the response, the non-necessary information is omitted.

Response Parameters

Name Description
id The ID of the Gift Card
code The Gift Card code code used
amount The used value of the Gift Card in the selected store currency
base_amount The used value of the Gift Card in the base store currency
mageworx_giftcards_description The Gift Card description
mageworx_giftcards_amount The balance change of the Gift Card in the selected store currency
base_mageworx_giftcards_amount The balance change of the Gift Card in the base store currency

Add gift card product to cart

This method allows adding the gift card product to the cart.

Request Format

POST /index.php/rest/default/V1/carts/mine/items

Payload

{
    "cartItem": {
        "sku": "Gift",
        "qty": 1,
        "quote_id": "10",
        "product_type": "giftcard",
        "product_option": {
            "extension_attributes": {
                "mageworx_giftcard_item_option": {
                    "card_amount": "other_amount",
                    "card_amount_other": 5,
                    "mail_from": "John",
                    "mail_to": "Doe",
                    "mail_to_email": "[email protected]",
                    "mail_message": "Hello, John!!!",
                    "mail_delivery_date_user_value": "07/08/2020"
                }
            }
        }
    }
}

The "card_amount" should be set to one of the predefined gift card amounts. If the gift card product should be added with a custom amount (if enabled), then the "card_amount" should be set to "other amount" and the custom amount should be added in the "card_amount_other" row.

Response JSON example

{
    "item_id": 12,
    "sku": "Gift",
    "qty": 1,
    "name": "Gift",
    "price": 5,
    "product_type": "mageworx_giftcards",
    "quote_id": "10",
    "product_option": {
        "extension_attributes": {
            "mageworx_giftcard_item_option": {
                "card_amount": "5",
                "card_amount_other": 0,
                "mail_from": "John",
                "mail_to": "Doe",
                "mail_to_email": "[email protected]",
                "mail_message": "Hello, John!!!",
                "mail_delivery_date_user_value": "07/08/2020",
                "mail_delivery_date": "Jul 8, 2020"
            }
        }
    }
}

GDPR Notes

The General Data Protection Regulation (GDPR) protects people's personal data. The GDPR is aimed at giving citizens control over their personal data. It simplifies regulations for economic relations with other countries by making the EU procedures standardised.

The regulation makes sure that no personal data is processed unless the user has allowed the processor of personal data to do so. It also enforces the right for people to have their private information no longer accessible by a company.

To match this regulation, MageWorx provides notes how to remove the sensitive information from the websites that have the Gift Card extension installed.

These fields may require data entry when creating a Gift Card Code (either by the store admin or by the customer who is buying a gift card product):

  • from Name

  • to Name

  • to E-mail

  • Message

And these are the corresponding fildes in the mageworx_giftcards_card: table:

  • mail_from

  • mail_to

  • mail_to_email

  • mail_message

To remove this info, follow the instructions below:

Use this command:

UPDATE mageworx_giftcards_card
SET mail_from = NULL, mail_to = NULL, mail_to_email = NULL, mail_message = NULL;

It will annul the values of the mentioned table fields.

This command will annul only those table fields that have a non-null value:

UPDATE mageworx_giftcards_card
SET mail_to_email = NULL
WHERE mail_to_email IS NOT NULL;

Got Questions?

Need help with the extensions? Feel free submit a ticket from https://www.mageworx.com/support/ 



Mageworx offers outstanding services developing custom-tailored solutions for Magento platform to attain your eCommerce objectives. Our professional impassioned team provides profound and custom oriented development of your project in a short timeframe.