Add Items to Cart

Add items to the cart along with any required child products that are specified in the request body. Compatibility and pricing rules are run against the cart.

You must use the fieldsToUpdate parameter to update any default line item value.

Add line items to cart replaces the OmniCPQServiceWrapper addProducts method.

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.

When you add child items to the cart:

Specify a parentRecord node in the input request.
In the parentRecord node, specify the productHierarchyPath field.
If the immediate parent of the child item that you’re adding is a virtual parent, then also include these fields:
- The Id field in the parentRecord node. Ensure that it’s the PricebookEntryId of the immediate virtual parent.
- The parentId field in the items node. Ensure that it’s the lineItemId of the immediate real parent.

Remote Method

1postCartsItems

In releases prior to CME Spring ‘20, the postCartsItems method supports the addition of one item at a time. If you must add multiple items, make multiple postCartsItems calls.

With CME Spring ‘20 and later releases, the itemId parameter supports multiple comma-separated values when adding root and child items via postCartsItems method calls if UOWMode is set to true.

When the items array contains the same pricebook entry ID more than once, Classic Cart APIs collapse those entries into a single cart line item. To add more than one distinct line of the same product, make separate postCartsItems calls. To increase quantity on one line, pass a single item with the desired quantity or fieldsToUpdate.quantity.

Note

REST Handler

1APIItemsCartsCpqV2

Apex Remote Service

1CpqAppHandler

Apex Remote Input Map

1{
2 "methodName": "postCartsItems",
3 "cartId": "801360000008eNU",
4 "items": [
5  {
6  {
7   "itemId": "01t36000000pfcKAAQ",
8   "parentId": "01t36000000pfcKAAZ",
9   "fieldsToUpdate": {
10    "quantity": 6,
11    "vlocity_cmt__RecurringManualDiscount__c": 10,
12    "SampleDateTime__c": "2024/10/10 11:46"
13   }
14  }
15 }
16 ]
17}
18"itemId" = "pricebookEntryId",
19"parentId" = "OrderItem.Id"

Package

Communication (vlocity_cmt)

API Parameters and Response Format

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

For the fieldsToUpdate attribute, ensure to configure Date and Time values as per locale configuration without the seconds value. For example, 2024/10/10 11:46 for the Japanese locale. See Supported Date and Time Formats (ICU). Standard Cart APIs ignore locale and require ISO dates (yyyy-MM-dd).

Important

Resource Information

Response Format	JSON
Resource URL	`/services/apexrest/{namespace}/v2/cpq/carts/{cart_ID}/items`

Example Request

For more information about levelBasedApproach, see Configuring Cart Item Refresh Levels.

Note

