Cart Item
A Cart Item is a child record of a Salesforce Commerce WebCart that represents one line in a shopper's cart.
Definition
A Cart Item is a child record of a Salesforce Commerce WebCart that represents one line in a shopper's cart. It stores a reference to a Product, the Quantity, the list and sales prices, the delivery group it belongs to, and any item-level price adjustments or taxes. Each Cart Item belongs to exactly one WebCart. Together the Cart Items hold the line-level detail that sits under the cart's overall totals in a store built with B2B Commerce or D2C Commerce.
A Cart Item can be one of two types: a Product line or a Charge line (such as a shipping or handling fee). The object became available in API version 49.0. Cart Items matter because the cart's totals are a rollup of Cart Item math. Pricing, promotions, inventory, and tax all act on individual Cart Items first, and the cart totals are recalculated after. When the cart converts to an order at checkout, each Cart Item maps to an OrderItem, so the line you see while shopping carries through to fulfilment.
How a Cart Item behaves across the Commerce cart lifecycle
The CartItem object and its standard fields
CartItem is a standard object in B2B Commerce and D2C Commerce, available since API version 49.0, and it is queryable with SOQL like any other record. The most-used fields are CartId (the parent WebCart), Product2Id (the catalogue product), Sku, Quantity, ListPrice, and SalesPrice. Amount fields include TotalLineAmount, TotalPrice, and TotalAdjustmentAmount, which capture the line total and the combined effect of any discounts. Type distinguishes a Product line from a Charge line, so a shipping fee and a purchased item can both live in the cart as Cart Items. CartDeliveryGroupId links the item to the delivery group that decides where and how it ships. For bundles, a Cart Item can reference a parent Cart Item, which lets a configured kit hang its component lines off a single header. The standard fields cover most retail and B2B scenarios without any customisation, and orgs that need extra data add custom fields to the object.
Adding a product creates a Cart Item
When a shopper clicks Add to Cart, the storefront creates a Cart Item with the chosen quantity and a reference to the product. The platform then runs cart calculation, which is where pricing, promotions, and inventory get applied to that new line. The Cart Item picks up its SalesPrice from the active price book entry, and the cart totals update to include the new line. Changing the quantity in the cart updates the same Cart Item rather than creating a new one. Removing a line deletes the Cart Item, and the totals recalculate down. Because a Charge line is also a Cart Item, a shipping fee added during checkout appears as its own row of type Charge. This single-object model keeps the cart simple to query: one parent WebCart, many Cart Items, and the totals always derivable from the lines beneath them. The shopper sees a tidy list; the data model stays flat and predictable.
The Cart Calculate API reads and writes Cart Items
The Cart Calculate API is the framework that recalculates a cart whenever it changes. It runs five calculators: Pricing, Promotions, Inventory, Shipping, and Taxes. Pricing, Promotions, and Inventory run during both the cart and checkout phases. Shipping and Taxes run only during checkout by default, since you rarely know the address or final cost until then. Each calculator receives the current cart state, reads the Cart Items it cares about, does its work, and writes updated values back before passing control to the next calculator. To customise this, a developer writes an orchestrator that extends the CartExtension.CartCalculate class and registers it for the Commerce_Domain_Cart_Calculate extension point. The orchestrator decides which calculators run and in what order. Custom calculators for tax or inventory plug into the same flow. The point to remember is that almost every calculation in Commerce operates at the Cart Item level first, with the WebCart totals following from there.
Pricing and promotions on each Cart Item
Every Cart Item carries both a ListPrice (the catalogue price from the price book entry) and a SalesPrice (the price after pricing rules apply). The two can differ because of buyer-specific pricing: an entitlement policy, a negotiated contract, a volume break, or a promotion can all move the price for a given Buyer Account. The Pricing calculator writes the effective SalesPrice, and the line amounts build on it. Promotions then split into line-level and cart-level. A line-level promotion discounts specific Cart Items, such as a buy-one-get-one offer on a SKU. A cart-level promotion discounts the whole cart, then spreads the saving across qualifying lines. Both write to the adjustment amount, which reduces the line total. Because several promotions can apply at once, test how they stack so the math lands where you expect. In subscription scenarios with Commerce Subscription Plus, extra fields describe the selling model, term, and billing frequency, so recurring lines price differently while still living in the same cart.
Delivery groups, bundles, and inventory
A WebCart can split its lines across more than one shipment, and the CartDeliveryGroup is what makes that possible. Each Cart Item points to a delivery group through CartDeliveryGroupId, which records the ship-to address and the chosen delivery method for that set of lines. Splitting a cart into two delivery groups lets one group ship to a job site and another to head office, with shipping and tax calculated per group at checkout. Bundles use the parent Cart Item relationship: a configured kit has a header Cart Item with its component lines referencing it as their parent. Inventory runs per Cart Item too. The Inventory calculator checks availability for each line against the inventory source. An out-of-stock line can either block checkout, which is the safer pattern, or be flagged for backorder, depending on configuration. Different product types deserve different rules, so perishable goods usually get stricter checks than industrial parts on a longer lead time.
Conversion to OrderItem at checkout
When the shopper completes checkout, the Cart to Order step copies the cart into order records. Each Cart Item maps to an OrderItem on the resulting Order. The mapping copies Product2Id, Quantity, and TotalLineAmount across, and the CartDeliveryGroup becomes an OrderDeliveryGroup so the shipment split survives the handoff. Adjustments and taxes carry over into their order-side equivalents. Custom fields map automatically when a field with the same API name exists on both the Cart and Order objects (and on OrderSummary), which is how an org keeps bespoke line data through the conversion. After this point, fulfilment, returns, and customer service work against OrderItem and OrderSummary, not the cart. The cart and its Cart Items have done their job. Validating this mapping in a sandbox before go-live matters, because the conversion contract is exactly what downstream order management and support depend on. A field that fails to map quietly drops data that nobody notices until an order is short.
Reporting and analytics on Cart Items
Cart Items answer line-level questions that the parent WebCart cannot. Querying Cart Items tells you which products get added to carts, which lines get removed before checkout, which promotions move which SKUs, and which configurations shoppers assemble most often. Cart-level reporting answers aggregate questions like average cart value, while Cart Item reporting answers product-level questions like add-to-cart rate by SKU. Tracking adds-then-removes is especially useful: a product with a high abandon rate is usually signalling a pricing or user-experience problem worth investigating. Because the SalesPrice and ListPrice both live on the line, you can compare catalogue price against realised price across thousands of carts and spot where discounting is heaviest. Most of the operational analytics that a Commerce team relies on, from conversion funnels to promotion effectiveness, are built by reading Cart Item data rather than the cart header. The line is where the behaviour lives.
Configure cart calculation for Cart Items
You do not create Cart Items directly; the storefront creates them when a shopper adds products. What you do configure is the Cart Calculate API, which is the framework that prices, promotes, checks inventory, and taxes each Cart Item. Here is how to set up custom cart calculation in a B2B or D2C store.
- Decide which calculators you need
The Cart Calculate API ships Pricing, Promotions, Inventory, Shipping, and Taxes calculators. Confirm which standard ones meet your needs and where you require a custom integration, such as an external tax engine or a third-party inventory source.
- Write an orchestrator
Create an Apex class that extends CartExtension.CartCalculate and override the calculate method. The orchestrator controls which calculators run and in what sequence when the cart changes.
- Register the extension point
Register your orchestrator for the Commerce_Domain_Cart_Calculate extension point so the platform invokes it on cart updates. Without registration, the default calculation runs instead.
- Plug in custom calculators
For a custom tax or inventory integration, implement the matching calculator and have your orchestrator call it. The calculator reads the Cart Items, computes its result, and writes values back to the cart.
- Test on representative carts
Validate in a sandbox with carts that mix product and charge lines, multiple delivery groups, and stacked promotions. Confirm the totals and the Cart to Order mapping before you enable it in production.
Pricing, Promotions, and Inventory run during both cart and checkout; Shipping and Taxes run only at checkout by default.
Extend CartExtension.CartCalculate and override calculate to control calculator order and which ones execute.
Commerce_Domain_Cart_Calculate is the registration name the platform uses to find and invoke your orchestrator.
Choose whether an out-of-stock Cart Item blocks checkout or is flagged for backorder, tuned per product type.
- Shipping and Taxes do not run during the cart phase by default, so cart-stage totals exclude them until checkout.
- A custom field only maps from Cart Item to OrderItem if the same API name exists on both Cart and Order (and OrderSummary).
- Loading and saving the in-memory CartExtension.CartItem is done by Salesforce, not by your Apex; you read and adjust, the platform persists.
- Stacked line-level and cart-level promotions can interact in surprising ways; test the combined discount on real carts.
Prefer this walkthrough as its own page? How to Cart Item in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Cart Item.
Hands-on resources to go deeper on Cart Item.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Discussion
Loading discussion…