Get Cart Items

Return cart items and their configurable attributes based on specified criteria.

Item name, description, and price
Configurable attributes for the item
Links to further actions
Messages per item
Whether to expand all the child items in the bundle

1GET /v2/cpq/carts/{cart_ID}/items?query={query}&lastRecordId=(n)&pagesize={n}&filters={filter}&fields={field1,field2}&validate={true/false}&price={true/false}

If the value for pagesize parameter is not provided, it defaults to 20. To fetch or price more than 20 items, specify pagesize explicitly.
Customers can search for specific products even with over 10,000 PriceListEntry records if the these conditions are met.
- The product must be orderable.
- Filter parameters should not contain underscores.
- Only Product2-related fields can be queried or filtered.

Note

Fieldset as a parameter for this API is not supported. If the fieldset parameter is passed, a runtime error occurs.

This API can be called either through REST or through Apex remote calls. The default value for the price parameter is true. If price=false is not specified, pricing is executed by default. Specify price=false if you do not want to execute pricing.

In Salesforce Industries Communications, Media, and Energy Fall ‘20 and later releases, the getCarts validate parameter has a default value of _True*, so the API will return validation messages. If validate=false is not specified, validation messages are returned by default. Specify validate=false in the UI if you do not want to receive validation messages.

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.

Get Cart Items Trim Mode

Trim Mode is an optimization feature that reduces the payload size of the GetCartItems API response. Instead of returning the full set of cart item fields, Trim Mode restricts the response to only what is explicitly required.

When enabled, the API response includes these:

A fixed set of 22 default fields (identity, hierarchy, and status)
Fields specified via the fields query parameter
Fields defined in the GCITrimFieldsToInclude field set in Salesforce

All other fields are removed from the response. Structural nodes such as PricebookEntry, Product2, and productChildItemDefinition are always preserved.

Trim Mode applies only to:

getCartItemList
getCartItemListById

Important

See, Enabling Trim Mode.

Remote Method

1getCartsItems

REST Handler

1APIItemsCartsCpqV2

Apex Remote Service

1CpqAppHandler

Apex Remote Input Map

1{
2 methodName: getCartsItems,
3 cartId: 801360000008 eNU,
4 query: "iphone",
5 lastItemId: "01t36000000pfcKAAQ",
6 pagesize: 20,
7 includeAttachment: false,
8 fields: fields = Quantity,
9 vlocity_cmt__RecurringCharge__c,
10 vlocity_cmt__OneTimeTotal__c,
11 vlocity_cmt__BillingAccountId__r.Name,
12 vlocity_cmt__ServiceAccountId__r.Name,
13 vlocity_cmt__PremisesId__r.Name
14 filter: vlocity_cmt__ServiceAccountId__c: 991360000008 eNU_991360000008eNY,
15 vlocity_cmt__BillingAccount__c: 01 t36000000pfcKAAQ_01t36000000pfcKAAQ
16}
17cartId = order.Id, opportunity.Id, quote.Id

Package

Communication (vlocity_cmt)

API Parameters and Response Format

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

Resource Information

Response Format	JSON
Resource URL	`/services/apexrest/{namespace}/v2/cpq/carts/{cart_ID}/items?query={query}&lastRecordId=(n)&pagesize={n}&filters={filter}&fields={field1,field2}&validate={true/false}&price={true/false}`

Example Request

1GET
2/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8H/items?pagesize=5

Example Response