1POST
2{
3  "items": [
4    {
5      "itemId": "01uf4000000gmRTAAY",
6      "parentId": "802f4000000PZ1VAAW",
7      "parentRecord": {
8        "records": [
9          {
10            "messages": [],
11            "displaySequence": -1,
12            "Id": {
13              "messages": [],
14              "label": "Order Product ID",
15              "hidden": false,
16              "fieldName": "Id",
17              "editable": false,
18              "dataType": "ID",
19              "value": "802f4000000PZ1VAAW"
20            },
21            "UnitPrice": {
22              "messages": [],
23              "label": "Unit Price",
24              "hidden": true,
25              "fieldName": "UnitPrice",
26              "editable": false,
27              "dataType": "CURRENCY",
28              "value": 358.95
29            },
30            "productId": "01tf4000000Kd0uAAC",
31            "defaultQuantity": 1,
32            "minQuantity": 0,
33            "maxQuantity": 99999,
34            "groupMinQuantity": 0,
35            "groupMaxQuantity": 99999,
36            "sequenceNumber": 1,
37            "productHierarchyPath": "01tf4000000Kd0uAAC",
38            "itemType": "lineItem",
39            "childProducts": {
40              "records": [
41                {
42                  "Name": {
43                    "label": "Product Name",
44                    "value": "PRODUCT-77151"
45                  },
46                  "UnitPrice": {
47                    "label": "List Price",
48                    "value": 0
49                  },
50                  "vlocity_cmt__RecurringPrice__c": {
51                    "label": "Recurring Price",
52                    "value": 0
53                  },
54                  "Product2Id": {
55                    "label": "Product ID",
56                    "value": "01tf4000000Kd0zAAC"
57                  },
58                  "Pricebook2Id": {
59                    "label": "Price Book ID",
60                    "value": "01sf4000003LYn3AAG"
61                  },
62                  "Id": {
63                    "label": "Price Book Entry ID",
64                    "value": "01uf4000000gmRTAAY"
65                  },
66                  "defaultQuantity": 0,
67                  "productId": "01tf4000000Kd0zAAC",
68                  "Product2": {
69                    "Name": "PRODUCT-77151",
70                    "RecordTypeId": "012f40000004zEOAAY",
71                    "vlocity_cmt__IsConfigurable__c": false,
72                    "vlocity_cmt__SubType__c": "None",
73                    "vlocity_cmt__Type__c": "None"
74                  },
75                  "messages": [],
76                  "actions": {
77                    "addtocart": {
78                      "rest": {
79                        "params": {
80                          "price": true,
81                          "validate": true,
82                          "includeAttachment": false,
83                          "pagesize": 20,
84                          "items": [
85                            {
86                              "parentId": "802f4000000PZ1VAAW",
87                              "quantity": 0,
88                              "itemId": "01uf4000000gmRTAAY"
89                            }
90                          ],
91                          "cartId": "801f4000000ChZjAAK"
92                        },
93                        "method": "POST",
94                        "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/801f4000000ChZjAAK/items"
95                      },
96                      "remote": {
97                        "params": {
98                          "price": true,
99                          "validate": true,
100                          "includeAttachment": false,
101                          "pagesize": 20,
102                          "items": [
103                            {
104                              "parentId": "802f4000000PZ1VAAW",
105                              "quantity": 0,
106                              "itemId": "01uf4000000gmRTAAY"
107                            }
108                          ],
109                          "cartId": "801f4000000ChZjAAK",
110                          "methodName": "postCartsItems"
111                        }
112                      },
113                      "client": {
114                        "params": {
115                          "pagesize": 0,
116                        }
117                      }
118                    }
119                  }
120                }
121              ]
122            },
123            "vlocity_cmt__RecurringPrice__c": 527.96,
124            "name": "PRODUCT-39982",
125            "provisioningStatus": "New",
126            "Product2Id": "01tf4000000Kd0uAAC",
127            "PricebookEntryId": {
128              "messages": [],
129              "label": "Price Book Entry ID",
130              "hidden": false,
131              "fieldName": "PricebookEntryId",
132              "editable": false,
133              "dataType": "REFERENCE",
134              "value": "01uf4000000gmRJAAY"
135            },
136            "Quantity": {
137              "messages": [],
138              "label": "Quantity",
139              "hidden": false,
140              "fieldName": "Quantity",
141              "editable": true,
142              "dataType": "DOUBLE",
143              "value": 1
144            },
145            "vlocity_cmt__OneTimeTotal__c": {
146              "messages": [],
147              "label": "One Time Total",
148              "hidden": false,
149              "fieldName": "vlocity_cmt__OneTimeTotal__c",
150              "editable": false,
151              "dataType": "CURRENCY",
152              "value": 358.95
153            },
154            "vlocity_cmt__RecurringTotal__c": {
155              "messages": [],
156              "label": "Recurring Total",
157              "hidden": false,
158              "fieldName": "vlocity_cmt__RecurringTotal__c",
159              "editable": false,
160              "dataType": "CURRENCY",
161              "value": 527.96
162            },
163            "vlocity_cmt__ProvisioningStatus__c": {
164              "messages": [],
165              "label": "Provisioning Status",
166              "hidden": true,
167              "fieldName": "vlocity_cmt__ProvisioningStatus__c",
168              "editable": false,
169              "dataType": "STRING",
170              "value": "New"
171            },
172            "vlocity_cmt__ProductHierarchyPath__c": {
173              "messages": [],
174              "label": "Product Hierarchy Path",
175              "hidden": true,
176              "fieldName": "vlocity_cmt__ProductHierarchyPath__c",
177              "editable": false,
178              "dataType": "STRING",
179              "value": "01tf4000000Kd0uAAC"
180            },
181            "vlocity_cmt__LineNumber__c": {
182              "messages": [],
183              "label": "LineNumber",
184              "hidden": true,
185              "fieldName": "vlocity_cmt__LineNumber__c",
186              "editable": false,
187              "dataType": "STRING",
188              "value": "0001"
189            },
190            "vlocity_cmt__RootItemId__c": {
191              "messages": [],
192              "label": "RootItemId",
193              "hidden": true,
194              "fieldName": "vlocity_cmt__RootItemId__c",
195              "editable": false,
196              "dataType": "STRING",
197              "value": "802f4000000PZ1VAAW"
198            },
199            "ListPrice": {
200              "messages": [],
201              "label": "List Price",
202              "hidden": true,
203              "fieldName": "ListPrice",
204              "editable": false,
205              "dataType": "CURRENCY",
206              "value": 358.95
207            },
208            "vlocity_cmt__OneTimeCharge__c": {
209              "messages": [],
210              "label": "One Time Charge",
211              "hidden": true,
212              "fieldName": "vlocity_cmt__OneTimeCharge__c",
213              "editable": false,
214              "dataType": "CURRENCY",
215              "value": 358.95
216            },
217            "vlocity_cmt__RecurringCharge__c": {
218              "messages": [],
219              "label": "Recurring Charge",
220              "hidden": true,
221              "fieldName": "vlocity_cmt__RecurringCharge__c",
222              "editable": false,
223              "dataType": "CURRENCY",
224              "value": 527.96
225            },
226            "vlocity_cmt__RecurringManualDiscount__c": {
227              "messages": [],
228              "label": "Recurring Manual Discount",
229              "hidden": false,
230              "fieldName": "vlocity_cmt__RecurringManualDiscount__c",
231              "editable": true,
232              "dataType": "PERCENT",
233              "value": 0
234            },
235            "vlocity_cmt__OneTimeManualDiscount__c": {
236              "messages": [],
237              "label": "One Time Manual Discount",
238              "hidden": false,
239              "fieldName": "vlocity_cmt__OneTimeManualDiscount__c",
240              "editable": true,
241              "dataType": "PERCENT",
242              "value": 0
243            },
244            "vlocity_cmt__ParentItemId__c": {
245              "messages": [],
246              "label": "ParentItemId",
247              "hidden": true,
248              "fieldName": "vlocity_cmt__ParentItemId__c",
249              "editable": false,
250              "dataType": "STRING"
251            },
252            "PricebookEntry": {
253              "Product2Id": "01tf4000000Kd0uAAC",
254              "Pricebook2Id": "01sf4000003LYn3AAG",
255              "Id": "01uf4000000gmRJAAY",
256              "Product2": {
257                "Name": "PRODUCT-39982",
258                "Id": "01tf4000000Kd0uAAC",
259                "vlocity_cmt__Type__c": "None",
260                "vlocity_cmt__IsConfigurable__c": "false"
261              }
262            },
263            "Product2": {
264              "Name": "PRODUCT-39982",
265              "RecordTypeId": "012f40000004zEOAAY",
266              "vlocity_cmt__IsConfigurable__c": false,
267              "vlocity_cmt__SubType__c": "None",
268              "vlocity_cmt__Type__c": "None"
269            },
270            "vlocity_cmt__ItemName__c": {
271              "messages": [],
272              "label": "Item Name",
273              "hidden": false,
274              "fieldName": "vlocity_cmt__ItemName__c",
275              "editable": true,
276              "dataType": "STRING"
277            },
278            "actions": {
279              "addtocart": {
280                "rest": {
281                  "params": {
282                    "price": true,
283                    "validate": true,
284                    "includeAttachment": false,
285                    "pagesize": 20,
286                    "items": [
287                      {
288                        "parentId": "802f4000000PZ1VAAW",
289                        "quantity": 1,
290                        "itemId": "01uf4000000gmRJAAY"
291                      }
292                    ],
293                    "cartId": "801f4000000ChZjAAK"
294                  },
295                  "method": "POST",
296                  "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/801f4000000ChZjAAK/items"
297                },
298                "remote": {
299                  "params": {
300                    "price": true,
301                    "validate": true,
302                    "includeAttachment": false,
303                    "pagesize": 20,
304                    "items": [
305                      {
306                        "parentId": "802f4000000PZ1VAAW",
307                        "quantity": 1,
308                        "itemId": "01uf4000000gmRJAAY"
309                      }
310                    ],
311                    "cartId": "801f4000000ChZjAAK",
312                    "methodName": "postCartsItems"
313                  }
314                },
315                "client": {
316                  "params": {
317                    "pagesize": 0,
318                  }
319                }
320              },
321              "cloneitem": {
322                "rest": {
323                  "params": {
324                    "pagesize": 0,
325                    "items": [
326                      {
327                        "quantity": 0,
328                        "itemId": "802f4000000PZ1VAAW"
329                      }
330                    ],
331                    "cartId": "801f4000000ChZjAAK"
332                  },
333                  "method": "POST",
334                  "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/801f4000000ChZjAAK/items/clone"
335                },
336                "remote": {
337                  "params": {
338                    "pagesize": 0,
339                    "items": [
340                      {
341                        "quantity": 0,
342                        "itemId": "802f4000000PZ1VAAW"
343                      }
344                    ],
345                    "cartId": "801f4000000ChZjAAK",
346                    "methodName": "cloneItems"
347                  }
348                },
349                "client": {
350                  "params": {
351                    "pagesize": 0,
352                  }
353                }
354              }
355            },
356            "isVirtualItem": false
357          }
358        ]
359      }
360    }
361  ],
362  "pagesize": 0,
363  "levelBasedApproach": false
364}

