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.

1POST /v2/cpq/carts/{cart_ID}/items

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.

Apex Remote Service

1CpqAppHandler

Remote Method

1postCartsItems

REST Handler

1APIItemsCartsCpqV2

REST Method

1createCartItems

Package

Communication (vlocity_cmt)

API Parameters and Response Format

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

Resource Information

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.

Note

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.

Note

Example REST Request

Root Add

1POST /v2/cpq/carts/{cart_ID}/items
2Content-Type: application/json
3
4{
5  "validate": true,
6  "items": [
7    {
8      "itemId": "01uxx00000099gxAAA"
9    }
10  ],
11  "cartId": "801xx000003H4WlAAK",
12  "price": true,
13  "quantity": 3
14}

Root Add with caller-supplied price

1POST /v2/cpq/carts/{cart_ID}/items
2Content-Type: application/json
3
4{
5  "validate": true,
6  "items": [
7    {
8      "itemId": "01uxx00000099gxAAA",
9      "fieldsToUpdate": {
10        "UnitPrice": 0,
11        "ListPrice": 0
12      }
13    }
14  ],
15  "cartId": "801xx000003H4WlAAK",
16  "price": false
17}

Child Add

1POST /v2/cpq/carts/{cart_ID}/items
2Content-Type: application/json
3
4{
5  "validate": true,
6  "items": [
7    {
8      "parentId": "802xx000001ni7fAAA",
9      "parentHierarchyPath": "01txx0000006qMaAAI",
10      "itemId": "01uxx00000099iZAAQ",
11      "fieldsToUpdate": {"vlocity_cmt__AttributeSelectedValues__c": null},
12      "parentRecord": {
13        "records": [
14          {
15            "vlocity_cmt__RootItemId__c": { "value": "7769bef4-0a0f-4dd5-be09-a989cad663d7" },
16            "vlocity_cmt__AssetReferenceId__c": { "value": "7769bef4-0a0f-4dd5-be09-a989cad663d7" },
17            "Id": { "value": "802xx000001ni7fAAA" }
18          }
19        ]
20      }
21    }
22  ],
23  "cartId": "801xx000003H4WlAAK",
24  "price": true
25}

Child Add Under Virtual Parent

1POST /v2/cpq/carts/{cart_ID}/items
2Content-Type: application/json
3
4{
5  "validate": true,
6  "items": [
7    {
8      "parentId": "802xx000001ni7fAAA",
9      "itemId": "01uxx00000099kBAAQ",
10      "parentRecord": {
11        "records": [
12          {
13            "isVirtualItem": true,
14            "parentLineItemId": "802xx000001ni7fAAA",
15            "productHierarchyPath": "01txx0000006qMaAAI<01txx0000006tKSAAY"
16          }
17        ]
18      }
19    }
20  ],
21  "cartId": "801xx000003H4WlAAK",
22  "price": true
23}

Example REST Response

Root Bundle Add Response

1{
2  "totalSize": 1,
3  "messages": [
4    {
5      "code": "150",
6      "severity": "INFO",
7      "message": "Successfully added."
8    }
9  ],
10  "actions": {
11    "itempricesupdated": {}
12  },
13  "records": [
14    {
15      "messages": [],
16      "actions": {},
17      "isVirtualItem": false,
18      "maxQuantity": 99999,
19      "ProductCode": "CODE-77706",
20      "hasChildren": true,
21      "IsActive": true,
22      "defaultQuantity": 1,
23      "productGroups": {
24        "totalSize": 1,
25        "messages": [],
26        "records": [ {} ]
27      },
28      "childProducts": {
29        "totalSize": 1,
30        "messages": [],
31        "records": [ {} ]
32      }
33    }
34  ]
35}

Add with noResponseNeeded=true

1{
2  "totalSize": 0,
3  "messages": [
4    {
5      "code": "150",
6      "severity": "INFO",
7      "message": "Successfully added."
8    }
9  ],
10  "actions": {
11    "itempricesupdated": {
12      "rest": {
13        "params": {},
14        "method": "GET",
15        "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/801xx000003H4WlAAK/price?price=false&cartId=801xx000003H4WlAAK"
16      },
17      "remote": { "params": {} },
18      "client": { "params": {} }
19    }
20  }
21}