Broadleaf Microservices
  • v1.0.0-latest-prod

Offer Provider


Provider for interfacing with an Offer Engine that can supply discounts and promotions base on the contents of a cart. The default implementation facilitates HTTP requests against the Offer Services endpoints.


Cart Operations interacts with the Offer Engine two times usually to apply offers and promotions:

  1. Before fulfillment pricing occurs to retrieve discounts for the cart as a whole and for individual items, that is, to finish calculating the base merchandise pricing for the cart

  2. After the base fulfillment pricing has been calculated to retrieve fulfillment discounts

The reason for this ordering is that fulfillment pricing may depend upon the price of the merchandise. This is particularly true for fulfillment and fulfillment item discounts, which may have rules that they are only applied for items or entire carts above certain subtotal thresholds.

Default Implementation Details

Additionally, the Broadleaf Offer Engine requires its own order-like structure that isn’t the same as the cart domain. Therefore, the default implementation of the OfferProvider, ExternalOfferProvider, facilitates converting a cart, its items, and fulfillment groups into an OrderDto that the Offer Engine can process. This domain includes a runOrderAndItemOffers flag to control whether order and order item offers are calculated.

In step 2 in the previous section where fulfillment discounts are calculated, this flag is set to false to prevent any recalculation of the base merchandise pricing—otherwise, the fulfillment discount calculation can be incorrect and interfere with the application of non-fulfillment discounts. Moreover, this allows the calculations to run faster since fewer offers or promotions need to be considered.

The ExternalOfferProvider also defers some tasks to other components.

  • UserTargetGenerationService: Generates the UserTarget DTOs that represent any type of user such as an individual customer, a business account, or an entire customer segment. This consults the SecurityContextHolder to get authenticated user info.

  • CartTotalsCalculator: Assists in calculating the subtotal, fulfillment, and before and after tax totals for the cart.


ExternalOfferProperties defines the properties for configuring the ExternalOfferProvider. These include:

  • broadleaf.cartoperation.offerprovider.url: The base url of the offer engine.

  • broadleaf.cartoperation.offerprovider.useCodeUri: The context path for retrieving code usability info. This is appended to the url property.

  • broadleaf.cartoperation.offerprovider.validateUri: The context path for validating discounts during checkout. This is appended to the url property.

  • broadleaf.cartoperation.offerprovider.applyUri: The context path for calculating and apply discounts to a cart. This is appended to the url property.

Examples of building request from properties
// manage offer code

// validate offers
        .queryParam("customerContext.customerId", customerId)
        .queryParam("customerContext.accountId", accountId)
        .queryParam("customerContext.customerSegmentIds", customerSegmentIds)
        .queryParam("offerCodes", offerCodes)
        .queryParam("offerIds", offerIds)

// apply offers