Ordercloud Headstart: Adding Promotion Thresholds

Leading with Innovation

Sitecore cloud-based OrderCloud platform is designed to bring a flexible and intuitive API for its clients. Being a platform focused on its headless and API-first design, OrderCloud allows for easy extensibility and integration with any kind of project requirement. As a Sitecore Platinum Partner, XCentium created many innovations and is a driving force in the development of extensions, customizations and plug-ins for the platform. This blog details one such extension of a common OrderCloud feature, promotion thresholds, which is intended to show the current user promotions that can be applied when they reach an order subtotal. For example, free shipping when reaching $100.00.

A modified XCentium version of Sitecore’s Headstart project was used for this extended feature, so the following assumes the user has installed and built the perquisites. 

To harness this feature, we first need to create some example promotion objects with minimum and maximum threshold extended properties utilizing the promotions endpoint (  in the OrderCloud portal.

OC Threshold 1
OC Threshold 2

Next, instead of using OrderCloud’s main promotions endpoint, we will use the Me promotions endpoint. The OrderCloud feature will rely on the currently logged-in user session to calculate subtotals in order to trigger promotion thresholds, while the Me endpoint will make it easier to get the current user’s session. We will be adding to the PromotionCommand and OrderCommand in the middleware since that’s where OrderCloud’s API will be fetched.


Here is where the main logic of fetching and filtering will be processed.

public async Task<ListPage<Promotion>> ListPromotionsByOrderSubtotalThresholdAsync(string orderID, VerifiedUserContext user)
 await RemoveAllPromotionsAsync(orderID, user); // Clear current in memory promotions.
 Order order = await _oc.Orders.GetAsync(OrderDirection.Outgoing, orderID, accessToken: user.AccessToken);
 ListPage<Promotion> thresholdPromotions = await _oc.Me.ListPromotionsAsync(filters: "xp.MinThreshold=*");
 thresholdPromotions.Items = thresholdPromotions.Items.Where(promo => (order.Subtotal >= promo.xp.MinThreshold && order.Subtotal <= promo.xp.MaxThreshold)).ToList();
 return thresholdPromotions;


public async Task<ListPage<Promotion>> ListPromotionsByThreshold(string orderID, VerifiedUserContext user)
 return await _promotionCommand.ListPromotionsByOrderSubtotalThresholdAsync(orderID, user);

After adding those commands, we also need to access it through the controller. We will add it to OrderController since it deals with both the OrderCommand and the PromotionCommand.


[DocName("GET eligible promotions that are valid by order total threshold.")]
[HttpGet, Route("{orderID}/promotionsbythreshold"), OrderCloudUserAuth(ApiRole.Shopper)]
public async Task<ListPage<Promotion>> ListPromotionsByThreshold(string orderID)
 return await _command.ListPromotionsByThreshold(orderID, UserContext);


Now, to test our newly added features, we simply add a product to initiate an order.

OC Threshold 3

In our cart, we can see that no notifications have shown up yet, as the order subtotal is not enough to trigger any of our promotion thresholds.

OC Threshold 4
If we increase the quantity of our product, the subtotal triggers our first promotion threshold.

OC Threshold 5

Keep increasing the quantity, and we can keep triggering thresholds with a higher minimum.

OC Threshold 6

Increase the subtotal even more, and you’ll notice that when we go over any of the maximum thresholds, the notifications disappear.

OC Threshold 7