Promotions

When configuring promotions for Salesforce B2C Commerce, you can extend your application to meet your unique campaign and promotion requirements using components such as:

  • Business objects: add or change existing campaign, promotion, and promotion qualifier business objects to customize your application.
  • APIs: use the B2C Commerce APIs that are specific for promotions.
  • Templates: add or change templates.

You can implement the following promotion types, which are not included automatically in B2C Commerce:

You can customize your code to show different promotional message on the product detail page, depending on if the product is a qualifying or discounted product (or both) for a promotion for which a customer qualifies. You can use an alternate way to calculate tax for line items in an order, especially if your back-end systems can't handle order-level discounts.

You can use the B2C Commerce APIs and Business Manager to handle qualifiers, such as source codes and coupons.

Bonus products are a special, more complex discount than typical monetary or percentage discounts.

Bonus discounts describe the actual bonus products granted by the promotion rule. The current XML schema supports the definition of SKU lists of bonus products.

You can customize your code to show different promotional message on a product detail page, depending on whether the product is a qualifying or discounted product (or both) for a promotion for which a customer qualifies. This lets you communicate a different message on the qualifying product than on the participating products.

For example, if you wanted to offer a gift with a purchase, you might want to say something like Buy a Sawzall and get a FREE Sawzall Blade Set - $19.99 Value! on qualifying products, and Receive this Blade Set FREE with Purchase of Any Sawzall! on the discounted product. This lets you double the potential exposure for a particular promotion, and hopefully, increase product revenue.

This feature isn't implemented in SiteGenesis. To implement this feature, you must add a custom attribute to handle the message for a qualifying product, and you must change your storefront code to show different promotion messages using specific APIs. If you don't change your storefront code, Salesforce B2C Commerce behaves as before (see Case C in the table below).

Use these methods to show different messages for a promotion on the product detail page, depending on the role the product plays in the promotion (qualifying or discounted).

MethodDescription
PromotionPlan.getProductPromotionsForQualifyingProduct(Product) : CollectionReturns the product promotions for which the specified product is a qualifying, but not a discounted product.
PromotionPlan.getProductPromotionsForDiscountedProduct(Product) : CollectionReturns the product promotions for which the specified product is a discounted (and possibly also a qualifying) product. It also returns promotions where the specified product is a bonus

These methods provide an alternative to PromotionPlan.getProductPromotions(Product) : Collection. See the API documentation for details.

To use the new API methods, you can do the following:

  1. Define a custom attribute on the Promotion object type, for example, calloutMsg2, to hold the callout message relevant for qualifying products. You can use the existing attribute calloutMsg for discounted products.

    • Select Administration > Site Development > System Object Types > promotion > Attribute Definitions tab, use the same parameters as for calloutMsg. Make sure you include your callout message attribute in an Attribute Grouping (click Attribute Grouping tab)
  2. Change all promotions to define two separate callout messages. If you don't want different messages for the two cases, you can simply duplicate the callout message to both attributes.

    • Select site > Merchant Tools > Online Marketing > Promotions > promotion, enter information into the Qualifying Callout Message2 field that you just created.
  3. Change the storefront templates.

    • SiteGenesis currently uses template code such as the following to show information about the highest ranked promotion associated with a product:

    • Replace this method call with code such as the following, which shows one of two different messages, depending on the relation of the product to the promotion:

For more information, see Product Promotions.

These are some ways you can extend Salesforce B2C Commerce to meet your unique campaign and promotion requirements:

If you want to...The implementation might look like...
Display popup storefront ads for a featured campaign
  • Create additional attributes that the merchant or marketer can manage by entering text to be used as a popup window title and HTML to be used to populate the window body.
  • Define the business logic the system will use to determine when, where and which popup ad to show if more than one is defined.
