Release notes

Changelog

October 14, 2025

Boilerplate Updates

Boilerplate

The Commerce boilerplate has been updated with the following changes:

AEM Assets compatibility - Decimal dimensions now render properly, supporting image rendering with decimal width/height values (#767).
Commerce Block documentation - Commerce blocks now include comprehensive README files for better developer onboarding and implementation guidance (#728)
Configuration error handling - Missing or invalid site configurations now show a helpful 418 error page that provides clear guidance to developers (#714)
Configuration fallback enhancement - Single-endpoint setups now automatically fall back to “commerce-endpoint”, simplifying configuration (#700)
Metadata and schema improvements - Breaking change: Product URLs now enforce lowercase SKUs. Sites with uppercase SKUs must ensure proper metadata mapping to prevent broken links (#406). Metadata handling now works properly for multistore configurations with JSON-LD path resolution (#686)
Mini-PDP component reorganization - The mini-pdp component now lives in the components folder for better code organization and reusability (#722)
PDP state management - Multiple PDPs on the same page no longer overwrite each other’s state, ensuring proper product data isolation (#696)
Placeholder data preservation - Placeholder data no longer gets lost, preventing content display issues (#689)
Search functionality improvements - Search functionality now handles results better with improved styling (#776)
UI accessibility improvements - Non-interactive elements no longer show pointer cursors, improving accessibility compliance (#681)

For complete details, see the Boilerplate Updates changelog entry.

August 12, 2025

Boilerplate Updates

Boilerplate

The Commerce boilerplate has been updated with the following changes:

Account drop-in fixes - Resolved various account drop-in functionality issues
Added carousel and cards-list components - Integrated carousel and cards-list components for enhanced product display capabilities
Architecture cleanup - Removed deprecated widgets and custom PLP components
Checkout compatibility - Fixed shipping methods infinite loop and iOS compatibility
Checkout update - Updated checkout drop-in to version 2.0.0-beta6
Commerce Storefront compatibility improvements - Enhanced compatibility with storefront-builder for improved UE integration
Documentation enhancement - Added comprehensive JSDocs comments to commerce.js
Global placeholders - Implemented global placeholders system
Header optimization - Optimized header’s mini-cart and search loading performance
Initialization optimization - Reordered main initialization in scripts.js for improved loading sequence
Modal localization - Fixed modal localized text display
PDP image zoom fix - Fixed image zoom icon display issues
Product discovery search fix - Fixed search item link functionality
reCAPTCHA enhancement - Enhanced reCAPTCHA initialization in initializeDropins function
Recommendations drop-in events - Recommendations drop-in now sends Adobe Client Data Layer events
Recommendations update - Updated @storefront-recommendations to v1.0.0
Removed default content from product-details block - Cleaned up default content from product-details block for cleaner implementation
Scripts refactoring - Major refactoring of scripts.js for improved maintainability
Wishlist improvements - Enhanced wishlist mobile alerts and cart integration

For complete details, see the Boilerplate Updates changelog entry.

June 24, 2025

Boilerplate Refactoring

Boilerplate

The scripts.js file has been refactored to align with the upstream AEM Boilerplate while extracting all commerce-specific functionality into scripts/commerce.js. This refactoring provides better separation of concerns and improved maintainability.

Key Changes:

scripts.js now contains only core AEM functionality (aligned with upstream AEM Boilerplate)
commerce.js now contains all commerce-specific functionality including:
- GraphQL queries and commerce backend connections
- Template handling and application
- Commerce page type detection
- Adobe Data Layer initialization
- Commerce utilities (rootLink, fetchPlaceholders, etc.)
- Modal auto-linking functionality
- Commerce-specific preloading logic

Import Updates Required: Developers need to update import statements from scripts/scripts.js to scripts/commerce.js for commerce-specific functions:

1
// Before
2
import { rootLink } from '../../scripts/scripts.js';
3
import { fetchPlaceholders } from '../../scripts/scripts.js';
4

5
// After
6
import { rootLink } from '../../scripts/commerce.js';
7
import { fetchPlaceholders } from '../../scripts/commerce.js';

See the Architecture Overview for more details about the refactoring and its benefits.

October 14, 2025

Cart v1.5.1

Cart

The Cart drop-in component has been updated to include the following changes:

Tiered pricing now available: The cart automatically applies quantity-based discounts to eligible items. This feature integrates with GraphQL to fetch price tier data, matches the best discount for the current quantity, and calculates savings percentages. Both simple and configurable products display their applicable tiers clearly in the cart UI (#70).
Smarter configurable product handling: When you modify a configurable product’s options, the cart now intelligently merges it with existing items that have matching configurations. This consolidates quantities and removes duplicates for a cleaner experience. We also fixed an issue where updating items with identical options would incorrectly increase quantity instead of maintaining the current amount (#69).
B2B company context support: The cart automatically refreshes when company context changes, keeping contents and pricing synchronized with your current B2B company for multi-company scenarios (#65).
Cross-tab logout sync: Cart state now stays consistent across browser tabs after user logout, ensuring the same cart behavior in all active sessions (#62).
Clearer tax information: Virtual carts without applied taxes now show “TBD” until checkout begins, then display the actual tax values. This provides clearer tax information throughout the checkout flow (#72).
Better quantity validation: Quantity field validation now properly handles maximum values, ensuring accurate input constraints (#68).
Accessibility improvements: Lighthouse accessibility scores are now higher thanks to proper aria-labels for quantity inputs and improved keyboard navigation for screen readers (#67).

August 12, 2025

Cart v1.5.0

Cart

The Cart drop-in component has been updated to include the following changes:

Extended Add/Update Cart API: Added support for custom fields in the addToCart() and updateProductsFromCart() API functions, enabling developers to set and update custom cart item fields such as standard_height and custom_height during cart operations.
Fixed missing Channel Field: Fixed an issue where the channel attribute was missing from all Adobe Experience Platform (AEP) events on the Product Details Page. The channel field is now properly populated as part of the global storefront context for all PDP events, ensuring complete event data collection.
Added undo remove cart items: Introduced configurable functionality to allow users to undo item removals from the cart. When enabled, removed items display an undo banner in their original position while cart totals reflect the removal, with the ability to reinstate items with their original quantity and options. The feature works with both built-in remove buttons and the updateProductsInCart API, with customizable undo banner styling.
Enhanced mini cart flexibility: Redesigned the mini cart layout with reduced container nesting and improved slot architecture, allowing developers to easily wrap individual elements (price, product title, quantity), customize action button placement and styling, add quantity stepper labels, and include specific product attributes with comprehensive documentation.

June 25, 2025

Cart v1.4.0

Cart

Fixed the alignment of the Apply button text in the gift wrapping customization, ensuring it now matches the intended design.
Resolved an edge case where updating a cart item with the same options and quantity could unexpectedly remove the item from the cart.
The cart open AEP event now correctly includes productListItems, providing more accurate event data.
The cart view AEP event now includes selected product options and discount information in productListItems.
The add to cart AEP event now populates selected options for complex and bundled products, improving event tracking accuracy.
The start checkout AEP event now includes available product discount information in productListItems.
The cart summary list can now be rendered in a customizable column layout, allowing brands to better match their design guidelines.

October 14, 2025

Checkout v2.1.0

Checkout

The Checkout drop-in has been updated to include the following changes:

New utility library: The checkout now includes reusable utilities for address transformation, form validation, cart state management, and shipping cost estimation. This improves code reusability across different checkout implementations (#88, #146).
Free orders now supported: Zero-cost checkouts (when coupons or promotions cover the full total) now have dedicated payment method display and handling (#170).

August 12, 2025

Checkout v2.0.1

Checkout

The checkout drop-in component has been updated to include the following changes:

Miscellaneous bug fixes and enhancements.

The Multi-step checkout tutorial has been updated providing a customizable example to implement a comprehensive multi-step checkout based on a modular architecture (event-driven step coordination) that supports the following scenarios:

Guest users
Logged-in customers
Virtual products
Mixed carts (physical + virtual product combinations)

June 25, 2025

Checkout v2.0.0

Checkout

The checkout drop-in component GraphQL API has been extended exposing new fragments:

BILLING_CART_ADDRESS_FRAGMENT
SHIPPING_CART_ADDRESS_FRAGMENT
AVAILABLE_PAYMENT_METHOD_FRAGMENT
SELECTED_PAYMENT_METHOD_FRAGMENT

The Error Handling has been implemented in some containers (still work in progress):

BillToShippingAddress
LoginForm
PaymentMethods
ShippingMethods

The Event Handling has been documented within the list of events emitted and subscribed by the checkout drop-in component containers.

A new Active property has been added for all containers: This property activates/deactivates the container.

A new AutoSync property has been added for some containers: This property allows the container automatically synchronizing its state changes with the backend.

A new TitleProps interface has been created to customize the title and header of some containers.

The BillToShippingAddress container configuration structure has been modified. A new property has been added to the BillToShippingAddressProps interface:

BillToShippingAddressProps.onCartSyncError property added: This property allows performing some actions in case of an error is thrown when the bill to shipping checkbox is checked.

Implemented an error handling mechanism for the BillToShippingAddress container based on the “Optimistic” UI updates with rollback pattern consisting on the following:

It provides a callback function onCartSyncError() to be used in the integration layer in case the merchant wanted to perform some actions like showing an error message etc.
It performs a rollback reverting to the previous valid checkbox state.
In case the callback is not implemented, a fallback will be used, which consists of displaying an inline alert message.

The LoginForm container configuration structure has been modified. New properties have been added to the LoginFormProps interface:

LoginFormProps.displayHeadingContent property added: This property allows displaying the container heading content.
LoginFormProps.slots.Heading property added: This property allows customizing the container heading content based on the user authentication status.

… and the following properties have been added extending from TitleProps interface:

LoginFormProps.displayTitle property inherited: This property allows displaying the container title.
LoginFormProps.slots.Title property inherited: This property allows customizing the container title.

The PaymentMethods container configuration structure has been modified. Deprecated properties have been removed from the PaymentMethodsProps interface:

PaymentMethodsProps.setOnChange deprecated property removed.
PaymentMethodsProps.slots.Handlers deprecated property removed.

… the following property has been renamed:

PaymentMethodsProps.slots.Methods[code].setOnChange property renamed to PaymentMethodsProps.slots.Methods[code].autoSync.

… the following properties have been added:

PaymentMethodsProps.onSelectionChange property added: This property allows performing some actions when a payment method is selected.
PaymentMethodsProps.onCartSyncError property added: This property allows performing some actions in case of an error is thrown during the payment method selection.
PaymentMethodsProps.UIComponentType property added: This property allows using a different UI component type as a selector for each payment method. UI components available are: ‘ToggleButton’ and ‘RadioButton’.

… and the following properties have been added extending from TitleProps interface:

PaymentMethodsProps.displayTitle property inherited: This property allows displaying the container title.
PaymentMethodsProps.slots.Title property inherited: This property allows customizing the container title.

Implemented an error handling mechanism for the PaymentMethods container based on the “Optimistic” UI updates with rollback pattern consisting on the following:

It provides a callback function onCartSyncError() to be used in the integration layer in case the merchant wanted to perform some actions like showing an error message etc.
It performs a rollback reverting to the previous valid payment method selected.
In case the callback is not implemented, a fallback will be used, which consists of displaying an inline alert message.

The ShippingMethods container configuration structure has been modified. A property has been removed from the ShippingMethodsProps interface:

ShippingMethodsProps.preSelectedMethod property removed: This was an obsolete and unused property without business logic behind.

… the following property has been renamed:

ShippingMethodsProps.onShippingMethodSelect property renamed to ShippingMethodsProps.onSelectionChange.

… the following properties have been added:

ShippingMethodsProps.onCartSyncError property added: This property allows performing some actions in case of an error is thrown during the shipping method selection.
ShippingMethodsProps.UIComponentType property added: This property allows using a different UI component type as a selector for each shipping method. The available UI components are: ToggleButton and RadioButton.

… and the following properties have been added extending from TitleProps interface:

ShippingMethodsProps.displayTitle property inherited: This property allows displaying the container title.
ShippingMethodsProps.slots.Title property inherited: This property allows customizing the container title.

Implemented an error handling mechanism for the ShippingMethods container based on the “Optimistic” UI updates with rollback pattern consisting on the following:

It provides a callback function onCartSyncError() to be used in the integration layer in case the merchant wanted to perform some actions like showing an error message etc.
It performs a rollback reverting to the previous valid shipping method selected.
In case the callback is not implemented, a fallback will be used, which consists of displaying an inline alert message.

The TermsAndConditions container is now visible for both the anonymous and authenticated checkout processes.

March 6, 2025

Checkout v1.3.0

Checkout

A new TermsAndConditions container has been added.

February 11, 2025

Checkout v1.2.0

Checkout

The PlaceOrder container configuration structure has been modified. A new property has been added to the PlaceOrderProps interface:

PlaceOrderProps.slots.Content property added: This property allows setting the container content based on the selected payment method. This solves the way how to set the container content dynamically based on the selected payment method, instead of having to modify the text of the container manipulating directly the DOM and detecting payment method selection by handling the PaymentMethods slot, which is not ideal for maintainability.

February 3, 2025

Checkout v1.1.0

Checkout

The PaymentMethods container configuration structure has been modified. The PaymentMethodsProps interface has been changed and some properties have been deprecated and replaced:

PaymentMethodsProps.setOnChange property @deprecated: This property is deprecated and will be removed in future versions. It has been replaced by the following: PaymentMethodsProps.slots.Methods.<payment-method-code>.setOnChange.
PaymentMethodsProps.slots.Handlers property @deprecated: This property is deprecated and will be removed in future versions. It has been replaced by the following one: PaymentMethodsProps.slots.Methods.<payment-method-code>.render.
PaymentMethodsProps.slots.Methods property added: This property is an object that consists of a list of payment method codes that provide a set of configurations to customize each payment method individually.

Configurations accepted by payment methods:
- The displayLabel configuration hides the payment method label (for example, if you only want to display the icon).
- The enabled configuration allows merchants to individually hide payment methods filtering them from the available payment methods list (for example, it is useful when a payment provider has enabled a payment method in the backend, which is configured with more than one payment option and you don’t want to display one of them).
- The icon configuration specifies the name of the icon to be shown beside of the label. The icon name must exist within the list of available icons defined in the drop-ins SDK.
- The setOnChange configuration sets the payment method automatically when it is selected. Only if a payment method is specifically set to false, the container will not automatically set the payment method to the cart when selected (for example, if a payment method needs to obtain more information during the place order action).
- The render configuration is a handler used to render and configure the payment method.

October 20, 2025