APIs for Get Promotion Products

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.

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

You can programmatically refine by multiple promotions using the following:

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:

Method Description
getProducts() : String Returns the products in the search results.
getPromotionID() : String Returns the promotion with the specified ID.
setPromotionIDs(List promotionIDs) : String Specifies 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

Promotion Types and Discounts

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 type Discount type Products 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


Discounted products

Buy X Get Y

Percent Off

Amount Off

Fixed Price

Price From Price Book


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

Business Manager

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.

Example: Storefront Implementation

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.

  1. Create a promotion as follows:
    • 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.
  2. Add an image that shows the add called: Save Up To 40% On Select Women's Footwear Styles.
  3. 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.

Related Links

APIs for Promotions

X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.