Implement dynamic messaging in the cart for order promotions, such as: Spend X more and be eligible for an additional 10% off
  • Define additional attributes that merchant can use to control message text and identify custom threshold values.
  • Define the business logic used to dynamically calculate how much more a consumer must spend to qualify for an order promotion discount.
  • Define the presentation logic for rendering the dynamic message in the cart.
Map promotions to print catalogs
  • Use the source code framework to implement this functionality, which also lets the merchant trigger the pricing (using price books) and promotions featured in that catalog, and define storefront redirect behavior.
  • Create source codes.
  • Map source codes to promotions, price books.
  • Add a text entry box to the storefront where consumers can provide the catalog source code.
Attach images to promotions as attention grabbers within the storefront
  • Create icons that represent hot deals or free shipping, for example.
  • Map these images to the general image attribute for each promotion.
  • Define the presentation logic and handling of these images in the storefront.
Implement custom landing pages for campaigns or promotions that are featured in email campaigns
  • Create custom landing page content assets.
  • Define logic for rendering content asset on a custom landing page.
  • Share links to custom landing pages with the marketing team.
  • Consider using the source code framework. This framework already contains logic to handle a link that redirects to specified page (custom landing page). Additionally, the link can activate the associated promotions and price books. Analytics for source code conversion is standard functionality.
Modify how promotions are processed
  • Modify the CalculateCart.ds script to meet your requirements.

Modification details will depend on your specific implementation.

Salesforce B2C Commerce can calculate discounts for which a basket almost qualifies. These discounts are called approaching discounts or upsell discounts. The API retrieves the collection of discounts that almost qualify and shows a message for one or more of them in the storefront.

These promotion types have an Alert flag in Business Manager that controls whether customers are notified of the promotion before they fully meet the merchandise conditions:

  • Order: with amount of order merchandise total
  • Shipping: with amount of shipment merchandise total

If the Alert flag is set, you can specify a monetary value threshold that determines how close the customer must be in order to be notified of the discount. If the value is omitted, the customer is alerted as long as their basket is under the discount threshold. For tiered promotions, the alert only triggers for the lowest tier.

Suppose a merchant has three active promotions:

PromotionDescriptionEnable upsellsUpsell threshold
110% off orders over $150true50
220% off orders over $200true75
3Free ground shipping for orders over $200true60

Case 1

A customer has $140 worth of merchandise in their cart, but doesn't qualify for any of the promotions. The API returns all three approaching discounts because the cart is within the thresholds defined by all three promotions.

Case 2

A customer has $150 worth of merchandise in their cart and receives 10% off their order due to Promotion 1. The merchandise total is now $135. The basket is within the threshold for Promotion 2 (here the $150 is used to determine the threshold, not the $135), and so the customer sees the upsell message for Promotion 2:

"Buy $50 more worth of merchandise and receive '20% off orders over $200.00'"

The upsell message says "$50 more worth of merchandise" instead of "$65 more." This is because the merchandise total that is used is after product promotions but before order promotions are considered. Merchants typically don't stack order promotions, so when the customer reaches the threshold for the second promotion, the first no longer applies.

The customer doesn't see upsell message for Promotion 3 because the merchandise total after order discounts is $135, which is less than $140 and therefore not within the threshold range defined by that promotion.

B2C Commerce doesn't consider the exclusivity or rank of promotions in the PromotionPlan during this process. The reason is that the rank of two promotions that are based on the amount of merchandise total is irrelevant if the cart satisfies one condition threshold but not the other. In this case, the cart receives the discount for the promotions whose condition is satisfied, regardless of rank. Only when the cart satisfies the thresholds for both, can rank make a difference.

Additional support is needed for this feature to your storefront application. To help you, we’ve provided this feature in the SiteGenesis application as follows:

  • In the SiteGenesis demo data, all order promotions of type With amount of qualifying products and shipping promotions or With amount of shipment qualifying products have Enable Upsells set to true with thresholds defined.
  • The cart page shows order and shipping promotions for which customers almost qualify.
  • The shipping page shows shipping promotions for which the customer almost qualifies.

