Documentation

Managing static product bundles with Composable Commerce

Elevate, May 20-22-2025, Miami Beach, Florida

In a world where customers navigate through seemingly unlimited options, merchants face the challenge of constantly innovating to stand out. Product bundling serves as an effective strategy, simplifying consumers' choices while benefiting merchants. In this guide, we explore a tried-and-tested solution for managing static product bundles with Composable Commerce.

Benefits of product bundles

In digital commerce, a product bundle is a marketing strategy that combines multiple products or services and offers them as one package. This package might come at a reduced price or offer added value. Instead of buying items individually, customers can purchase the package, which generally contains complementary or related items.

Product bundles offer several advantages to merchants as well as their customers:

  • Increased value perception: customers often perceive product bundles as having a value that surpasses the total cost of the individual items. This perceived value can motivate purchases and increase sales.
  • Opportunities for cross-selling and upselling: combining related or popular items can encourage customers to buy additional products.
  • Efficient inventory management: bundles can help clear out inventory, as combining slow-moving products with more popular items can help boost sales for less desirable items.
  • Enhanced promotional activities: merchants can present product bundles as special deals or time-limited offers. Such promotions create a sense of urgency, encouraging customers to take advantage of the bundle before the deal ends.
  • Improved customer experience: bundles that offer a cohesive set of products or services can enhance customer experience. Customers appreciate the convenience of finding everything they need in one package.
  • Reduced shipping costs: as multiple items are shipped together, selling bundled products can lead to cost savings on shipping and handling for both the seller and the customer.
  • Increased customer loyalty: positive experiences with a product bundle are more likely to bring the customer back to the store for future purchases, increasing customer loyalty.
  • Competitive advantage: distinctive product bundles can give businesses a competitive edge, attracting more customers.

Model static bundles in Composable Commerce

Static bundles combine multiple related products for one total price, for example, selling a camera, bag, and batteries together at one price. The customer purchases a single bundle and receives two or more distinct, pre-selected items. Static bundles point to specific SKUs.

First, let's take a look at the Composable Commerce data structures required for modeling product bundles.

The high-level data structures

Product Types

The most flexible approach for modeling static bundles in Composable Commerce uses Product Types that reference Product Variants. With Product Variants, you can specify the exact SKUs that are included in the bundle.

Product Variants and Line Items

When Product Variants are added to a Cart, they are represented as Line Items. When adding a bundle to a Cart, use a Line Item to represent the bundle and one additional Line Item for each Product Variant included in that bundle. This approach gives you full flexibility in deciding how to manage inventory and pricing for the bundle.

For this example, we are using a photography bundle that includes a camera and a lens. The bundle has a distinct, reduced price.

Cart representation of main Line Item and component Line Items
Within the Cart, there's a Line Item for the bundle, with its price directly specified. Additionally, the Cart contains two more Line Items, one for the camera and the other for the lens, both priced at 0.
Inventory management is enabled for the component Line Items – the camera and the lens. The InventoryMode for the bundle is set to None. The component Line Items reference the bundle Line Item using the parentLineItemId Custom Field.

The general architecture and user flow

When a customer adds a product to a cart, three primary systems are involved:

  • Client application (for example, a web store): the component where customers interact, select products, initiate transactions, and more.
  • Backend for frontend (for example, API hub): processes requests from the client application, executes custom business logic, and communicates with external APIs, such as Composable Commerce. This is the best place to add custom logic for bundle management.
    Learn more about adding custom logic in the API hub here.
  • Composable Commerce: handles core commerce functionalities, such as cart operations, prices, discounts, and inventory tracking.
The process starts with a customer adding a product to the cart. The client application calls the middleware to check whether the product is a bundle or a standard item. If the middleware identifies the product as a bundle, it follows a specific set of steps. These steps involve checking product availability and adding the required Line Items to the Cart. The middleware then informs the client application about the success or failure of the cart update.
Sequence of events to add a Product bundle to the cart

Once the client application receives the cart update status, it displays either an updated cart or an error message (for example, availability error).

If a bundle is added successfully, the client application has the option to show or hide the component Line Items (identifiable via the parentLineItemID field). However, it's crucial to ensure that direct modifications to the component Line Items are restricted. All changes should be applied to the primary bundle Line Item.

Setup and implementation

Customize the Product Type

The Product Type used to model the bundle must reference the Product Variants (SKUs) included in that bundle. One straightforward method for this is to use a set of text Attributes.
To configure this for the photography bundle, add a components property to the bundle Product Type that contains details about the specific SKUs included in the bundle.
Customizing the product type for a bundle

Specify the quantity of Product Variants

In some cases, each Product Variant in the bundle might have distinct quantities, for example, a bundle with a camera, a lens, and two complimentary batteries. To store the quantity for each component Product Variant, consider these approaches:

  • Use a Custom Object to represent any additional information (SKU, quantity) of each component Product Variant. In this configuration, each item is essentially a reference to a Custom Object.
  • Adopt a standard format where each text in the set of Attributes combines the required information with a designated separator, such as ||. An example would be BAT456||2, where BAT456 represents the SKU, and 2 represents the quantity. You can extend this approach to capture more details about each component Product Variant, including names and descriptions.

Customize the Line Item

When a bundle is added to a Cart, each component Product Variant needs a dedicated Line Item. These Line Items reference the parent Line Item representing the bundle. To implement this reference, customize the Line Item type by adding a Custom Field parentLineItemId of type String.

Cart logic customization for adding a bundle to a Cart

We recommend implementing the following steps in your middleware for adding a bundle to a Cart:
  1. Detect that the product is a bundle and perform initial validations, such as verifying the availability of each component Product Variant.
  2. If all component SKUs are available, call the AddLineItem action to add the bundle to the Cart, generating a new Line Item with the following:
    • externalPrice set to the bundle price.
    • quantity set to 1.
    • inventoryMode set to None.
  3. Check the components property of the bundle to retrieve all Product Variants (SKUs) included in the bundle using Product Projection Search.
  4. Iterate through the set of component Product Variants and, for each one, add a new Line Item with the following:
    • externalPrice set to 0.00.
    • quantity set to the value specified by the bundle.
    • custom set to include the parentLineItemId Custom Field where the value is the ID of the bundle Line Item.
    • inventoryMode set to TrackOnly or ReserveOnOrder.

Cart logic customization for changing bundle quantity

When a bundle's quantity is changed, the middleware must update the quantities of the component Line Items accordingly. To avoid unnecessary calculations and updates for simple product quantity changes, implement a dedicated method in your middleware for bundle quantity changes.

Here's the set of steps for adjusting bundle quantity:

  1. Retrieve the Cart.
  2. Validate that the Line Item in question is referencing a bundle. If not, use the standard quantity change process.
  3. Check that the specified quantity adjustment is possible by validating the availability of each component Product Variant. This step helps prevent inventory discrepancies further down the process when updating related Line Items.
  4. Change the quantity on the bundle Line Item.
  5. Iterate through the component Line Items and update the quantity for each.

Removing a bundle from the Cart works similarly; iterate over the component Line Items and remove each item.

Conclusion

In this guide, we've explored a flexible approach for modeling static product bundles with Composable Commerce. By implementing the outlined strategy, you can efficiently manage bundles, ensure accurate pricing and inventory, and provide a seamless experience for your customers.