Add Items to Cart

The postCartsItems API allows clients to add one or more products to an existing cart. This is a core operation in any CPQ (Configure, Price, Quote) process. The API enforces business rules such as product eligibility, quantity constraints, and cart state validation, ensuring that only valid items are added. It can trigger pricing, validation, and promotion logic as needed. Robust error handling ensures atomicity—either all items are added successfully, or none are—while clear error messages guide users in case of issues. The API is designed for extensibility, supporting guest users.

This API supports the guest user enhancements that Salesforce introduced with the Winter ‘21 release. To encrypt and decrypt data for guest users, use the UserSecurity class with this API. See Guest User Technical Details.

For additional information, ​see UserSecurity Class and CPQ and Digital Commerce Changes for Guest Users.

Communication (vlocity_cmt)

For API parameter names and descriptions, see Cart-Based API Swagger Reference.

  • Resource URL: /services/apexrest/{namespace}/v2/cpq/carts/{cart_ID}/items
  • HTTP Method: POST
  • Content-Type: application/json
  • Response Format: JSON

Starting in the Winter’27 release, you can pass UnitPrice and ListPrice in fieldsToUpdate. To keep caller-supplied price values, set price to false. When price is true (the default), the pricing engine runs after fieldsToUpdate is applied and can overwrite price fields from pricebook entries and pricing plan rules. Use price: false for contract pricing, zero-price items, or any case where the caller owns the price.

Each object in the items array creates a distinct cart line item, even when itemId is the same pricebook entry. Classic Cart APIs collapse duplicate pricebook entry IDs in one call into a single line item. To add quantity on one line, pass a single item with quantity. Date fields in fieldsToUpdate must use ISO format (yyyy-MM-dd). Standard Cart APIs do not parse locale-based values such as dd/mm/yyyy.