How to extend the SFCC promotion engine?

Lessons learned during customization SFCC campaign and promotion engine.

Oleg Sapishchuk
6 min readJun 3, 2019

When I’m writing this article, I’m assuming that you are already familiar with Campaigns and Promotions module, from official SFCC documentation. You might already use Campaigns and Promotions on your existing Salesforce Commerce Cloud (SFCC) e-commerce website. Another possible scenario that you just took Business Manager (BM) training and having in mind one or few promotion scenarios that seem to be not achievable with out of the box Campaign and Promotions module offered by SFCC.

Or maybe you are just like me — tech guy who is looking for the solution?


Lately, for one of my clients, during consulting them about different promotion combinations and configurations that might be done, we faced an issue that promotions rules for qualifiers don’t work in “AND” condition, but in “OR.” On that time, as I was super surprised of such behavior, support ticket was created, so SFCC can take a look on that bug, as logically it had to work with “AND” condition.

As you might guess why I’m writing this article, it wasn’t accepted to be a bug in the core of the platform. In the same time, they highlighted it is the platform documentation and BM User Interface (UI) “bug.” SFCC support replied they will update documentation and BM UI to highlight it’s working as “OR” instead of “AND.”

More about this case, you can read in public “Known Issues” web-page.

End of the story?


In any personal or work situations, when there is unclear way what to do, there is a solution somewhere, and for SFCC program based on the current case we had the following possible approaches

  • change business promotion rules to fit into out of the box platform capabilities
  • request SFCC platform to extend their promotion engine to support advanced scenarios as per clients needs to
  • provide customized solution on top of the SaaS engine using SFCC API and SFCC Scripting Language.

First 2 steps failed, due to various reasons. The only information that can help in the future is — the third step. Hence let’s review how we can extend and customize promotion engine using SFCC API and SFCC Scripting Language.

Plan and Realization

To find the solution, we need to think about “how to.” “How to” is a concept via planning how different activities will be performed. It forces us to simulate different scenarios and build a list of questions that we might prepare and point out to the right resources. For example:

How to achieve final goal?

The main goal is to let the client being able to trigger his business promotion rules on SFCC platform. If his current requirements can be achieved partially, we are focusing on the missing part. It might be the case that if we divide requirements into two pieces, separately we obtain it for 100%. Hence our customization will be to link those two pieces. Another case might be that client requirement is not supported via split, and we should find a solution to extend and customize more logic.

The best way is to split and link, as via such approach we are leveraging from most of out of the box platform features and decrease the level of customizations. The natural mechanism of promotions in our case will be kept. Such happened with my customer and all his rules. I could split into packages where we could create two promotions.

How to choose an approach?

For promotions customizations there are two ways of customizing:

  1. Apply promotions based on customer group. Build customer group based on custom session value. Control the data via code and custom preferences if required.
  2. Remove applied from BM promotions based on SFCC Scripting Language logic using API methods.

I saw both of them and from an operational perspective, the second one is better, while from the performance side I would say that the first option suite the best.

If you wish to understand the reason of my characteristics, try to draft scenarios when you scale on multiple countries and zones and check the impact of the customizations from technical and business perspectives. Measure… measure… measure…

How to search?

Thanks to Stephen Holsinger we have this fantastic and fast way to search in SFCC documentation

Using it with the query “Extensions for Promotions.

Search Results

We will be targetted to SFCC best practices documentation page which described how to modify how promotions are processed. On that page, we will found out where exactly we need to make the changes.


how to investigate?

Having the proper file where our logic should exist, we are not aware of what exactly should be coded or used. Using SFCC documentation and checking SFCC API documentation for relevant keywords as promotion promotion plan promotion manager apply promotion remove promotion get promotion we will identify Classes and Methods that potentially could fit our customizations on needs. 99% of them are located under Promotion, PromotionMgr, and PromotionPlan.

how to make sure the solution will be working?

Build a proof of concept (PoC) using SFCC API methods, hardcoded values that we might get from BM customizations or created property files and dummy campaign and promotion configuration in BM in order check if our customizations will work.

The algorithm of the PoC was simple:

PoC for remove promotion

how to organize technical part in the business way of thinking?

Design the solution

PoC showed that we could modify the logic and remove promotions that did qualify potential conditional rules.

Linked Promotions is the way which was chosen for the letting business and operational team use the same Campaign and Promotion interfaces with few custom attributes. Custom attributes will link our split logic and group them into one conditional requirement that our custom logic in the code will take into consideration.

The idea of Linked Promotions is super simple: You can split business promotion rule into two separate promotions, and you link them as, those will be applied only if both promotions requirements are satisfied to the current basket. If only one met requirements and was used, it will be removed. This way both separate promotions works as grouped one promotion. Linking is achieved via custom attribute where you put the ID of another promotion and in SFCC Scripting Language use it to prepare conditional logic.

For example, we have the following conditions from the business team:

  1. Buy at least one specific product
  2. Total cart amount exceeds the specified price threshold
  3. If first and second qualified customers should get a bonus product (sample)

which we transform into following Linked Promotions:

  1. Promotion A: Buy 1 + product A then get 0 discount
  2. Promotion B: Buy 100$ or more with the qualifying product for all products then get a bonus product (sample)

As mentioned above the client will get sample products if only he added Product A, and the total amount of the basket is more then 100$. Such rule was not possible to define using out of the box Campaign and Promotions engine.


New achievement. Another problem solved. One more solution provided to the client to satisfy their business expectations.

The excellent lesson learned was to not expect from SaaS platform agree with the bugs you found in their core and always prepare the plan B.

Linked Promotion solution is in production for some time already and showing good results. It was worth it to build such customization for the client.

Per Aspera Ad Astra — this is exactly the feeling I have when working with SFCC.

My name is Oleg Sapishchuk, and I’m an experienced architect providing digital transformation with unified commerce solutions for some of the world’s best-known and most influential brands. Salesforce B2C Commerce is the topic that I write about most frequently. If you are interested in new or previously written material, I invite you to follow my Medium profile.



Oleg Sapishchuk

Solution Architect providing digital transformation with unified commerce solutions for some of the world’s best known and most influential brands