Overview
If you've ever wondered why some Shopify bundles appear as a single grouped item at checkout while others show each product separately, the answer is the Cart Transform Function API. This glossary article explains what the Cart Transform API is, how its three core operations work, and what limitations you need to know before choosing a bundle app. Whether you're evaluating native bundle tools or troubleshooting ungrouped cart items, this guide breaks down the technology in plain language.
Contents
What is the Cart Transform API?
The Cart Transform API is part of Shopify Functions, a framework that lets developers customize Shopify's backend logic. The Cart Transform API integrates this logic directly into the checkout flow. In practical terms, it is the technology that controls how bundled products are grouped, displayed, and priced inside the cart and at checkout. Transforming a cart means changing the pricing and presentation of items in a cart, and the Cart Transform API is the only way to modify the appearance of cart items such as titles, images, prices, and bundle grouping.
Think of it as the behind-the-scenes engine that turns a list of separate products into a clean, grouped bundle line item your customer can understand at a glance.
How the Cart Transform API works in Shopify
The Cart Transform API is part of Shopify's Functions framework. It allows developers to intercept and modify cart line items during the cart and checkout process. Instead of manually editing line items using JavaScript (which doesn't work reliably with checkout extensibility), Shopify Functions run securely on Shopify's infrastructure and modify the cart server-side.
When a customer adds a bundle to their cart, the bundle app passes product data to Shopify's servers. Cart transforms enable sophisticated merchandising strategies by programmatically merging, expanding, or updating cart line items. Transform functions operate during cart updates, product additions, and checkout initiation, providing multiple touchpoints to enhance the shopping experience.
Cart Transform is Shopify's cart-side merchandising surface. It is the Function API that owns bundle expansion, bundle merging, and line-level presentation updates in the cart. If the requirement is to change how lines are grouped, shown, or priced as a cart structure problem, Cart Transform is the right layer.
The three core operations: Expand, Merge, and Update
The Cart Transform API provides three distinct operations that bundle apps use to control how products appear in the cart and checkout. You can expand a cart line item to display its bundled items, merge multiple cart lines into a single line representing a bundle, and update the presentation of line items in the cart to override their price, title, or image.
Expand
The Expand operation expands a cart line item to display the bundled items it contains. This is the most common approach for "fixed" or "configurable" bundles. A customer adds a single parent product (like "Skincare Starter Kit") to the cart, and the Expand operation breaks it into its component products (cleanser, toner, moisturizer) displayed as nested children underneath the parent.
Use Expand when the shopper adds a parent bundle product and you want Shopify to display the underlying component lines. This is often the cleanest fit for configurable kits, add-on bundles, or parent SKUs that exist mainly as a commercial wrapper for child merchandise.
Merge
The Merge operation merges multiple cart lines into a single line that represents a bundle. This works in the opposite direction from Expand. A customer adds several individual products to the cart separately, and Merge groups them together under a new parent bundle line. This is useful for "build your own bundle" or mix-and-match experiences where the customer selects items one by one.
Update
The Update operation updates the presentation of line items in a cart to override their price, title, or image. It doesn't change the cart's structure; it simply changes how a line item looks. However, only stores on a Shopify Plus plan can use apps with update operations.
Side note - A subtle limitation from Shopify's docs: the updated image is visible in checkout only and is not persisted to orders. That is another reason to treat the Update operation as a presentation layer, not a durable product-data rewrite.
Why some bundles look grouped and others don't
This is one of the most common questions merchants ask. The short answer: only bundles built on the Cart Transform API display as grouped, nested line items in the cart and checkout.
Legacy "line item bundles" added each product to the cart as separate line items, typically with a discount applied via automatic discount or the now almost-deprecated Shopify Scripts. Bundled line items weren't grouped together, so customers would see each product from the bundle separately in the checkout.
These limitations led Shopify to develop the Cart Transform Function API in 2023. Cart transform extensions run on Shopify's servers and modify the cart through this API. When a customer adds products to their cart, the bundle structure is passed to Shopify's servers, and the cart transform function automatically bundles the products together. Each component displays as a child of the parent bundle product in the checkout, and each component's inventory is properly connected.
If your bundle app doesn't use the Cart Transform API, your products will likely appear as separate, ungrouped line items at checkout. When evaluating bundle apps, look for ones built on Shopify's native bundles platform. For example, Biscuits Bundles is built on the Shopify Bundles platform with Cart Transform at its core, so every bundle created with its multi-step bundle builder appears properly grouped in cart and checkout. You can see this in action on the Biscuits Bundles demos page.
Limitations merchants should know
The Cart Transform API is powerful, but it comes with constraints that can affect your bundle strategy. Here are the most important ones:
One cart transform function per store
You can install a maximum of one cart transform function on each store. That single-transform rule is much more important than it looks. It means if you install two different bundle apps that both rely on Cart Transform, only one can run. Most merchants won't hit this problem because a single well-built bundle app handles all your bundles, but it's worth knowing if you're using multiple apps for different merchandising needs.
No compatibility with selling plans (subscriptions)
Shopify rejects expand, merge, and update operations if a selling plan is present. This means bundles can't be sold with selling plans, such as subscriptions, pre-orders, and try-before-you-buy. If you want to offer a monthly subscription box, the items would need to be added individually to their own selling plans rather than grouped as a native bundle.
Update operation requires Shopify Plus
Only development stores or stores on a Shopify Plus plan can use apps with lineUpdate operations. The Expand and Merge operations are available on all Shopify plans, but if your app needs to override a line item's price, title, or image without changing the cart structure, you'll need Plus.
Order status and notification display gaps
On the order status page, bundle items are not always grouped. The order summary may break the bundle items into separate line items. Clients want the same bundle grouping in checkout and thank you to also carry through to the order status page.
As of December 6, 2024, orders that contain bundles now display as a nested group of line items in many email templates. Any notification templates that use the default template have automatically updated to display the grouped view for product bundles. However, if you've customized any of your email notification templates before that date, your notification templates aren't updated and may need manual adjustment.
Potential discount conflicts
Cart Transform changes line structure and can also adjust pricing, while Discount Functions run concurrently and independently. If you encode bundle savings in Cart Transform and also allow discounts to target those same lines, you can double-discount or discount the wrong surface. Keep this in mind when setting up automatic discounts alongside bundle pricing.
Why the Cart Transform API matters
For merchants, the Cart Transform API is the reason native Shopify bundles work the way they do. It directly impacts the customer experience at the most critical moment: checkout. Grouped bundle items reduce confusion, build trust in the pricing, and lower cart abandonment.
The Cart Transform Function API has become Shopify's recommended approach since its introduction in 2023, and most modern bundle apps in the Shopify App Store now use this architecture. When you choose a bundle app built on Cart Transform, you get server-side bundle grouping, real-time inventory tracking per component, and a checkout experience that matches what customers expect.
If you're looking for a bundle builder that leverages Cart Transform natively, Biscuits Bundles is built directly on the Shopify Bundles platform. It supports multi-step bundle builders with collapsible accordion steps, flexible pricing models (sum of products, fixed price, percentage or amount off, volume discount tiers), and live inventory tracking, all powered by the Cart Transform API under the hood.
Related concepts
Shopify Functions: The broader framework that powers Cart Transform. Functions let app developers customize Shopify's backend logic for discounts, shipping, payments, and cart behavior without modifying Shopify's core code.
Fixed bundles: A bundle made from a predetermined set of products and associated variants. Fixed bundles use Shopify's product components API and are expanded at checkout via Cart Transform.
Customized bundles: Used for more complex use cases, particularly when offering more choices to customers, or modelling a more complex composition of products, such as mix-and-match bundles. These rely on the Cart Transform Expand or Merge operations to group items at checkout.
Checkout Extensibility: Your store must use an upgraded checkout. Stores that use checkout.liquid customizations or features are incompatible with product bundles. Cart Transform only works with Shopify's extensible checkout.
Shopify Bundles app: Shopify's free first-party bundles app that allows you to create and edit fixed product bundles and multipacks right from your Shopify admin. For mix-and-match or build-your-own bundles, third-party apps like Biscuits Bundles fill the gap.
Selling plans: Purchase options such as subscriptions and pre-orders. These are currently incompatible with Cart Transform operations, which is a key consideration for subscription-based businesses.
View on app store