We are excited to announce the 2.2.1-GA release of Broadleaf Commerce, delivering powerful new offer capabilities, enhanced search functionality, important security updates, and numerous fixes that improve scalability, flexibility, and overall eCommerce performance. Let’s dive into what’s new in Broadleaf Commerce 2.2.1!

Important Information

• Java 17 is required since 2.0.0-GA.
  
• SearchServices 2.2.1 requires CatalogServices 2.2.1+.
  
• A full reindex is required after upgrading SearchServices.
  
• Due to Campaign Offer Code audit enhancements, a database migration is required in order to display legacy code uses.
  
• Node 20 is supported in Unified Admin and Commerce SDK. Node 14, 16, and 18 are end-of-life.
  
• Please see the full 2.2.1 release notes here.
  

Key Features & Enhancements

1. Offer Enhancements: Opt-In Offers, Dynamic Offers, and Payment Offers

Impacted Services: OfferServices

Broadleaf Commerce introduces significant new Offer features:

• Opt-In Offers: Applications can opt-in (or out) of tenant-level offers with flexible acceptance models.

• Dynamic Offers: Discount amounts can now be supplied externally and applied during repricing.
  
• Payment Offers: Discounts can be applied based on payment type (Visa, MasterCard, Amex, etc.).

2. Search Improvements and Synonym Management

Impacted Services: SearchServices, CatalogServices, Catalog BrowseServices

• Added indexing for required product options, improving accuracy for merchandising products in search and typeahead.
  
• Introduced Synonym Management, including managed language support and new admin views.

• Solr narrowing fixes include new document fields and query contributors for sandbox, catalog, and application-level discrimination.
  

Please refer to the 2.1.5 Catalog release notes and 2.1.5 Search release notes for more information.

3. Campaign Offer Code Audit

Impacted Services: OfferServices

• Updated Campaign Offer Code audit tab to properly display legacy code usage.
  
• A database migration is required to populate the new campaign_id field.
  

Please refer to the 3.0.6 Offer release notes for more information.

4. Inventory Location Support in Carts

Impacted Services: CartOperationServices, InventoryServices

• Added ability to specify inventory location when adding items to cart.
  
• Availability checks and fulfillment grouping now respect inventory location in addition to fulfillment type.
  

5. Security Updates

Impacted Services: ContentServices, MicroservicesGateways

• Security-related updates have been applied to ContentServices and Microservices Gateways.
  

To review the security-related content, see the 2.2.1 notes.

6. Unified Admin 1.10.12 Enhancements

Impacted Services: AdminServices, CatalogServices

• Added Node 20 support.
  
• Support for multiple routes mapped to the same path, distinguished by scope or component ID.
  
• Added ability to restrict routes by ANY vs ALL scopes.
  
• Semantic HTML improvements and externalized stylesheets for easier customization.
  
• Enhanced navigation with collapsible sections and sandbox change visibility.
  

7. Catalog and Metadata Enhancements

Impacted Services: CatalogServices, Admin Metadata Services

• Repository updates for handling large result sets with batching.
  
• Support for generating multiple base views for Business Types.
  
• Added characteristics inheritance for Business Types.
  

8. Content Enhancements

Impacted Services: ContentServices

• New Custom Content Field entity for reusable definitions.

• Marketing messages can now reference Content Items

9. Payments and Gateway Updates

Impacted Services: PaymentTransactionServices, Stripe, Adyen, Amazon Payment Services, Checkout.com, MyFatoorah, Tabby

• Stripe integration updated to use Stripe Elements and upgraded Java SDK.
  
• Improved handling of asynchronous payment reversals with new management states.
  
• Enhanced webhook logging with tenant and application IDs.
  

10. Observability Enhancements

Impacted Services: Common Libraries, SandboxServices

• Added OpenTelemetry support across common libraries and sandbox.
  

11. SDK & Microfrontend Updates

Impacted Services: Commerce SDK, Payment JS SDK, Commerce Quote Microfrontend, Commerce Next.js Starter

• Commerce SDK: added pricing invalidation flags and X-Customer-Ref headers.
  
• Payment JS SDK: added onSuccess callbacks.
  
• Quote Microfrontend: upgraded to React 18 and Node 18+.
  
• Next.js Starter: support for payment offers via PAYMENTS_LIST attributes.
  

Notable Bug Fixes

• Fixed Solr narrowing and indexing issues to ensure correct results by sandbox, catalog, and application.
  
• Corrected productType and priceWithDependentItems indexing for merchandising products.
  
• Resolved cart issues including gifts, duplicate keys, and COD handling.
  
• Fixed Admin navigation precision, validation for required fields, and sandbox ribbon display.
  
• Payment reversal job now handles application-discriminated gateways and asynchronous results.
  
• Improved Inventory handling to prevent duplicate reservations across multiple locations.
  

Why Upgrade to Broadleaf 2.2.1?

The 2.2.1 release delivers key improvements for accuracy, flexibility, and security in enterprise eCommerce:

• Smarter product search and synonym management for better customer experience.
  
• Expanded promotional strategies with opt-in, dynamic, and payment-based offers.
  
• Stronger observability and security updates.
  
• Improved Admin usability with multiple-route support and semantic updates.
  
• Updated SDKs and microfrontends for simpler integrations.
  

How to Upgrade

• Ensure you are running Java 17.
  
• Upgrade to CatalogServices 2.2.1 before SearchServices 2.2.1.
  
• Run a full search reindex after upgrading SearchServices.
  
• Perform the database migration for Campaign Offer Code audit history.
  
• Update frontend environments to Node 20 and validate multi-route admin behavior.
  

For full instructions, please refer to the upgrade guide.

What’s Next?

Broadleaf Commerce continues to expand capabilities for modern eCommerce. Upcoming releases will focus on deeper search quality signals, richer merchandising controls, and new promotional tools that align with marketplace and payment innovations.