How Native Bundles Work in Shopify

If you're building custom bundle experiences on Shopify, whether you're a developer, an agency, or a merchant who wants to do more with bundling, it helps to have a base-level understanding of what Shopify is actually doing under the hood. This video walks through how native bundles work with the Cart Transform API.

A bundle has two parts

Every native bundle is made of the same two pieces:

• The parent. This is the product the customer adds to cart. It is not a real product in the sense that it never gets fulfilled. Some people call it a container product or a ghost product.
• The components. These are the products that actually get fulfilled. They get attached to the parent.

Before the Cart Transform API existed, bundles were usually sold as BOM (Bill of Materials) SKUs: only the parent went through checkout, and the individual components were worked out after the fact at fulfillment. Native bundles flip that around, so the real products show up in checkout and in the order.

Every parent has a configuration

Somewhere in Shopify, each parent has a bundle configuration. It's the instruction that says, "when this parent product is in the cart, these are the components that should be attached to it."

{
  "components": [
    { "product": "Ocean Blue Shirt",    "quantity": 1 },
    { "product": "Navy Sports Jacket",  "quantity": 1 },
    { "product": "Chequered Red Shirt", "quantity": 1 },
    { "product": "Zipped Jacket",       "quantity": 1 }
  ]
}

Turning the parent into its components is called bundle expansion. That's the Cart Transform API's term for it: we're expanding the parent into its components.

The Cart Transform Function runs on every cart event

The Cart Transform Function doesn't run once. Shopify runs it on its own servers every time something happens to the cart:

1. Product added. The customer adds a product to the cart.
2. Quantity changed. A line is increased or decreased.
3. Product removed. A line is taken out of the cart.
4. Checkout begins. The customer proceeds to checkout.

Your storefront never calls the function directly. It just adds products to cart as usual, and Shopify takes care of the rest.

Example: adding The Weekend Kit to cart

Here's what happens, step by step, when a customer adds The Weekend Kit:

1. The customer adds the parent, The Weekend Kit, to cart.
2. The Cart Transform Function runs and reads the cart.
3. It finds a bundle parent and looks up its configuration.
4. It expands the parent into its four components.
5. It updates the cart.

The result is a bundle that shows up in checkout and in the order as its individual components.

In the video I walk through this on a real storefront with The Weekend Kit set up in Flex Bundles. Whether the components are listed in the storefront cart depends on your theme (the cart still holds the parent as one line; more on that in where Shopify bundle data lives). In checkout, the bundle is shown expanded, so the customer sees exactly what they're getting.

What the order looks like

On the order in the Shopify admin, you never see the parent. You see the individual component line items, grouped under a "Part of" label that ties them back to the bundle. Flex Bundles also adds a _flex_bundle attribute to each component with a reference to the parent, so fulfillment software, 3PLs, and reporting can tell which items shipped together.

These are the items that get fulfilled, with real SKUs, real inventory, and prices that add up to what the customer paid.

That's really it

At the end of the day, native bundles are pretty simple:

1. The parent gets added to cart.
2. On each cart event, it gets expanded into its individual components based on its configuration.
3. The individual component line items get fulfilled.

Once you understand that foundation, there's a lot more you can build on top of it: custom attributes on each component, a fully custom bundle UI, and pricing or discount strategies you control. The Cart API integration docs cover how to drive all of this from your storefront.

If you want to see what that could look like for your store, book a demo. And follow along for more videos on the technical side of bundling.