Use these APIs to implement approaching discount in your application.

ApproachingDiscount

The API class ApproachingDiscount, which represents a discount that a customer almost qualifies for based on the merchandise in their cart has these methods:

MethodDescription
Discount getDiscount()The discount the customer receives if they add more merchandise to the cart.
Money getConditionThreshold()The amount of merchandise required in the cart in order to receive the discount.
Money getMerchandiseValue()The amount of merchandise in the cart contributing towards the condition threshold (is always less than the condition threshold).
Money getDistanceFromConditionThreshold()The amount of additional money needed in the order or shipment to receive the discount.

DiscountPlan

The API class DiscountPlan, which retrieves the collection of discounts the cart almost qualifies for has these methods:

MethodDescription
Collection getApproachingOrderDiscounts() Gets the collection of order discounts that the LineItemCtnr almost qualifies for based on the merchandise total in the cart. Here almost is controlled by thresholds configured at the promotion level.
Collection getApproachingShippingDiscounts(Shipment shipment, Collection shippingMethods)Gets the collection of shipping discounts that the passed shipment almost qualifies for based on the merchandise total in the shipment. Here almost is controlled by thresholds configured at the promotion level. This method only returns discounts for shipping promotions that apply to one of the passed shipping methods.
Collection getApproachingShippingDiscounts(Shipment shipment, ShippingMethod shippingMethod)Same as before, but filters by only a single shipping method.

B2C Commerce calculates approaching promotions based on DiscountPlan and not the cart directly. DiscountPlan is a formal description of discounts to be applied on a line item. B2C Commerce calculates the discounts themselves based on a specific set of promotions, that is, the PromotionPlan. It only selects approaching discounts from promotions in the original PromotionPlan. Removing discounts from the DiscountPlan has no effect on the approaching discounts returned by the API, and isn't supported.

How the APIs Work

Order promotions - The API retrieves the approaching order discounts of an order. An order can have approaching discounts even if it has actual applied discounts. To determine the approaching discounts, B2C Commerce:

  1. Reviews each non-applied order promotion in the original PromotionPlan with the enable upsells flag on.
  2. Determines if the order is within the condition threshold for the promotion rule by comparing the merchandise total of the DiscountPlan before other order discounts (and after considering any product discounts) against the condition threshold.
  3. If the merchandise total is within the range, includes the promotion in the returned collection. This collection can include multiple order promotions.
  4. Sorts the returned collection by the condition threshold ascending. Merchants typically want to show one promotion that represents the smallest amount of merchandise the customer must add to the cart to get a discount. Some merchants, however, want to show multiple messages. For example: "10% off orders over $200. 20% off orders over $300".

Shipping promotions - Approaching shipping discounts are calculated in a similar way. The API retrieves the approaching shipping discounts for each shipment in an order based on a set of shipping methods. A shipment can have approaching shipping discounts even if it has actual applied shipping discounts. When determining the approaching discounts, B2C Commerce:

  1. Reviews each non-applied shipping promotion in the original PromotionPlan with the enable upsells flag on.
  2. Filters promotions that don't apply to any of the included shipping methods.
  3. For each remaining promotion, determines if the shipment is within the condition threshold for the promotion rule. It determines this by considering the merchandise total of the shipment before other shipping discounts (and after product and prorated order discounts).
  4. Sorts the returned collection by the condition threshold ascending. This collection can include multiple shipping promotions.

Example

Using the API, you can retrieve the list of approaching promotions from within a template and show the appropriate messages, as shown in this example:

The product.xsd schema supports product shipping promotions.

Import and export product shipping promotions that are specified in promotions.xsd support the following elements:

  • <shipping-methods> in ProductPromotionRule.
  • <fixed-price-shipping> and <free-shipping> in SimpleProductDiscount and TieredProductDiscount.

You can create Salesforce B2C Commerce promotions in a B2C Commerce tool (such as Business Manager) and you can access these promotions via the B2C Commerce API.

