Developer Documentation

Gift with Purchase Development Guide

This guide covers the technical information and development tasks related to simple gift with purchase promotions.

After reading this guide you will understand:

  • The simple gift with purchase promotion lifecycle.
  • The select gift with purchase promotion lifecycle.
  • Why you need an ILineItemUpdater and how to implement one.
  • User interface changes you might need to make to use these features.
  • Answers to commonly asked gift with purchase technical questions.

Gift with Purchase Lifecycle

This section explains the life cycle of different gift with purchase promotions.

Simple Gift with Purchase Lifecyle

This is the lifecycle when there is only one gift (i.e. there is no choice).

  • Customer qualifies for a gift with purchase promotion.
  • We create a new gift line item IDictionary with a CurrentPrice _cy_iadjust_currentprice of 0m.
  • We populate the _product_* properties of gift line item using QueryCatalogInfo.
  • We add the line item to the pipeline order form IDictionary.
  • We call your ILineItemUpdater implementation with the line item and dictionary so you can update them as you require.

Select Gift with Purchase Lifecyle

This is the lifecycle when the customer has a choice of gifts to select from.

  • Customer qualifies for a gift with purchase promotion.
  • We call your IBasketAdditionSelector implementation.
  • You select the gift to add (usually by asking the customer!).
  • We create a new gift line item IDictionary with a CurrentPrice _cy_iadjust_currentprice of 0m.
  • We populate the _product_* properties of gift line item using QueryCatalogInfo.
  • We add the line item to the pipeline order form IDictionary.
  • We call your ILineItemUpdater implementation with the line item and dictionary so you can update them as you require.

Development Tasks

This section details the gift with purchase development tasks.

Develop an ILineItemUpdater

You must implement an ILineItemUpdater for gift with purchase promotions. This is responsible for populating the newly added gift line with any data that you require in the pipelines.

  • Add a reference to Enticify.CommerceServer.dll.
  • Add a new class to your solution and add using Enticify.Promotions.Basket
  • Implement the Enticify interface ILineItemUpdater on your new class.
  • Add & update line item properties in the implemented method UpdateLineItem. For example:
    • Shipments. You may need to assign the new line item to a shipment.
    • Addresses. You may need to assign an address ID etc
    • Variant ID. Depending on how you configure the gift with purchase promotion, you may want to assign a variant ID. See FAQ below for details.
    • Custom. Many Commerce Server sites have custom data stored line items. You will need to set this.
  • Call one of the ExtensionRegistry.ScanAssembliesForExtensions overloads once in the application on start, before Enticify runs for the first time. This class is in the Enticify.Promotions.Advanced namespace.

Example: Set basic shipping properties on new line item.

using System;
using Enticify.Promotions.Basket;
#if MS
using Microsoft.CommerceServer.Runtime;
#else
using CommerceServer.Core.Runtime;
#endif

namespace Enticify.Samples
{
    /// 
    /// Simple example usage of the ILineItemUpater interface.
    /// 
    // ReSharper disable once UnusedMember.Global
    public class ExampleLineItemUpdater : ILineItemUpdater
    {
        public void UpdateLineItem(IDictionary lineItem, IDictionary orderForm)
        {
            if (lineItem == null) throw new ArgumentNullException("lineItem");
            if (orderForm == null) throw new ArgumentNullException("orderForm");

            //Populate the new line item with default shipping method information.
            //DO NOT COPY THIS - IT IS JUST AN EXAMPLE OF SETTING SOME PROPERTIES.
            lineItem["shipping_method_id"] = new Guid("f30e922f-23ea-4fd1-ab98-5bab9048e12b");
            lineItem["shipping_address_id"] = "0000";
        }
    }
}

Develop an IBasketAdditionSelector.

You only need to do this when offering the customer a choice of gift with purchase.

You must implement an IBasketAdditionSelector for gift with purchase promotions that offer a choice of gifts. Read the basket addition selection guide.

Update your Site User Interface as Required

For both types of gift with purchase you'll need to consider the following changes:

  • Required: Remove access to basket line quantity controls. Enticify handles gift line quantity.
  • Required: Remove access to basket line deletion controls. Enticify handles gift line addition and removal.
  • Optional: Make it clear to the customer that the line is a gift.

If you're offering gift with purchase choices, you'll also need to consider the following:

  • Required: Create the gift selection UI so your customers can choose a gift when available.
  • Optional: You will need to store the customer response if you want them to be able to decline a gift (and therefore no longer show your selection UI). This is usually done by storing information in a session cookie. More details.

FAQ

Which properties does Enticify set on the new line item?

We set at least the following:

  • product_catalog - set with the catalog name you specified in the product picker.
  • product_id - set with the product id you specified in the product picker.
  • _cy_iadjust_regularprice - set to 0 (as the item is free).
  • quantity - set to the value you set for the discount Award Limit.
  • index - set with a new Guid identifier for the line.
  • All of the _product_ because we run QueryCatalogInfo on the line.

How can I identify basket line items that were added by a gift with purchase promotion?

We provide a LineItem extension method for this purpose.

  1. Add using statement for Enticify.Promotions
  2. LineItem instances now have method bool IsGiftWithPurchaseAutoAddedLineItem()

Why do I need to assign the line to a shipment?

You will need to assign the auto gifted items to shipments. When using Enticify, shipping components are run before the discounts are applied. Therefore, you will need to assign the auto-added items to a shipment (or create a new shipment if you wish). You can do this inside your ILineItemUpdater (as we provide you the OrderForm dictionary, so you can access the shipments).

** Will the gift be removed if the condition item is out of stock?**

No. However, if you run the Commerce Server CheckInventory pipeline component and remove items from the basket that are out of stock, Enticify will remove the gifted item. In fact, we always remove it at the start of the basket pipeline and then re-add it if applicable.