Developer Documentation

Gift Selection Promotions

This guide covers the development tasks related to gift selection promotions. These are promotions with a free gift award that must be selected by the customer before Enticify can add it to their basket.

Read this guide to learn the following:

  • How the gift selection process works.
  • How to write code to select or decline a gift.
  • How to set properties on the the gifted line item.

The Gift Selection Process

Following is an outline of the Enticify gift selection process.

  1. You create a gift selection discount using Marketing Manager.
  2. You implement an IGiftSelector and register it with Enticify.
  3. The customer adds items to their basket and meets the promotion condition and eligibility requirements.
  4. Enticify calls your IGiftSelector asking you to select the gift.
  5. If the customer has not selected for this promotion before:
    • You return a SelectGiftLaterResponse.
    • Enticify finishes applying promotions (and assumes the gift selection will apply).
    • You do not use or display the resultant basket.
    • You ask the customer to select from the list of gifts provided to your IGiftSelector.
    • The customer can select a gift OR decline the promotion.
    • You store their selection for this promotion.
    • You run the basket again.
    • Go back to step 4.
  6. If the customer has selected the gift for this promotion:
    • You return GiftSelectedResponse with the selected GiftInfo.
    • Enticify adds the selected gift to the customer basket.
    • Enticify calls your IAutoAddedLineItemUpdater so you can set properties on the line.
  7. If the customer has declined the gift for this promotion:
    • You return GiftDeclinedResponse.
    • Enticify does not apply this promotion.
    • Enticify continues with other promotions.

Considerations when using the results of a pipeline run if you answer any IGiftSelector.TrySelectGift call with SelectGiftLaterResponse.

Until the gift choice is made or declined, Enticify considers the basket items that are the condition items of this promotion (i.e. the items the customer had to add to qualify for the gift selection) to be in-use by this promotion. If you have a second promotion running with a lower priority (so it runs after the gift selection) but which targets the same items, it may not apply the correct number of times or at all (depending on how you have configured discount interactions).
If the gift is declined, the condition items will be released and any subsequent promotions will apply accordingly. If the gift is chosen, the condition items will remain in-use and the subsequent promotion applications will remain unchanged. In practise showing the interim basket will probably be fine, you just need to be aware of this nuance.

Gift Selection Code

To implement gift selection in code, you write a single class that implements IGiftSelector. The steps are as follows:

  • Add a reference to Enticify.CommerceServer.dll.
  • Add a new class to your solution (e.g. MyGiftSelector).
  • Add a using statement for Enticify.Promotions.
  • Add a using statement for Enticify.Promotions.Gifting.
  • Make MyGiftSelector implement IGiftSelector.
  • Implement the logic required to carry out the gift selection process described in the previous section.
  • Register the assembly containing this class with Enticify by calling EnticifyExtensions.RegisterFromAssemblies once in the application on start.

Setting Gifted Line Item Properties

The gift line item is added after some of the standard pipeline components and potentially some of your own custom pipeline components. Therefore, it is important that we provide you with a way to set properties on these freshly minted gift lines.

You need to make sure that all the properties you require are added to the gifted line items. We provide you with the mechanism to do this.

Properties Set by Enticify

When a customer qualifies for the gift with purchase discounts, Enticify creates a new basket line item and sets the following properties on it:

  • 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.

Setting Additional Properties

Do the following to update/set additional properties of the gifted line item immediately after Enticify adds it:

  • Add a reference to Enticify.dll.
  • Add a new class to your solution and add using Enticify.Promotions.Advanced
  • Implement the Enticify interface IAutoAddedGiftLineItemUpdater on your new class.
  • Add & update line item properties in the implemented method UpdateAutoAddedLineItemGift. This is called with the lineItemGift line item dictionary.
  • Register the assembly containing this class with Enticify by calling EnticifyExtensions.RegisterFromAssemblies(assemblies) once in the application on start.

Auto Add Gift Shipping Assignment

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 IAutoAddedGiftLineItemUpdater (as we provide you the OrderForm dictionary).

Identifying Gifted Basket Line Items

We provide a LineItem extension method for this purpose.

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

Adding Variant Gift Lines

The Commerce Server discount product picker does not allow you to pick a product variant. Therefore, you must add the variant id property in your IAutoAddedGiftLineItemUpdater implementation. There are a number of ways we could make this configurable directly in Markerting Manager. Please contact us to discuss this.

The following code demonstrates how you might set the variant id of an auto-added item and allocate the new basket line to a shipment. Note: This example assumes you have a single shipment.