The APIs described in the topic, Implementing a Choice-of-Bonus-Product Discount, are all that you need to implement this discount in your storefront. Use the following to address some common questions.
Q: What if the shopper or basket no longer qualifies for a choice-of-bonus-product discount?
A: If the shopper 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 aren't enough bonus items available? Or what if the bonus products become unavailable while already in the basket or during checkout?
A: When checking out, the application pipeline or 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 aren't
filtered out by BonusDiscountLineItem.getBonusProducts()). SiteGenesis also
shows a message to the shopper on the bonus select page and cart page if a previously selected
bonus product has become unavailable. The shopper can’t check out until they remove the product.
If all bonus products become unavailable during checkout, the promotion doesn't apply in the
shopper'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: You must code your application pipeline or script logic to prevent this. 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. If you configure
your logic properly, this situation can only occur when the merchant decreases the quantity
after a shopper receives the bonus discount. In SiteGenesis, the
ValidateCartForCheckout.ds script checks for this case and prevents the shopper
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 excluded from the list of products returned by
BonusDiscountLineItem.getBonusProducts() and don't 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 a cart with an associated ProductLineitem has a product
that is no longer available, B2C Commerce automatically removes the product.
Q: What if the shopper doesn't select any bonus products or selects fewer bonus items than allowed?
A: You can't force a shopper to accept free items. The storefront provides messages to the
shopper on the cart page, but doesn't prevent checkout. The order ends 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 shopper?
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. Then the price of its bonus
PriceAdjustment is adjusted 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);
}
}else if section.The code works 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 shopper selects bonus products. When the
shopper selects bonus products, B2C Commerce:
PriceAdjustment on each bonus product line item.CouponLineItem.
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 a discount applies, the bonus discount is re-created. For example, a
choice-of-bonus-product discount blocks another promotion from applying due to exclusivity or
rank. By design, there is no way to remove the bonus promotion to let the blocked promotion
apply.