1{
2   "totalSize": 1,
3   "messages": [],
4   "records": [{
5      "messages": [],
6      "actions": {
7         "addtocart": {
8            "rest": {
9               "params": {
10                  "includeAttachment": false,
11                  "pagesize": 5,
12                  "lastRecordId": null,
13                  "query": null,
14                  "items": [{
15                     "parentId": "80241000000HalcAAC",
16                     "quantity": 1,
17                     "itemId": "01u41000001QPtsAAG"
18                   }]
19               },
20               "method": "POST",
21               "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items"
22            },
23            "remote": {
24               "params": {
25                  "price": true,
26                  "validate": true,
27                  "includeAttachment": false,
28                  "pagesize": 5,
29                  "lastRecordId": null,
30                  "query": null,
31                  "items": [{
32                     "parentId": "80241000000HalcAAC",
33                     "quantity": 1,
34                     "itemId": "01u41000001QPtsAAG"
35                  }],
36                  "cartId": "80141000000Cg8HAAS",
37                  "methodName": "postCartsItems"
38               }
39            },
40            "client": {
41               "params": {}
42            }
43         },
44         "updateitems": {
45            "rest": {
46               "params": {
47                  "fields": null,
48                  "price": true,
49                  "validate": true,
50                  "filters": null,
51                  "includeAttachment": false,
52                  "pagesize": 5,
53                  "lastRecordId": null,
54                  "query": null,
55                     "items": [{
56                        "itemId": "80241000000HalcAAC"
57                     }]
58                  },
59                  "method": "PUT",
60                  "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items"
61            },
62               "remote": {
63                  "params": {
64                      "fields": null,
65                      "price": true,
66                      "validate": true,
67                      "filters": null,
68                      "includeAttachment": false,
69                      "pagesize": 5,
70                      "lastRecordId": null,
71                      "query": null,
72                      "items": [{
73                         "itemId": "80241000000HalcAAC"
74                     }],
75                     "cartId": "80141000000Cg8HAAS",
76                     "methodName": "putCartsItems"
77                  }
78               },
79               "client": {
80                  "params": {}
81               }
82            },
83            "deleteitem": {
84               "rest": {
85                  "params": {},
86                  "method": "DELETE",
87                  "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items/80241000000HalcAAC?pagesize=5&amp;includeAttachment=false&amp;validate=true&amp;price=true"
88            },
89            "remote": {
90               "params": {
91                  "price": true,
92                  "validate": true,
93                  "filters": null,
94                  "includeAttachment": false,
95                  "pagesize": 5,
96                  "lastRecordId": null,
97                  "query": null,
98                  "id": "80241000000HalcAAC",
99                  "cartId": "80141000000Cg8HAAS",
100                  "methodName": "deleteCartsItems"
101               }
102            },
103            "client": {
104               "params": {}
105            }
106         },
107         "cloneitem": {
108            "rest": {
109               "params": {
110                  "items": [{
111                     "itemId": "80241000000HalcAAC"
112               }]
113            },
114            "method": "POST",
115            "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items/clone"
116         },
117         "remote": {
118            "params": {
119               "id": "80241000000HalcAAC",
120               "cartId": "80141000000Cg8HAAS",
121               "methodName": "cloneItems"
122           }
123         },
124         "client": {
125            "params": {}
126         }
127      },
128      "modifyattributes": {
129         "rest": {
130            "params": {
131               "fields": null,
132               "items": [{
133                  "itemId": "80241000000HalcAAC"
134            }]
135         },
136         "method": "PUT",
137         "link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items/80241000000HalcAAC/itemattributes"
138      },
139      "remote": {
140         "params": {
141            "fields": null,
142            "items": [{
143               "itemId": "80241000000HalcAAC"
144            }],
145            "itemId": "80241000000HalcAAC",
146            "cartId": "80141000000Cg8HAAS",
147            "methodName": "putItemAttributes"
148         }
149      },
150      "client": {
151         "params": {}
152      }
153   }
154},
155   "displaySequence": -1,
156   "Id": {
157      "value": "80241000000HalcAAC",
158      "messages": [],
159      "label": "Order Product ID",
160      "hidden": false,
161      "fieldName": "Id",
162      "editable": false,
163      "dataType": "ID",
164      "actions": {}
165   },
166   "Pricebook2Id": "01s41000005dPYQAA2",
167   "Product2Id": "01t41000000sYaSAAU",
168   "UnitPrice": {
169      "value": 1.00,
170      "messages": [],
171      "label": "Unit Price",
172      "hidden": false,
173      "fieldName": "UnitPrice",
174      "editable": true,
175      "dataType": "CURRENCY",
176      "actions": {}
177   },
178   "Name": "GC 2",
179   "IsActive": true,
180   "Product2": {
181      "attributes": {
182         "type": "Product2",
183         "url": "/services/data/v38.0/sobjects/Product2/01t41000000sYaSAAU"
184      },
185      "Id": "01t41000000sYaSAAU",
186      "Name": "GC 2",
187      "vlocity_cmt__IsConfigurable__c": false,
188      "vlocity_cmt__Type__c": "None",
189      "vlocity_cmt__SubType__c": "None",
190      "RecordTypeId": "012410000006OWUAA2",
191      "vlocity_cmt__JSONAttribute__c": null
192   },
193   "productId": "01t41000000sYaSAAU",
194   "defaultQuantity": 1.0,
195   "minQuantity": 0.0,
196   "maxQuantity": 99999.0,
197   "groupMinQuantity": 0,
198   "groupMaxQuantity": 99999,
199   "sequenceNumber": 1.00,
200   "productChildItemDefinition": {
201      "attributes": {
202         "type": "vlocity_cmt__ProductChildItem__c",
203         "url": "/services/data/v38.0/sobjects/vlocity_cmt__ProductChildItem__c/a2541000000G0AGAA0"
204      },
205      "Id": "a2541000000G0AGAA0",
206      "Name": "Root PCI",
207      "vlocity_cmt__IsVirtualItem__c": false,
208      "vlocity_cmt__Quantity__c": 1,
209      "vlocity_cmt__MaxQuantity__c": 99999,
210      "vlocity_cmt__MinQuantity__c": 0,
211      "vlocity_cmt__MaximumChildItemQuantity__c": 99999,
212      "vlocity_cmt__MinimumChildItemQuantity__c": 0,
213      "vlocity_cmt__IsOverride__c": false,
214      "vlocity_cmt__ParentProductId__c": "01t41000000sYaSAAU",
215      "vlocity_cmt__ChildLineNumber__c": "1",
216      "vlocity_cmt__SeqNumber__c": 1.00,
217      "vlocity_cmt__CollapseHierarchy__c": false,
218      "vlocity_cmt__IsRootProductChildItem__c": true,
219      "vlocity_cmt__ParentProductId__r": {
220         "attributes": {
221            "type": "Product2",
222            "url": "/services/data/v38.0/sobjects/Product2/01t41000000sYaSAAU"
223         },
224         "Id": "01t41000000sYaSAAU",
225         "Name": "GC 2"
226      }
227   },
228   "productHierarchyPath":"01t41000000sYaSAAU",
229   "name": "GC 2",
230   "isVirtualItem": false,
231   "itemType": "lineItem",
232   "PricebookEntryId": {
233      "value": "01u41000001QPtsAAG",
234      "messages": [],
235      "label": "Price Book Entry ID",
236      "hidden": false,
237      "fieldName": "PricebookEntryId",
238      "editable": false,
239      "dataType": "REFERENCE",
240      "actions": {}
241   },
242   "Quantity": {
243      "value": 1.00,
244      "messages": [],
245      "label": "Quantity",
246      "hidden": false,
247      "fieldName": "Quantity",
248      "editable": true,
249      "dataType": "DOUBLE",
250      "actions": {}
251   },
252   "vlocity_cmt__OneTimeTotal__c": {
253      "value": 1.00,
254      "messages": [],
255      "label": "One Time Total",
256      "hidden": false,
257      "fieldName": "vlocity_cmt__OneTimeTotal__c",
258      "editable": false,
259      "dataType": "CURRENCY",
260      "actions": {}
261   },
262   "vlocity_cmt__RecurringTotal__c": {
263      "value": 0.00,
264      "messages": [],
265      "label": "Recurring Total",
266      "hidden": false,
267      "fieldName": "vlocity_cmt__RecurringTotal__c",
268      "editable": false,
269      "dataType": "CURRENCY",
270      "actions": {}
271   },
272   "vlocity_cmt__ProvisioningStatus__c": {
273      "value": "New",
274      "messages": [],
275      "label": "Provisioning Status",
276      "hidden": false,
277      "fieldName": "vlocity_cmt__ProvisioningStatus__c",
278      "editable": false,
279      "dataType": "STRING",
280      "actions": {}
281   },
282   "vlocity_cmt__BillingAccountId__c": "00141000007uyWYAAY",
283   "vlocity_cmt__ServiceAccountId__c": "00141000007uyWYAAY",
284   "vlocity_cmt__ProductHierarchyPath__c": {
285      "value": "01t41000000sYaSAAU",
286      "messages": [],
287      "label": "Product Hierarchy Path",
288      "hidden": false,
289      "fieldName": "vlocity_cmt__ProductHierarchyPath__c",
290      "editable": true,
291      "dataType": "STRING",
292      "actions": {}
293   },
294   "vlocity_cmt__LineNumber__c": {
295      "value": "0001",
296      "messages": [],
297      "label": "LineNumber",
298      "hidden": true,
299      "fieldName": "vlocity_cmt__LineNumber__c",
300      "editable": true,
301      "dataType": "STRING",
302      "actions": {}
303   },
304   "vlocity_cmt__RootItemId__c": {
305      "value": "80241000000HalcAAC",
306      "messages": [],
307      "label": "RootItemId",
308      "hidden": true,
309      "fieldName": "vlocity_cmt__RootItemId__c",
310      "editable": true,
311      "dataType": "STRING",
312      "actions": {}
313   },
314   "ListPrice": {
315      "value": 1.00,
316      "messages": [],
317      "label": "List Price",
318      "hidden": false,
319      "fieldName": "ListPrice",
320      "editable": false,
321      "dataType": "CURRENCY",
322      "actions": {}
323   },
324   "vlocity_cmt__OneTimeCharge__c": {
325      "value": 1.00,
326      "messages": [],
327      "label": "One Time Charge",
328      "hidden": false,
329      "fieldName": "vlocity_cmt__OneTimeCharge__c",
330      "editable": false,
331      "dataType": "CURRENCY",
332      "actions": {}
333   },
334   "vlocity_cmt__OneTimeCalculatedPrice__c": {
335      "value": 1.00,
336      "messages": [],
337      "label": "One Time Calculated Price",
338      "hidden": false,
339      "fieldName": "vlocity_cmt__OneTimeCalculatedPrice__c",
340      "editable": true,
341      "dataType": "CURRENCY",
342      "actions": {}
343   },
344   "vlocity_cmt__OneTimeManualDiscount__c": {
345      "value": 0.00,
346      "messages": [],
347      "label": "One Time Manual Discount",
348      "hidden": false,
349      "fieldName": "vlocity_cmt__OneTimeManualDiscount__c",
350      "editable": true,
351      "dataType": "PERCENT",
352      "actions": {}
353   },
354   "vlocity_cmt__RecurringCharge__c": {
355      "value": 0.00,
356      "messages": [],
357      "label": "Recurring Charge",
358      "hidden": false,
359      "fieldName": "vlocity_cmt__RecurringCharge__c",
360      "editable": false,
361      "dataType": "CURRENCY",
362      "actions": {}
363   },
364   "vlocity_cmt__RecurringCalculatedPrice__c": {
365      "value": 0.00,
366      "messages": [],
367      "label": "Recurring Calculated Price",
368      "hidden": false,
369      "fieldName": "vlocity_cmt__RecurringCalculatedPrice__c",
370      "editable": true,
371      "dataType": "CURRENCY",
372      "actions": {}
373   },
374   "vlocity_cmt__RecurringManualDiscount__c": {
375      "value": 0.00,
376      "messages": [],
377      "label": "Recurring Manual Discount",
378      "hidden": false,
379      "fieldName": "vlocity_cmt__RecurringManualDiscount__c",
380      "editable": true,
381      "dataType": "PERCENT",
382      "actions": {}
383   },
384   "PricebookEntry": {
385      "attributes": {
386         "type": "PricebookEntry",
387         "url": "/services/data/v38.0/sobjects/PricebookEntry/01u41000001QPtsAAG"
388      },
389      "Id": "01u41000001QPtsAAG",
390      "Product2Id": "01t41000000sYaSAAU",
391      "Pricebook2Id": "01s41000005dPYQAA2",
392      "Product2": {
393         "attributes": {
394            "type": "Product2",
395            "url": "/services/data/v38.0/sobjects/Product2/01t41000000sYaSAAU"
396         },
397         "Id": "01t41000000sYaSAAU",
398         "Name": "GC 2",
399         "vlocity_cmt__Type__c": "None",
400         "vlocity_cmt__IsConfigurable__c": false
401      }
402   },
403   "vlocity_cmt__ServiceAccountId__r": {
404      "attributes": {
405         "type": "Account",
406         "url": "/services/data/v38.0/sobjects/Account/00141000007uyWYAAY"
407      },
408      "Id": "00141000007uyWYAAY",
409      "Name": "Telco test"
410   },
411   "vlocity_cmt__BillingAccountId__r": {
412      "attributes": {
413         "type": "Account",
414         "url": "/services/data/v38.0/sobjects/Account/00141000007uyWYAAY"
415      },
416      "Id": "00141000007uyWYAAY",
417      "Name": "Telco test"
418   },
419   "vlocity_cmt__InCartQuantityMap__c": {
420      "value": null,
421      "messages": [],
422      "label": "InCartQuantityMap",
423      "hidden": false,
424      "fieldName": "vlocity_cmt__InCartQuantityMap__c",
425      "editable": true,
426      "dataType": "TEXTAREA",
427      "actions": {}
428   },
429   "vlocity_cmt__JSONAttribute__c": {
430      "value": null,
431      "messages": [],
432      "label": "JSONAttribute",
433      "hidden": false,
434      "fieldName": "vlocity_cmt__JSONAttribute__c",
435      "editable": true,
436      "dataType": "TEXTAREA",
437      "actions": {}
438   },
439   "vlocity_cmt__ParentItemId__c": {
440      "value": null,
441      "messages": [],
442      "label": "ParentItemId",
443      "hidden": true,
444      "fieldName": "vlocity_cmt__ParentItemId__c",
445      "editable": true,
446      "dataType": "STRING",
447      "actions": {}
448   },
449   "vlocity_cmt__RecurringDiscountPrice__c": {
450      "value": null,
451      "messages": [],
452      "label": "Recurring Discount Price",
453      "hidden": false,
454      "fieldName": "vlocity_cmt__RecurringDiscountPrice__c",
455      "editable": false,
456      "dataType": "CURRENCY",
457      "actions": {}
458      }
459   }]
460}

