Customize 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:

• Choice of Bonus Product Discount
• Alert On Approaching Discount

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.

• You can redirect customers programmatically when they enter source codes. See URL Call to Pipeline Start Node for Source Codes.
• You can dynamically map an incoming URL to navigate to a specific page or pages.
• You can configure your coupons so that customers can redeem multiple coupon codes in the same order.

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

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:

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:

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, so the customer sees the upsell message for Promotion 2:

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

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.

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:

DiscountPlan

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

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 after product and order discounts are applied 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.

• BonusDiscountLineItem
• CouponLineItem
• PriceAdjustment
• ProductShippingLineItem
• ShippingMgr
• ProductLineItem (See API Bonus Promotion Positioning.)

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

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.

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

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:

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.

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.

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.

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.

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:

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:

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:

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:

A/B Testing

Campaigns and Promotions

Promotion Discounts

Qualifying and Discounted Products

Implementing Choice of Bonus Product(s) Discount

Restricting Promotions to Identical Products