Things to Know When Upgrading Your E-commerce Site to Kentico 11

• Kentico 11 sites have a maximum limit on the number of enabled products (SKUs), based on the used License Edition (100 for Kentico CMS Base, 500 for Kentico CMS Ultimate, unlimited for Kentico EMS). See the Products page for detailed information.
  • This limitation applies to all version 11 licenses, not just new ones. It will affect you even if you’re upgrading from a version without this restriction.
• All e-commerce fields that store prices or other monetary values now use the decimal data type, with a precision of 18 total digits and 9 decimal places. The changes affect objects such as products, shopping carts, orders, payments, discounts, shipping costs, taxes, currency exchange rates, etc.
  • This change was made to make price calculations more accurate. If you have any customizations related to pricing, you may have to update your code to use the decimal data type. Using var instead of strongly-typed variable declarations can help to avoid situations like this.
• Orders in Kentico 11 use a different data structure and calculation model than in previous versions. As a result, the system does not fully support upgrading or import of existing orders – the final price totals of the orders remain the same, but you may notice inconsistencies when viewing the details of upgraded orders or the values of specific columns in the COM_Order or COM_OrderItem database tables (item prices, various subtotals, discounts, etc.). If you need to keep archives of existing orders with full details, we recommend exporting the order data to an external system or file.
  • The upgrade utility was re-released in early January to lessen the inconsistencies, but it is still not a seamless transition, as orders from version 10 and 11 are not compatible.
• Kentico no longer provides any functionality for collecting and tracking donations. The Donation product representation was removed for SKUs, along with all related web parts (Donate, Donations), and reports. When upgrading to Kentico 11, any existing Donation products are converted to Standard products. See Collecting donations to learn about the current recommendations for managing donations.
  • We recommend using a 3^rd party service, such as PayPal, for collecting donations in Kentico 11.
• The system no longer allows users to input prices with more decimal places than allowed by the site's main currency. This should no longer be necessary as a workaround for tax calculations – the system can now be configured to store and process price values that already include tax.
• The supported signatures of transformation methods for getting product prices and other related values were changed. Most of the methods can now only be called without parameters. For detailed information, see Reference - Transformation methods (ASCX transformations) and Reference - Macro methods (Text / XML transformations). The related Display price including catalog discounts and Display price including taxes settings were removed.
  • Essentially, values that used to be from parameters are now retrieved automatically based on available data rather than parameters passed to the methods. For example, to retrieve a SKU’s price you can now simply use <%# GetSKUPrice() %> instead of  <%# GetSKUPrice(true, true, "ColumnName") %>
• The final price of purchases is now stored in the new GrandTotal field of shopping cart and order objects instead of the TotalPrice field. Unlike the TotalPrice field, the GrandTotal includes reductions from gift cards. The change affects both the API and macro expressions. When upgrading sites, we recommend replacing occurrences of the TotalPrice field with GrandTotal in macros (for example in invoices and order notification email templates) and in custom code.
  • Because gift card functionality was added, we also had to add this new field to hold the remaining price after Gift Cards have been applied. If you plan on using Gift Cards, please update your macros and custom code to use GrandTotal instead of TotalPrice.
• Shopping cart item objects no longer provide the UnitPriceAfterDiscount, UnitPriceAfterDiscountInMainCurrency, UnitTotalPrice and UnitTotalPriceInMainCurrency properties. The change affects both the API and macro expressions. When upgrading sites, replace occurrences in macros with the UnitPrice (the price of a single item, including catalog discounts) or TotalPrice (the unit price multiplied by the number of items) properties, for example: {% ShoppingCartItem.UnitPrice %}. Instead, you need to work in the shopping cart's currency and use the corresponding properties without the InMainCurrency suffix.
  • Take special note of this if you use a gateway for a payment provider that only deals with a single currency, such as Authorize.NET. In such cases, we recommend that you only offer the payment option when the cart is using the desired currency.
• The IsProductInShoppingCart macro method of shopping cart objects was removed.
  • Now, in order to check if an item is in the shopping cart, you can use Linq to test CartProducts.Any(…). For example, instead of ECommerceContext.CurrentShoppingCart.IsProductInShoppingCart("4fb8469c-882a-4012-ae18-dc19c1d55fcd"), you can use ECommerceContext.CurrentShoppingCart.CartProducts.Any(SKU.SKUGUID=="4fb8469c-882a-4012-ae18-dc19c1d55fcd").
• Kentico 11 introduces many changes that affect the processing of product prices. To ensure that prices are calculated and displayed correctly, always use the appropriate macro methods or ASCX transformation methods rather than directly accessing values from price columns or properties (such as SKUPrice).
  • The data is not always stored exactly how it needs to be displayed. Using the Macro/Transformation methods will ensure that the customers see the values you want them to, according to store configuration.
