Menu
Guides
API Reference
App Development
Storefront Development
VTEX IO Apps
Troubleshooting
Release Notes
Storefront Development
Getting started with storefront solutions
FastStore
Store Framework
CMS Portal (Legacy)
Storefront best practices

Keeping split cart lines

4 min read
By default, FastStore merges cart lines that share the same SKU, seller, attachments, and services into a single line. This is the right behavior for most stores. However, some stores need each unit of a product to remain a separate line in the cart, for example, when shoppers choose different assembly options (such as installation or extended warranty) for each unit, or when each unit must be handled as its own line in an ERP integration.
The preserveCartLines flag makes FastStore respect the lines that your store split in Checkout, instead of merging them again.
FastStore doesn't split lines on its own. Adding a product with quantity 2 still creates a single line, whether or not preserveCartLines is used. The split must be done in Checkout.

Default behavior and behavior with the flag

Consider a shopper who buys 2 units of the same refrigerator. Before the shopper chooses services for each unit, your store splits the line in Checkout using the split item endpoint, resulting in [refrigerator x1, refrigerator x1].
preserveCartLines: false (default)preserveCartLines: true
MinicartShows one line with quantity 2.Shows two lines with quantity 1 each.
CheckoutOn the next cart validation, FastStore sends the merged quantity, and Checkout undoes the split.The split is kept after the cart is validated and the page is reloaded.
Editing or removing a lineBecause lines share the same ID, the action may affect the wrong line.The action affects only the selected line.
The behavior of stores that don't enable the flag remains unchanged. This is because Checkout may also return several lines of the same SKU due to promotions, so the flag is opt-in. Without it, FastStore keeps merging those lines.
Assembly options are added to the cart as child items of a product line, and the preserveCartLines flag handles them. Services stored in bundleItems follow a different mechanism and don't require the flag.

Before you begin

  • Update your store to FastStore 4.10.3 or a later version. To do so, follow Updating the CLI package version.
  • Make sure your store splits items in Checkout. FastStore only preserves lines that already exist as separate lines in the Order Form.

Instructions

Step 1 - Enable preserveCartLines

  1. Open your discovery.config.js file.
  2. In the api object, set preserveCartLines to true.
discovery.config.js

_10
...
_10
api: {
_10
...
_10
preserveCartLines: true,
_10
}

Step 2 - Test the cart behavior locally

Before deploying, test the flag locally, as it changes how cart lines are matched with Checkout.
  1. In the terminal, run the following command to start the local server:

_10
yarn dev

  1. Create a cart with two units of the same SKU and call POST /api/checkout/pub/orderForm/{orderFormId}/items/{itemUniqueId}/split with a body that divides the item into lines of quantity 1, for example, [{"quantity": 1}, {"quantity": 1}].
  2. Open your store with the cart's checkout.vtex.com cookie and open the minicart. It should show two lines, and Checkout should keep two lines after you reload the page.
  3. Increase the quantity of one line. Only that line changes in Checkout.
  4. Remove one line. Only that line is removed, and its services (if any) stay on the correct unit.
If your store uses assembly options, also confirm the following:
  • The cart stays stable when the same SKU appears with and without a service.
  • The minicart matches the Checkout cart line by line.
  • The cart keeps working when an assembly option SKU has Display on website turned off.
The default minicart doesn't display the assembly options of each line. The split lines follow the Checkout behavior, but you may need a custom component to present the services chosen for each unit.
If you find any issues, contact VTEX Support with the orderFormId of the affected cart.

Step 3 - Deploy the changes

  1. Commit the changes to your discovery.config.js file.
  2. Push the changes to the main branch of your repository.
This triggers a WebOps build. Once it completes, the preserveCartLines flag will be active in your live store.