To use this API to pass child line items, you must also specify the Price Book Entry ID.

1{
2   "items":[
3      {
4         "parentRecord":{
5            "records":[
6               {
7                  "Id":{
8                     "label":"Price Book Entry ID",
9                     "value":"01uf4000000gmRJAAY"
10                  },
11                  "productHierarchyPath":""
12               }
13            ]
14         },
15         "parentId":" ",
16         "itemId":""
17      }
18   ]
19}

Example Result

An entire result can be thousands of lines long. This example has been truncated.

Note

1{
2   "totalSize": 1,
3   "messages": [{
4      "severity": "INFO",
5      "messageId": null,
6      "message": "Successfully added.",
7      "code": "150",
8      "actions": {}
9   }],
10   "records": [{
11      "messages": [],
12      "actions": {
13         "addtocart": {
14            "rest": {
15               "params": {
16                  "includeAttachment": false,
17                  "pagesize": 20,
18                  "lastRecordId": null,
19                  "query": null,
20                  "items": [{
21                     "parentId": "80241000000HalXAAS",
22                     "quantity": 1,
23                     "itemId": "01u41000001QPs5AAG"
24                  }]
25               },
26               "method": "POST",
27               "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items"
28            },
29            "remote": {
30               "params": {
31                  "price": true,
32                  "validate": true,
33                  "includeAttachment": false,
34                  "pagesize": 20,
35                  "lastRecordId": null,
36                  "query": null,
37                  "items": [{
38                     "parentId": "80241000000HalXAAS",
39                     "quantity": 1,
40                     "itemId": "01u41000001QPs5AAG"
41                  }],
42                  "cartId": "80141000000Cg8HAAS",
43                  "methodName": "postCartsItems"
44               }
45            },
46            "client": {
47               "params": {}
48            }
49         },
50         "updateitems": {
51            "rest": {
52            "params": {
53               "fields": null,
54               "price": true,
55               "validate": true,
56               "filters": null,
57               "includeAttachment": false,
58               "pagesize": 20,
59               "lastRecordId": null,
60               "query": null,
61               "items": [{
62                  "itemId": "80241000000HalXAAS"
63               }]
64            },
65            "method": "PUT",
66            "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items"
67         },
68         "remote": {
69            "params": {
70               "fields": null,
71               "price": true,
72               "validate": true,
73               "filters": null,
74               "includeAttachment": false,
75               "pagesize": 20,
76               "lastRecordId": null,
77               "query": null,
78               "items": [{
79                  "itemId": "80241000000HalXAAS"
80               }],
81               "cartId": "80141000000Cg8HAAS",
82               "methodName": "putCartsItems"
83            }
84         },
85         "client": {
86            "params": {}
87         }
88      },
89      "deleteitem": {
90         "rest": {
91            "params": {},
92            "method": "DELETE",
93            "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items/80241000000HalXAAS?pagesize=20&amp;includeAttachment=false&amp;validate=true&amp;price=true"
94         },
95         "remote": {
96         "params": {
97            "price": true,
98            "validate": true,
99            "filters": null,
100            "includeAttachment": false,
101            "pagesize": 20,
102            "lastRecordId": null,
103            "query": null,
104            "id": "80241000000HalXAAS",
105            "cartId": "80141000000Cg8HAAS",
106            "methodName": "deleteCartsItems"
107         }
108      },
109      "client": {
110         "params": {}
111      }
112   },
113      "cloneitem": {
114         "rest": {
115            "params": {
116               "items": [{
117                  "itemId": "80241000000HalXAAS"
118               }]
119            },
120            "method": "POST",
121            "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items/clone"
122         },
123         "remote": {
124            "params": {
125               "id": "80241000000HalXAAS",
126               "cartId": "80141000000Cg8HAAS",
127               "methodName": "cloneItems"
128            }
129         },
130         "client": {
131            "params": {}
132         }
133      },
134      "modifyattributes": {
135         "rest": {
136            "params": {
137               "fields": null,
138               "items": [{
139                  "itemId": "80241000000HalXAAS"
140               }]
141            },
142            "method": "PUT",
143            "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items/80241000000HalXAAS/itemattributes"
144         },
145         "remote": {
146            "params": {
147               "fields": null,
148               "items": [{
149                  "itemId": "80241000000HalXAAS"
150               }],
151               "itemId": "80241000000HalXAAS",
152               "cartId": "80141000000Cg8HAAS",
153               "methodName": "putItemAttributes"
154               }
155            },
156            "client": {
157               "params": {}
158            }
159         }
160      },
161      "displaySequence": -1,
162      "Id": {
163         "value": "80241000000HalXAAS",
164         "messages": [],
165         "label": "Order Product ID",
166         "hidden": false,
167         "fieldName": "Id",
168         "editable": false,
169         "dataType": "ID",
170         "actions": {}
171         },
172         "Pricebook2Id": "01s41000005dPYQAA2",
173         "Product2Id": "01t41000000sYZVAA2",
174         "UnitPrice": {
175            "value": 2.00,
176            "messages": [],
177            "label": "Unit Price",
178            "hidden": false,
179            "fieldName": "UnitPrice",
180            "editable": true,
181            "dataType": "CURRENCY",
182            "actions": {}
183         },
184         "Name": "Parent 1",
185         "IsActive": true,
186         "Product2": {
187            "attributes": {
188               "type": "Product2",
189               "url": "/services/data/v38.0/sobjects/Product2/01t41000000sYZVAA2"
190            },
191            "Id": "01t41000000sYZVAA2",
192            "Name": "Parent 1",
193            "vlocity_cmt__IsConfigurable__c": false,
194            "vlocity_cmt__Type__c": "None",
195            "vlocity_cmt__SubType__c": "None",
196            "RecordTypeId": "012410000006OWUAA2",
197            "vlocity_cmt__JSONAttribute__c": null
198         },
199         "productId": "01t41000000sYZVAA2",
200         "defaultQuantity": 1.0,
201         "minQuantity": 0.0,
202         "maxQuantity": 99999.0,
203         "groupMinQuantity": 0,
204         "groupMaxQuantity": 99999,
205         "sequenceNumber": 1.00,
206         "productChildItemDefinition": {
207            "attributes": {
208               "type": "vlocity_cmt__ProductChildItem__c",
209               "url": "/services/data/v38.0/sobjects/vlocity_cmt__ProductChildItem__c/a2541000000G0A1AAK"
210            },
211            "Id": "a2541000000G0A1AAK",
212            "Name": "Root PCI",
213            "vlocity_cmt__IsVirtualItem__c": false,
214            "vlocity_cmt__Quantity__c": 1,
215            "vlocity_cmt__MaxQuantity__c": 99999,
216            "vlocity_cmt__MinQuantity__c": 0,
217            "vlocity_cmt__MaximumChildItemQuantity__c": 99999,
218            "vlocity_cmt__MinimumChildItemQuantity__c": 0,
219            "vlocity_cmt__IsOverride__c": false,
220            "vlocity_cmt__ParentProductId__c": "01t41000000sYZVAA2",
221            "vlocity_cmt__ChildLineNumber__c": "1",
222            "vlocity_cmt__SeqNumber__c": 1.00,
223            "vlocity_cmt__CollapseHierarchy__c": false,
224            "vlocity_cmt__IsRootProductChildItem__c": true,
225            "vlocity_cmt__ParentProductId__r": {
226               "attributes": {
227                  "type": "Product2",
228                  "url": "/services/data/v38.0/sobjects/Product2/01t41000000sYZVAA2"
229               },
230               "Id": "01t41000000sYZVAA2",
231               "Name": "Parent 1"
232            }
233         },
234         "productHierarchyPath": "01t41000000sYZVAA2",
235         "name": "Parent 1",
236         "isVirtualItem": false,
237         "itemType": "lineItem",
238         "PricebookEntryId": {
239            "value": "01u41000001QPs5AAG",
240            "messages": [],
241            "label": "Price Book Entry ID",
242            "hidden": false,
243            "fieldName": "PricebookEntryId",
244            "editable": false,
245            "dataType": "REFERENCE",
246            "actions": {}
247         },
248...

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}