See Also

Configure OmniScript for Guided Selling

Enabling Trim Mode

Option 1: Per-Request (Recommended for Controlled Adoption)

Enable Trim Mode for specific API calls using a query parameter: /services/apexrest/vlocity_cmt/v2/cpq/carts/{cartId}/items?gciTrimMode=true /services/apexrest/vlocity_cmt/v2/cpq/carts/{cartId}/items?gciTrimMode=true&fields=UnitPrice,vlocity_cmt\_\_OneTimeCost\_\_c

Use this approach for:

Targeted integrations
Specific UI components
Testing and gradual rollout

Option 2: Org-Wide Configuration

Enable Trim Mode globally via CPQ configuration:

Set gciTrimMode = true in CPQ Configuration Setup. This applies to all GetCartItems API calls across the organization.
Configure field set:
- Product2.Name
- UnitPrice
- TotalPrice
- Description All responses include default fields, field set fields, and additional fields via fields parameter (if provided).

Trim Mode removes fields from the API response. Any code, UI, or integration that depends on those fields will break unless the fields are explicitly requested.
Out-of-the-box CPQ UI components and standard integrations expect the complete set of response fields. Enabling GCITrimMode at the org level can cause these components and integrations to fail unless all required fields are explicitly included using the fields request parameter or the GCITrimFieldsToInclude field set.