The AddBonusProductToBasket pipelet enables you to implement a choice of bonus product discount.

You can access B2C Commerce promotions via the scripting API, which provide a well-defined process that identifies, prioritizes and applies promotions, allowing you to:

  1. Manipulate the result of each process step
  2. Implement custom business rules
  3. Expose relevant promotion information

Access to B2C Commerce promotions is via the classes available in the dw.Campaign package.

You can also use the dw.Order package for certain promotion types.

To learn about specific promotion areas, see the Related links section below.

APIs are release-specific and subject to change. Check the API documentation for the release you are using.

You can use the Salesforce B2C Commerce API to search for all products that are eligible for a promotion, whether they are qualifying or discounted. You can search for qualifying products only, discounted products only, or both.

The input parameter, PromotionProductType, used in the Search pipelet and the ProductSearchModel scripting class, enables you to perform this level of search.

  • Valid values for the B2C Commerce Script API parameter are: all, bonus, discounted, parameter, and qualifying.
  • Valid values for the pipelet parameter are all, qualifying, and discounted.

For the Search pipelet, the same product can be returned by all three types of search. This behavior is different than the API methods PromotionPlan.getProductPromotionsForQualifyingProduct(Product) and getProductPromotionsForDiscountedProduct(Product), which never return the same promotion for a given product.

The products returned by this type of product search depend on the class of the promotion and other aspects of its configuration. The rules are listed below.

All Promotion Types

For all promotion types, the promotion must be marked as searchable if you want to search for products using that promotion. A product isn't returned by a product search if it's globally excluded, and the individual promotion doesn't disable global product exclusions.

There are additional rules, as follows, by promotion class:

Product Promotions

For product promotions, a search for qualifying or discounted products returns a product if that product satisfies the qualifying or discounted product rule, respectively.

Order Promotions

For order promotions:

  • A product isn't returned by a search if it satisfies the order promotion excluded products rule.
  • If the promotion has an explicit qualifying product rule (for example, only products in a specific category qualify), a product must satisfy the rule in order to be returned by a qualifying product search.
  • If the promotion doesn't have an explicit qualifying product rule, all products are returned by a qualifying product search.
  • If the order promotion is configured so that discounted products is equal to qualifying products, a discounted product search will return the same products as a qualifying product search. Otherwise, all products participating in the discount are returned by a discounted product search.

Shipping Promotions

For shipping promotions:

  • If the promotion has an explicit qualifying product rule (for example, only products in a specific category qualify), a product must satisfy the rule in order to be returned by a qualifying product search.
  • If the promotion doesn't have an explicit qualifying product rule, all products are returned by a qualifying product search.
  • No products are returned by a discounted product search because this makes no sense for shipping promotions.

You must rebuild the product index for this feature to take effect. Because only promotions marked as searchable are included, if you don't want the behavior to occur, you should explicitly mark all shipping and order promotions as not searchable. In general, if you don't use this feature in the storefront, it's better to mark promotions as not searchable, because setting them to searchable will increases indexing time.

You can use the Salesforce B2C Commerce APIs to show the promotional price of a product on the product detail page or on a product list.

The API provides the calculated price of an item via the getPromotionalPrice method (of the dw.campaign.Promotion class) if there is an applicable item level promotion ($ off, % off, or fixed price promotions without qualifying products only).

The customer will only see promotions for which they are eligible.

To calculate the promotional price, the getPromotionalPrice method uses the current sales price of the product for quantity 1.0, and applies the discount associated with the promotion to this price. If the product price is $14.99, and:

The promotion discount is...The method will return...
10%$13.49
$2$12.99
$10.00 fixed price$10.00