• When editing orders in the administration interface, the system no longer recalculates the unit prices of existing order items (for example based on the current catalog or volume discounts). Any required changes of unit prices in existing orders need to be done manually by store administrators.
  • Order items will be displayed at the prices they had when the order was created to avoid confusion when reviewing customers’ past orders.
• Currencies that have an empty value in their Decimal places property now allow 2 decimal places by default (in Kentico 10 or older, an empty value did not allow any decimal places).
  • If you still want to have a Currency with 0 decimal places, enter a zero into the Decimal places Currency property of Store configuration, rather than leaving it blank.

Discounts

• Volume discounts now require a Minimum quantity of at least 2 (it is no longer possible to create volume discounts for 1 item). After upgrading to Kentico 11, any volume discounts with a minimum quantity of 1 do not apply.
  • You can use a catalog discount to make a specific item or set of items cheaper
• The TotalDiscount property of shopping cart item objects no longer includes discounts that affect the price of individual product units (catalog and volume discounts), but only applied Buy X Get Y discounts and product coupons. The change affects both the API and macro expressions.
  • The TotalDiscount field of cart items now shows only item-level discounts. You can use the UnitTotalDiscount or UnitDiscountSummary properties for information about unit-level discounts.
• The ShoppingCartCouponCode and HasUsableCoupon properties of shopping cart objects, and the OrderCouponCode property of order objects were removed. The change affects both the API and macro expressions. If you used these properties to display coupon codes on your site's pages, we recommend displaying the related discounts instead as described in Displaying shopping cart details on pages.
  • Since the ability to apply multiple coupons was introduced, these properties have become impractical.
  • If you need to display the Discount coupons themselves, you can implement a custom macro method and parse coupon values from the Order.OrderCouponCodes xml property.
• The Discount coupon web part was renamed to Coupon codes (Display name only) and now requires a transformation to display the applied coupon codes. When upgrading sites that contain the web part, you need to prepare a suitable transformation for your site's design, configure each instance of the web part, and assign the transformation. See Working with coupon codes.
  • Because multiple coupons can be applied now, there were some changes to the web parts dealing with coupon codes. This necessitates a transformation to control how they are rendered.
• If a store manager changes an existing order in the Orders application, the recalculation evaluates the validity of discounts using the date and time when the order was created, not the current time.
  • This should prevent any confusion that could occur if a sale ends or begins between the Order being created and adjusted. This ensures that the prices the Customer saw when submitting the Order persist when the order is processed.
• The following breaking changes affect order discount macro rules:
  • The default Shopping cart contains product and Shopping cart contains products macro rules were removed. Use the new Order contains products rule instead.
    • Check any order discounts you have that might use these shopping cart rules in their ‘additional conditions’ and replace them with the order equivalent.
  • The default Total weight of order is under macro rule was updated to use a different macro condition. When upgrading websites to Kentico 11, you need to re-save any existing conditions using the rule.
    • The inner workings of this method were updated, and in order for that to be reflected on upgraded sites, conditions using this rule must be re-saved. 
  • The ShoppingCart object is no longer available when writing conditions of custom order discount macro rules. Instead, the macro context directly provides properties related to the shopping cart or order calculation, such as Currency, Customer, PaymentOption, ShippingOption, GrandTotal, etc.
    • We tried to make it easier to create macro rules involving cart properties by including them in the context. Now they can be accessed by <fieldname> rather than by ShoppingCart.<fieldname>. However, if you are upgrading from an older version, you will need to update any existing conditions to reflect this change.
  • See Configuring discount rules and Adding a discount rule with a custom method for more information.
• The following breaking changes affect Product coupons:
  • Global product coupons are no longer supported (i.e. product coupons must always be related to a specific site).
    • Product coupons are site-specific now. This does not mean that they cannot be applied to global products (a.k.a. Stand-alone SKUs), only that the coupons themselves cannot be global objects. 
  • The Product coupons application and the related objects now require the Read discounts and Modify discounts permissions for the E-commerce module instead of the Read data and Modify data permissions.
    • These new permissions were added to specifically control the access to Product coupon management. If you wish for editors to access and manage these discounts, you can assign these permissions to a role that the editors are a part of.
  • The system now applies product coupon discounts to individual shopping cart or order items, rather than the shopping cart or order as a whole (affects related properties in macros and the API).
    • The discount from the product coupons is now applied at the item level, rather than to the overall price of the order. While the end result will remain the same for the customer, the values of item-related fields will be different along the way.
  • The DiscountCoupon macro object is no longer available in the context of invoices or e-commerce email templates. After upgrading, invoice configurations and email templates need to be updated. If you wish to display detailed information about applied product coupons, use the DiscountSummary object available for individual ContentTable items.
  • When upgrading to Kentico 11, existing product coupon data is transferred, but without global product coupons and coupons assigned to products using the All products except for these option. See Upgrading to Kentico 11 for details.
    • Coupons that use the "All products except for these" specification must be adjusted to specify the specific products to which they apply.
