API: Bonus Promotion Positioning

When you configure bonus product promotions such as Buy any television, and get a free remote control, you might want the free remote to appear immediately after the television in the cart.

By default, Salesforce B2C Commerce sorts bonus products at the end of the cart. If the customer purchases any other merchandise, the free remote will most likely be positioned after the new items. By default, there is no programmatic connection between a bonus product and its qualifying product's product line items through the API.

You can use the following methods, however, to determine the qualifying products that trigger a bonus product for a product promotion that is based on a number of qualifying products. This enables you to show bonus products together with their triggering products in the cart. To activate these methods, you must enable them via a promotion site preference. When this preference is enabled, B2C Commerce consolidates bonus products into a single product line item. These are the methods, located in the dw.order package, and the ProductLineItem class:

Method Description
ProductLineItem getQualifyingProductLineItemForBonusProduct();

Returns the ProductLineItem that qualified the basket for this bonus product. This method is only applicable if the product line item is a bonus product line item, and if the promotion is a product promotion with a number of qualifying products that grants a bonus-product discount.

If these conditions are not met, the method returns null.

If there are multiple product line items that triggered this bonus product, the method returns only the last one by position within the order.

Collection getRelatedBonusProductLineItems();

Returns all bonus product line items for which this line item is a qualifying product line item. This method is usually called when rendering the cart so that bonus products can be shown next to the products that triggered their creation.

SiteGenesis shows bonus products immediately after the qualifying products that triggered their creation with no changes to templates. Bonus products that don't have a clear qualifying product appear at the end of cart.

It isn't possible to import an order in such a way to indicate a connection between a bonus product line item and a qualifying product line item. (The bonus flag isn't included in order export.)