Broadleaf Microservices
  • v1.0.0-latest-prod

Release Notes for 1.8.1-GA


  • JDK 11 is now required for the Broadleaf 1.7.0-GA release train, and beyond.

New Features & Notable Changes

Feature/Notable Change Related Services Links

Introduced item proration details to represent a prorated order adjustment on a per-quantity basis

PromotionServices, OfferClient, OrderCommon

Refactored TaxService to make use of TaxDelegate pattern introduced in TaxCommon


Introduced improved logging throughout the checkout process

OrderOperationServices, MicroSecurityCommon

Improve support for awaiting async result when looking up and claiming 3DS transactions in checkout

NextJS Starter, PaymentTransactionServices, Integration Module

  • Cleaned up our frontend example COD payment form & fees

  • Ensure the fees cannot be removed unless COD is deselected

  • Added validation to the payment validation activity in the checkout workflow to ensure COD is configured correctly & the COD fees exist

  • Updated the DefaultCartItemTypes to use a more specific enum value, COD_FEE instead of EXTRA_FEE

CartOperationServices, OrderServices, CartClient, OrderClient, Commerce SDK, NextJS Starter

Introduced Apple Pay integration with

CartOperationServices, OrderOperationServices, PaymentGatewayCommon, PaymentTransactionServices, Integration Module, Commerce SDK, NextJS Starter, Payment SDK

Improved catalog representation within CartOperationServices

  • Refactored IProduct into CatalogItem

  • Abstracted out the concept of Product and use CatalogItem instead throughout CartOperationServices

  • Removed several deprecated methods from previous versions

CartOperationServices, CartClient

Improved checkout performance and extensibility

CartClient, OrderOperationServices, PaymentTransactionServices, CreditAccountServices

Checkout Performance and Extensibility Improvements in 1.8.1-GA

Updated CartStalePricingValidationActivity to honor Cart pricing within defined time-to-live by default

Added Properties

Bug Fixes


Fixed invalid payment total if offer applied after shipping stage

Fixed potential NullPointerException from CartItem type filter

Fixed potential NullPointerException from Cart’s lastCatalogReprice

Fixed tax calculation for cart items with VIRTUAL fulfillment type

Upgrade Guide

Checkout Performance and Extensibility Improvements

In 1.8.1-GA, checkout-related components are refactored for better performance and extensibility, which include the following:

  • Introduced CheckoutProcessDto to hold all the data required and passed in and out of the checkout service, workflow, and activities

    • For example, the CheckoutWorkflow 's execute method signature changed from:

      Cart execute(Cart cart,
                  String requestId,
                  Map<String, String> paymentLockTokens,
                  Map<String, String> securityCodes,
                  @Nullable ContextInfo contextInfo);


      CheckoutProcessDto execute(CheckoutProcessDto checkoutProcessDto,
                  Map<String, String> securityCodes,
                  @Nullable ContextInfo contextInfo);
      Security codes are still explicitly passed as an additional parameter so that activities that require them are easily differentiated and are required to implement RequiresSecurePaymentInformationActivity
    • This domain is useful to ensure that any additional data required for a custom workflow or activity can be easily accessed and consumed in the customization, without requiring an override in the workflow and activities to add a new parameter. To add new data, please see Adding Custom Data for instructions

    • Cart payments are now retrieved during the lock payments request, and they are passed throughout the workflow and activities without needing to fetch them again

    • Checkout-related exception handling behaviors are also updated to pass around the latest CheckoutProcessDto, to avoid having stale data

  • Consolidated persist cart actions into a single request where possible

  • Moved store credit payment balance validation to CartPaymentMethodValidationActivity, so that checkout can fail earlier rather than having some payments executed and then reversed due to checkout rollback from insufficient balance

  • Improved store credit payment validation to read multiple store credit accounts in a single request

  • Introduced property to control whether real-time pricing should be used in CartStalePricingValidationActivity

    • If disabled (default out-of-box), the activity will honor the stale pricing if it’s within the specified cart pricing time-to-live. See Added Properties for more details

Update Method Signatures

If you have any customization around checkout-related components, such as checkout service, checkout workflow, custom activities, etc., their method signatures need to be updated accordingly.

For example, a custom added activity should change from:

public class CustomActivity implements CheckoutWorkflowActivity {

    public Cart execute(@lombok.NonNull Cart cart,
                        @lombok.NonNull String requestId,
                        @Nullable ContextInfo contextInfo) {
        return cart;

    public Cart rollback(@lombok.NonNull Cart cart,
                         @lombok.NonNull String requestId,
                         @Nullable ContextInfo contextInfo) {
        return cart;


public class CustomActivity implements CheckoutWorkflowActivity {

    public CheckoutProcessDto execute(@lombok.NonNull CheckoutProcessDto processDto,
                        @Nullable ContextInfo contextInfo) {
        return processDto;

    public CheckoutProcessDto rollback(@lombok.NonNull CheckoutProcessDto processDto,
                                       @Nullable ContextInfo contextInfo) {
        return processDto;
Custom activities that implement RequiresSecurePaymentInformationActivity still take the securityCodes explicitly, e.g. CheckoutProcessDto execute(CheckoutProcessDto dto, Map<String, String> securityCodes, @Nullable ContextInfo context)
Update CheckoutProcessDto with the Latest Data

To ensure that CheckoutProcessDto always has the latest data, please always remember to update CheckoutProcessDto accordingly if your custom activity persists cart, payments, etc. For example:

// Prevents StaleCartException from stale cart version
Cart updatedCart = cartProvider.updateCart(cart, contextInfo);

Adding Custom Data for a Custom Activity

In some cases, additional data is required to be passed in for your custom activity. To pass in any additional data, you can either extend CheckoutProcessDto to contain a new field, or utilize CheckoutProcessDto#additionalAttributes.

Configuration Properties

Added Properties

  • broadleaf.cartoperation.checkout.activity.validation.cart-stale-pricing.use-real-time-cart-pricing

    • Description: Whether the CartStalePricingValidationActivity should use real time pricing or honer the cart pricing time-to-live based on the last catalog reprice. See Stale Cart Pricing Configurations for other related configurations

    • Default value: false

  • broadleaf.cartoperation.paymentprovider.lock-and-retrieve-payments-uri

    • Description: The URI path for locking multiple payments and include their PaymentSummaries in the response