Important

Precedence Rules

API Parameter	Config Setting	Result
TRUE	any	Trim ON
FALSE	any	Trim OFF
not provided	TRUE	Trim ON
not provided	false / unset	Trim OFF

The API parameter always takes precedence. Use gciTrimMode = false to override org-wide settings per request.

Default Fields (Always Included)

These 22 fields are always present when trim mode is on, without needing to request them:

Id, RootItemId, ParentItemId, AssetReferenceId, LineNumber, Product2Id, PricebookEntryId, OrderId, QuoteId, OpportunityId, Quantity, Status, Action, IsRootItem, ProductHierarchyPath, ProductHierarchyGroupKeyPath, BillingAccountId, ServiceAccountId, InCartQuantityMap, CpqMessageData, CpqCardinalityMessage, CpqPricingMessage

Usage Examples

Minimal Cart (Mobile Optimization)

/services/apexrest/vlocity_cmt/v2/cpq/carts/{cartId}/items?gciTrimMode=true&fields=Product2.Name,TotalPrice

Returns a lightweight payload (~24 fields vs 150+).

Cost Analysis Dashboard

/services/apexrest/vlocity_cmt/v2/cpq/carts/{cartId}/items?gciTrimMode=true&fields=UnitPrice,vlocity_cmt__OneTimeCost__c,vlocity_cmt__RecurringCost__c,vlocity_cmt__OneTimeMargin__c

Override Org-Wide Trim Mode

/services/apexrest/vlocity_cmt/v2/cpq/carts/{cartId}/items?gciTrimMode=false

Returns full response regardless of org settings.