To calculate the promotional price using the second version of the method (getPromotionalPrice(product : Product, optionModel : ProductOptionModel) using the ProductOptionModel parameter, consider a product base price of $15.00 and a selected options surcharge of $5.00.

The promotion discount is...The method will return...
10%$18.00
$2$18.00
$10.00 fixed price$15.00

For percentage discounts, the discount is applied to the option surcharge, and for the other discount types, it only applies to the base product price.

Promotional Price

This class provides the following methods to calculate the promotional price of a product without actually adding the product to the basket and applying the promotion using the PromotionMgr API:

  • getPromotionalPrice(product : Product) : Money
  • getPromotionalPrice(product : Product, optionModel : ProductOptionModel) : Money

These methods are useful on product pages when you want to show the actual product price to the customer. These methods are restricted to simple product promotions without qualifying products and of discount type percentage, amount or fixed price. The methods don't consider the case of multiple promotions applying to a single product. As a result, there might be cases where the returned price doesn't reflect the actual charge to a consumer; but the methods should return accurate values in most scenarios.

Promotion Class

When using the getPromotionClass() method, you should consider the following:

  • A promotion can be combined in the shopping cart with other active product promotions, resulting in a different price reduction. Promotional price isn't considered for product sorting. The API does not consider dependencies between promotions.
  • When implementing this feature, you should consider the currently selected product options. If a product option is selected by the customer, the value of the promotional discount message should be calculated on the total value of the item (which would include surcharges). For example, if the currently selected product options add a surcharge to the product, a "10% off promotion" should also take 10% off the surcharge.

While promotions are evaluated and applied as one step of the basket calculation, other steps are:

  • Determining product prices
  • Calculating taxes
  • Calculating shipping costs

You can use the Salesforce B2C Commerce APIs to calculate and access shipment-level and product-level shipping costs. When using the applyShippingCost method (dw.Order.ShippingMgr Class), for example, the cart calculation script is simple:

You can use the B2C Commerce APIs to access product shipping costs. Product line items can have one dependent shipping line item. This shipping line item represents either the fixed or the surcharged shipping cost for this product line item. The price of the shipping line item is per product unit, and the shipping line item has a quantity field. The product shipping line item only exists if the product has individual shipping cost.

The following sample script accesses the product shipping costs:

The following methods of this class support product shipping discounts:

  • getAdjustedGrossPrice() : Money
  • getAdjustedNetPrice() : Money
  • getAdjustedPrice() : Money
  • getAdjustedTax() : Money
  • getPriceAdjustments() : Collection

Use the methods of this class to return the accumulated value of all shipment shipping line items and all product shipping line items in the shipment. If any of these shipping line items is N/A, the total price is N/A.

With this class, you can create, retrieve, and remove arbitrary shipping price adjustments (that is, price adjustments not controlled by B2C Commerce) and associate those adjustments with a specific shipping line item. This is useful for merchants who use multiple shipping line items to model various types of shipping charges, instead of just the standard shipping line item for all shipping costs.

The methods of this class return the accumulated value of all shipment shipping line items and all product shipping line items in the container. If any of these shipping line items is N/A, the total price is N/A.

You can fetch applicable shipping promotions during checkout using the methods in this class. You can also show potential shipping promotions to the customer during the checkout process.

The SiteGenesis application does not show shipping promotions for unselected shipping methods.

When implementing a choice of bonus product discount, you can use both scripting APIs and pipelets.

Use these B2C Commerce Script API classes to access the choice of bonus product discount feature:

  • dw.order.BonusDiscountLineItem
  • dw.order.LineItemCtnr (getBonusDiscountLineItems())
  • dw.campaign.BonusChoiceDiscount

The AddBonusProductToBasket pipelet adds a bonus product to the basket associated with a specific bonus discount line item. This pipelet doesn't set the price of the bonus product. Salesforce B2C Commerce sets the price of selected bonus products when applying discounts.

Your code must use this pipelet instead of the standard AddProductToBasket pipelet to add bonus items to the basket.

When the ProductLineItem representing the selected bonus product is created using this special pipelet, it acts like a normal ProductLineItem. All normal methods can be called on it.

It is the responsibility of application logic to prevent the line items from being modified unexpectedly. For example, your application shouldn't let the customer change the quantity of the line item in the cart beyond the limits allowed by the discount, or change the product associated with the line item to a non-discounted product.

Using the Salesforce B2C Commerce APIs, you can search for all qualifying/discounted products that are associated with a one or more product promotion and show them in one place on the storefront, giving customers more information and choices to help make better buying decisions.

For example, a storefront home page shows a promotion teaser "Buy 3 Shirts Get 1 Free". When the customer clicks the teaser, a list of all the qualifying shirts appears. Shirts that are sold out are not included on the list. The customer can then refine the list by brand and sort the list by price. An example of refining search results by multiple promotions, is to filter search results to return products that qualify for either a 20% discount or a free bonus item.

This API only works for promotion type Product.

The APIs for Get promotion products are based on storefront search and can therefore be combined with other search refinements such as category, price, brand, and color.

Refining by multiple promotions only works when the feature toggle, Enable Multiple Promotions on Refinements, is enabled. To enalbe the feature toggle, contact Customer Support.

You can programmatically refine by multiple promotions using the following:

  • Pipelet: use the Search pipelet to pass in a promotion ID value.
  • B2C Commerce Script API: use the dw.catalog.ProductSearchModel B2C Commerce Script API to pass in a promotion ID value.
  • Pipeline: use Search URL (in the Search pipeline) for a search result refined by multiple promotions.

The promotion ID is consumed by the Search pipelet and the search result contains only products for both promotions. To refine your search by multiple promotions via, use the promotionID parameter to enter a list of promotion IDs, separated by |, for example, 10%OFF|20%OFF.

The following dw.catalog.ProductSearchModel methods support this feature:

MethodDescription
getProducts() : StringReturns the products in the search results.
getPromotionID() : StringReturns the promotion with the specified ID.
setPromotionIDs(List promotionIDs) : StringSpecifies multiple promotion ids used for the search query. Supports up to 30 promotion IDs.

When using the Search URL sub-pipeline, the value of the URL parameter pmid contains a list of promotion IDs separated by |, for example:

.../search?prefn1=color&prefv1=red|green &pmid=10%OFF|FREE_BONUS

Promotions can have qualifying or discounted products, or both. In many cases, qualifying and discounted products are the same. For the various combinations of promotion types and discount types, products of a promotion are returned by these APIs as follows:

Promotion typeDiscount typeProducts returned

Without qualifying products

With amount of qualifying products

With number of qualifying products

Percent Off

Amount Off

Fixed Price

Percent Off Product Options

Price From Price Book

Fixed Price Shipping

Free Shipping

Discounted products/options

Buy X For Total

n/a

Discounted products

Buy X Get Y

Percent Off

Amount Off

Fixed Price

Price From Price Book

Free

Qualifying and discounted products

Without qualifying products

With amount of qualifying products

With number of qualifying products

Bonus Products

Choice Of Bonus Products

Qualifying products

To use this feature, you must set the promotion to searchable in Business manager. B2C Commerce considers a product promotion to be searchable if its Searchable flag is set to True and if it's active at any time 20 days in the past, any time 20 days in the future, or is currently active in the context of a campaign or A/B test.

When you create a new promotion or update the product rule of an existing promotion, you must perform a full rebuild of the product search index to include the updated promotion details. When the customer searches for a product in the storefront, and B2C Commerce executes a specific promotion ID, B2C Commerce looks for products that have this promotion ID incorporated into their index documents.

Promotion price and price book conditions are evaluated based on the price books assigned to the site at index time. Price books assigned to a session programmatically during run time are not considered.

This is a storefront implementation example:

The Search pipeline supports the pmid (promotion ID) parameter. You can use this in your application to show a promotion within a content asset.

  • Suppose you create a promotion with the following values:

    • ID: 40off-womenfootwear-selected
    • Description: 40% Off dark Women's Shoes priced $50 or more
    • Enabled: Yes
    • Searchable: Yes
    • Promotion Class: Product Without Qualifying Products
    • Discounted Products: Products in category womens-footwear(Footwear) or subcategories, and with price >= $50.00, and with attribute color = black, brown, or navy.
  • Next, you add an image that shows the add called: Save Up To 40% On Select Women's Footwear Styles.

  • Next, you create a content asset (or edit an existing one) to contain a promotion search link as follows:

    /Search-Show?pmid=40off-womenfootwear-selected on the image Save Up To 40% On Select Women's Footwear Styles.

You can use the Salesforce B2C Commerce APIs to run a series of time-based promotions, such as "deal of the day" campaigns, by using methods that retrieve specific promotions within a campaign, based on time.

You can have multiple deal of the day campaigns at the same time (deal of the day, week, month, or year), where the storefront user will see the currently active deal, the number of missed deals, and the number of upcoming deals. Each deal is a promotion. All deals of the day are bundled in a campaign.

  • Use the following methods from the dw.campaign.PromotionMgr class to retrieve promotions by the dates they are active. These methods differ from methods such as getUpcomingPromotions() in that they retrieve promotions assigned to a specific campaign and active within a specific date range, including past dates.
    • getActivePromotionsForCampaign(Campaign campaign, Date from, Date to) : PromotionPlan
    • getActiveCustomerPromotionsForCampaign(Campaign campaign, Date from, Date to) : PromotionPlan
  • Use the following method from the dw.campaign.PromotionPlan class to sort promotions by start date.
    • getPromotions(int sortOrder) : Collection
  • Use the following methods from the dw.campaign.Promotion class to access start and end dates.
    • getStartTime() : Date
    • getEndTime(): Date

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:

MethodDescription
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.)

