Gift Card Product Type

   —   
As you probably know, there is currently no built-in product type for selling gift cards or vouchers. This article provides you with an implementation of 'Gift Card' product type in Kentico 7 and the option to apply multiple discount coupons to a single order.
Kentico comes with a fantastic e-commerce customization model that allows you to approach requirements which are not covered in the out-of-the-box solution.

Let's take a look at how to use this model in a real-world scenario and the best practices in customizing the built-in e-commerce solution without touching any system objects / files. This is very important in keeping the process of applying hotfixes or upgrading pain free.
 
First of all, here is an import package to download, but before importing it, let's take a look at how the implementation works and try to describe each important part to understand the whole process.
 
NOTE: The Import package was exported from Kentico 7.0.32. In order to import it properly, you can either A.) apply hotfix 7.0.32 or later or B.) extract the .zip package, locate the "cms_info.xml.export" file in the root of the package and change the hotfix number you are currently using in the following section:
 
<Key>hotfixversion</Key>
<Value>32</Value>

 
The package contains the following objects:
  • Document type "E-commerce - Transformations"
    •  Order_ContentTable transformation was customized
  • Form control "KB101 Product type selector"
    •  adds option to work with new product type 'GiftCard'
  • Module "KB101"
    • just a holder to carry custom classes and custom files
  • System table "com.sku"
    •   definition of the "SKUProductType" field was changed to use new form control "KB101 Product type selector"
  • Resource string "com.producttype.giftcard"
 screen1.png            
              
As you can see from the above list, the package will not overwrite any system files or customize any system objects - only the functionality is changed.
 
1.) Create new document(s) of type cms.product and assign it to a product of type 'GiftCard'.
 
screen2.png
 
NOTE: Custom form control "KB101 Product type selector" (located in ~\CMSModules\KB101\FormControls\KB101SelectProductType.ascx) was assigned to the "SKUProductType" field of your product object, allowing you to select the new product type 'GiftCard' with resolved resource string "com.producttype.giftcard" in the UI of CMS Desk.
 
2.) Add the Gift Card product to the shopping cart and step through the checkout process and pay for the order.             
 
screen3.png
 
3.) You can add any number of 'Gift Cards' to a single shopping cart even if they are of another product instance. Each Gift Card will be turned into a separate discount coupon, not immediately after the order is saved, but once the order is paid for (depending on the payment gateway).
 
screen4.png
 
NOTE: This functionality is achieved / implemented in the "SetOrderInfoInternal" method in the ~\CMSModules\KB101\KB101OrderInfoProvider.cs file. Basically, this method ensures that once the order is paid for, the system generates a new discount coupon for each 'Gift Card' product with a unique DiscountCodeName, e.g.:
 
1-8DD7E457-0
 
Following is an explanation of how the coupon code is generated:
 
  •  1   - OrderID (COM_Order table)
  •  8DD7E457 - First 8 characters of the OrderItemGUID (COM_OrderItem table)
  •  0    - order of discount coupon if one 'Gift Card' product is purchased in unit of 2 or more
 
For more information about how to customize built-in methods of the e-commerce solution, please refer to this webinar explaining the basics of the e-commerce customization model.
 
5.) After the order is paid for, the "E-commerce - Order payment notification to customer" e-mail template is sent to the customer. This e-mail has not been customized, but contains code referring the "Ecommerce.Transformations.Order_ContentTable" transformation. This transformation renders the newly generated discount coupon code(s) implemented with the following k# code:
 
where = "DiscountCouponCode LIKE '" order.orderid "-" CartItemGuid.ToString().Split("-")[0].ToUpper() "%'"; coupons = SiteObjects.DiscountCoupons.Where(where); foreach (coupon in coupons) { " Coupon code = " coupon.DiscountCouponCode; }


NOTE: The above is k# code and should be properly enclosed.

The sent e-mail looks like this:
 
screen5.png
 
4.) Now you are ready to use the discount coupon for your next purchase. As you probably know, Kentico by default only allows you to use one discount coupon per order. In order to use several discount coupons per order, we need to customize the solution. For this purpose, without changing the structure of shopping cart, we can take advantage of the built-in field called "ShoppingCartCustomData", which is part of the COM_ShoppingCart and in which we will store information in XML format about the discount coupon(s) used for this purchase. For more information on how to work with the CustomData object, please refer to this webinar. Let’s purchase two gift cards for $100 and one for $50; a total of 3 discount coupons.
 
screen6.png
 
NOTE: This functionality is ensured in the "SetShoppingCartInfoInternal" method in the ~\App_Code\CMSModules\KB101\KB101ShoppingCartInfoProvider.cs file which is internally called by the "EvaluateContentInternal" method.
 
5.) Add a standard product to the shopping cart. Apply the discounts by inserting all of the discount coupons into the coupon box in the first step of the shopping cart. Notice how the total price decreases. After applying 3 x discounts coupon with a total value of $250, the final price should be decreased by $250:
 
screen7.png
 
screen8.png

NOTE: Custom discount calculation is ensured in the "CalculateOrderDiscountInternal" method in the ~\App_Code\CMSModules\KB101\KB101ShoppingCartInfoProvider.cs file.
 
6.) After the order with the applied discount coupons is saved / paid for, the used discount coupons are automatically invalidated in the "SetOrderInternal" method in the ~\App_Code\CMSModules\KB101\KB101ShoppingCartInfoProvider.cs file and cannot not be used anymore.
 
screen9.png
 
NOTE: Invalidation is ensured by setting DiscountCouponValidTo field of the discount coupon in the past.
 
7.) When the order that contains the purchased 'Gift Card' products is deleted, not only are the appropriate discount coupons deleted, but so are orders for which this discount coupon was used. If you do not like this behavior, feel free to adjust it in the "DeleteOrderInfoInternal" method in the ~\App_Code\CMSModules\KB101\KB101OrderInfoProvider.cs file.
 
The above implementation should give you an idea of how to approach such a requirement in Kentico, but still there is a lot of space for improvement. For example, you could generate the discount coupons soon as an order is saved but temporairly disable them until the order is paid for. This will allow you to send the discount coupon to the customer right away, informing them that it will only be active once the order is paid for.

- mr -


Applies to: Kentico 7.x
Share this article on   LinkedIn Google+

Miro Remias

Hi, I am a Product Management Team Lead here at Kentico. My missions i to lead, advise and empower our Product Management team in seeking the product-market fit.