• The following breaking changes affect Buy X Get Y discounts:
  • The system now applies Buy X Get Y discounts to individual shopping cart or order items, rather than the shopping cart or order as a whole (affects related properties in macros and the API).
    • Information about Buy X Get Y Discounts can now be found in the DiscountSummary and TotalDiscount properties of shopping cart items.
  • The OrderRelatedDiscountSummaryItems macro collection is no longer available in the context of invoices or e-commerce email templates . After upgrading, invoice configurations and email templates need to be updated. If you wish to display detailed information about applied Buy X Get Y discounts, use the DiscountSummary object available for individual ContentTable items.
    • As a result, for invoices and email templates, information about Buy X Get Y discounts can be found in the DiscountSummary objects of each item in the ContentTable. 
  • Buy X Get Y discounts can no longer be displayed on pages using the Shopping cart totals web part. Instead, see the recommendations in Displaying shopping cart details on pages.
    • Because the discounts are on the item-level now, details have to be expressed in the item transformation rather than using a dedicated web part.
• The following breaking changes affect Order discounts:
  • Order discounts are now always percentage-based (i.e. flat value order discounts are no longer supported, use gift cards for this purpose).
    • You can use the new gift card functionality to give customers a flat discount on their orders.
  • When upgrading to Kentico 11, the system converts all flat order discounts to percentage-based and disables them.
    • This makes them inactive, but available for reference.
  • When calculating the price of shopping carts and orders, the system now applies order discounts after other types of discounts, but before adding shipping costs and taxes.
  • Details of individual order discounts applied to the current shopping cart can no longer be displayed on pages using the Shopping cart totals web part. Instead, see the recommendations in Displaying shopping cart details on pages.
    • The Shopping cart totals web part only shows the total of all Order discounts.
    • The Order discount details can be displayed using a macro that iterates through the OrderDiscountSummary property.

Taxes

• Products, departments, and shipping options can now only have one tax class assigned. After upgrading to Kentico 11, only one of the taxes remains assigned for objects that originally had multiple taxes.
• The system no longer stores or displays tax values separately for individual items in shopping carts and orders (only the total overall tax). After upgrading, you may need to update any custom transformations applied to ContentTable data in invoices or e-commerce email templates.
• The ContentTaxesTable and ShippingTaxesTable macro objects are no longer available in the context of invoices or e-commerce email templates. After upgrading, invoice configurations and email templates need to be updated to use the new TaxSummary object instead. If using custom transformations to display the tax items, you need to update the transformation code to use Name and Value properties instead of the original TaxClassDisplayName and TaxSummary.

Payment methods

• The functionality of the default PayPal payment provider was modified. The changes introduce different requirements, configuration steps and settings. Follow the instructions in Configuring PayPal to set up the payment provider in Kentico 11.
  • Most notably, PayPal now requires a PayPal rest API associated with your PayPal account to work.
• The functionality of the default Authorize.Net payment provider was modified. The changes introduce different requirements, limitations and configurations steps. Follow the instructions in Configuring Authorize.NET to set up the payment provider in Kentico 11.
  • Most notably, Authorize.NET only works with a single currency configured in your merchant account, and anyone using a different currency will be charged an incorrect amount. The system can be customized to only display this payment option when the correct currency is selected.
• Due to changes in the custom payment gateway API, any custom payment gateways need to be rewritten for Kentico 11. See Creating a custom payment gateway.
  • There are new interfaces to implement for direct and delayed capture, along with a new way of mapping the provider to the form.
• The provider classes of the default payment gateways were moved to the CMS.Ecommerce assembly and namespace. When upgrading, any payment methods using the original class locations are automatically updated.
  • PayPal: CMS.Ecommerce.CMSPayPalProvider
  • Authorize.Net: CMS.Ecommerce.CMSAuthorizeNetProvider
  • Customer credit: CMS.Ecommerce.CMSCreditPaymentProvider

I wish you the best of luck upgrading your online store to version 11! To prepare further for the upgrade, I recommend that you see the upgrade documentation and the rest of the release notes. You can also check out this article breaking down the structure of Kentico upgrades in general.