You can use the Salesforce B2C Commerce APIs for when a promotion is assigned to an A/B test and not to a campaign. These classes return a placeholder campaign, representing A/B tests, for API methods that return or process a campaign instance, when an A/B test (not a campaign) is in effect.

  • dw.campaign.Campaign

  • dw.campaign.CampaignMgr

  • dw.campaign.Promotion

  • dw.campaign.PromotionMgr

    Returned PromotionPlans don't contain multiple Promotion objects with the same ID.

  • dw.campaign.PriceAdjustment

    A/B tests are just another case of a promotion without an associated campaign.

The method Promotion.getCampaign.getCustom isn’t accessible when a promotion is assigned to an A/B test and not a campaign. The method returns an empty map because this object isn't derived from an extensible object. The method promotions.campaign is a dummy object, which is an instance of dw/object/ExtensibleObject.java. When the method promotions.campaign.custom is called, the getCustom method on dw/object/ExtensibleObject.java is called and returns the “ExtensibleObjectAttributes id“ value. When a promotion or price adjustment is the result of an A/B test, the method Promotion.getCampaign.getID() always returns AB Testing.

When a promotion or price adjustment is the result of an A/B test, these methods return the following:

With this method...Returns...
Promotion.getCampaignplaceholder campaign
Promotion.getCouponsempty collection
Promotion.getCustomerGroupsempty collection
Promotion.getSourceCodeGroupsempty collection
Promotion.isBasedOnCouponfalse
Promotion.isBasedOnCouponsfalse
Promotion.isBasedOnCustomerGroupsfalse
Promotion.isBasedOnSourceCodesfalse
PriceAdjustment.getCampaignplaceholder campaign
PriceAdjustment.getCampaignIDID of placeholder campaign
PriceAdjustment.getCouponLineItemnull
PriceAdjustment.isBasedOnCampaigntrue
PriceAdjustment.isBasedOnCouponfalse

A/B Testing

Campaigns and Promotions

Promotion Discounts

Qualifying and Discounted Products

Implementing Choice of Bonus Product(s) Discount

Restricting Promotions to Identical Products