Choice-of-Bonus-Product Discount FAQ

The APIs described in Implementing a Choice-of-Bonus-Product Discount are all that you need to implement this discount in your storefront. However, you might have questions about certain storefront scenarios, described here.

Q: What if the customer/basket no longer qualifies for a choice-of-bonus-product-discount?

A: If the customer no longer qualifies for the discount, when Salesforce B2C Commerce applies discounts, it removes the BonusDiscountLineItem and associated selected products. This is similar to how other bonus products are handled and promotions in general.

Q: What if there are not enough bonus items available, bonus products become unavailable while already in the basket or bonus products become unavailable during checkout?

A: When checking out, the application pipeline/script logic validates that there is enough available-to-sell of each item in the basket to place the order. SiteGenesis shows unavailable products on the bonus selection page but prevents their selection. These products will not be filtered out by BonusDiscountLineItem.getBonusProducts()). SiteGenesis also shows a message to the customer on the bonus select page and cart page if a previously selected bonus product has become unavailable, and prevents checkout until the customer removes the product. If all bonus products become unavailable during checkout, the promotion will not apply in the customer's cart. See the answer to the previous question.

Q: What if the number of bonus items in the basket exceeds the configured maximum number of bonus items?

A: The API itself doesn't actually enforce that the number of bonus items selected doesn't exceed the number allowed by the discount. For example, custom code can simply call setQuantity() on a bonus ProductLineItem and increase the number of selected items beyond the maximum. You must code your application pipeline/script logic to prevent this. If the bonus product selection logic properly prevents this from happening, this situation can only occur when the merchant decrements the quantity after a customer has already received the bonus discount. In SiteGenesis, the ValidateCartForCheckout.ds script checks for this case and prevents the customer from placing the order if it happens.

Q: What if a bonus product is no longer assigned to a bonus discount, is offline, not assigned to site, or deleted?

A: These products are then excluded from the list of products returned by BonusDiscountLineItem.getBonusProducts(), and so will not appear on a bonus selection page.

Q: What if a bonus product in the basket is no longer assigned to a bonus discount, is offline, not assigned to site, or deleted?

A: This scenario can only occur if the merchant changes the bonus promotion or products assigned to the bonus promotion after the bonus promotion has been applied. When B2C Commerce applies discounts and there is a BonusDiscountLineItem in the cart with an associated ProductLineitem whose product is no longer available due to the stated scenario, B2C Commerce will automatically remove it.

Q: What if the customer doesn't select any bonus products, though eligible, or the customer selects fewer bonus items than allowed?

A: You can't force a customer to accept free items. The storefront will provide messages to the customer on the cart page, but will not prevent checkout. The order will end up containing a BonusDiscountLineItem with no selected products.

Q: What if I want to show the bonus product's original price in the cart, to indicate the savings to the customer?

A: B2C Commerce sets the price of bonus product line items to $0.00 in the cart. The SiteGenesis script CalculateCart.ds adjusts the price of each bonus ProductLineItem to its price-book price, and adjusts the price of its bonus PriceAdjustment to indicate the savings. The logic is as follows:

if(productLineItem.bonusProductLineItem && product != null)
{ 
	var price : Money = product.priceModel.price;
	productLineItem.setPriceValue(price.valueOrNull);
	var quantity : Quantity = productLineItem.quantity;

	// we assume that a bonus line item has only one price adjustment
	var adjustments : Collection = productLineItem.priceAdjustments;

	if(!adjustments.isEmpty())
	{
		var adjustment : PriceAdjustment = adjustments.iterator().next();
		var adjustmentPrice : Money = price.multiply(quantity.value).multiply(-1.0);
		adjustment.setPriceValue(adjustmentPrice.valueOrNull);
	}
}
Note: This code is in an else if section.

This code will work the same for bonus product line items, regardless of whether the triggering discount was a standard bonus discount or the choice-of-bonus-product discount.

Q: How does B2C Commerce handle coupons with this discount?

A: When a promotion is coupon-based, B2C Commerce generates a PriceAdjustment and associates it with the triggering CouponLineItem. The API provides methods CouponLineItem.getPriceAdjustments() and PriceAdjustment.getCouponLineItem() to navigate this relationship. A coupon in the cart isn't marked as APPLIED unless it actually results in the generation of a PriceAdjustment.

When a choice of bonus product discount is coupon-based, B2C Commerce doesn't associate the BonusDiscountLineItem with the CouponLineItem that triggered the promotion. For example, there is no CouponLineItem.getBonusDiscountLineItems() method. The coupon remains unapplied until the customer selects bonus products. When the customer selects bonus products, B2C Commerce:

  1. Generates a PriceAdjustment on each bonus product line item.
  2. Associates these adjustments with the triggering CouponLineItem.
  3. Marks the coupon as APPLIED.

Q: How would I modify my application to remove a discount from the cart? What are the ramifications?

A: The API provides a method to remove a BonusDiscountLineItem from the cart. However, even if you write custom code to remove a BonusDiscountLineItem from the cart, the next time B2C Commerce applies discounts, the bonus discount will be re-created. Therefore, if a promotion with a choice-of-bonus-product discount blocks another promotion from applying due to exclusivity or rank, there is no way to remove the bonus promotion to let the blocked promotion apply. This is by design.