Get List of Products

The getCartsProducts API provides a flexible and efficient way to retrieve a tailored list of products for a specific cart, based on the cart’s Price List and business context. It supports advanced filtering, pagination, localization, and the inclusion of product attachments.

Key Parameters:

Pagination Controls: pagesize and offsetSize work together to navigate large catalogs efficiently, while lastRecordId enables cursor-based pagination for better performance.
Filtering Options: query, attributes, filters, and category allow for precise product selection based on text search, attribute values, field values, and product categories.
Response Customization: includeIneligible, includeAttachments, includeAttributes, and fields let you control what data is included in the response.
Performance Optimization: maxRecords and eaCacheKey enable efficient caching for faster repeated queries.
Business Rules: eaCheck and filterByPriceListOnly apply eligibility rules and price list restrictions to the returned products.

Caching Enhancement:

Optimized caching is available using maxRecords (max 1000) and eaCacheKey parameters, improving response times for recurring queries.
Both parameters must be present to enable caching.

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.

If a Simple Offer Specification is associated with a Simple Product Specification, the API returns the Min, Max, and Default cardinality from the Simple Product Specification.
This applies only to the response. When adding items to the cart (postCartsItems), the system enforces the stricter cardinality defined in the Simple Offer Specification, even if the response shows different values.
The getCartsProducts API does not support combining filters and query parameters.

Note

Remote Method

1getCartsProducts

REST Handler

1APIProductsCartsCpqV2

Apex Remote Service

1CpqAppHandler

Apex Remote Input Map

1{
2  "methodName": "getCartsProducts",
3  "cartId": "801xx000003HC67",
4  "pagesize": 10,
5  "offsetSize": 0,
6  "filterByPriceListOnly": true,
7  "sortBy": "DESC",
8  "includeIneligible": true,
9  "includeAttachment": false
10}

cartId can be an Order, Opportunity, or Quote ID.

REST Handler

1APIProductsCartsCpqV2

REST Method

1getProducts

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}/products
Response Format: JSON

Example REST Request

1GET /v2/cpq/carts/{cart_ID}/products?query={query}&attributes={attribute_code:value}&lastRecordId={record_ID}&pagesize={n}&includeAttachment={true|false}&category={category}&filters={filters}&includeIneligible={true|false}

Example REST Response

1{
2  "totalSize": 3,
3  "messages": [
4
5  ],
6  "actions": {
7    "nextproducts": {
8      "rest": {
9        "params": {
10
11        },
12        "method": "GET",
13        "link": "/services/apexrest/devops001gs0/v2/cpq/carts/801LT00000kkMXhYAM/products?offsetSize=3&maxRecords=50&includeAttachment=false&cartId=801LT00000kkMXhYAM&pagesize=3&includeIneligible=true"
14      },
15      "remote": {
16        "params": {
17
18        }
19      },
20      "client": {
21        "params": {
22
23        }
24      }
25    }
26  },
27  "records": [
28    {
29      "messages": [
30
31      ],
32      "actions": {
33        "addtocart": {
34          "rest": {
35            "params": {
36              "validate": true,
37              "items": [
38                {
39                  "itemId": "01uLT0000073akTYAQ"
40                }
41              ],
42              "pagesize": 3,
43              "cartId": "801LT00000kkMXhYAM",
44              "hierarchy": -1,
45              "query": null,
46              "price": true,
47              "includeAttachment": false,
48              "lastRecordId": null
49            },
50            "method": "POST",
51            "link": "/services/apexrest/devops001gs0/v2/cpq/carts/801LT00000kkMXhYAM/items"
52          },
53          "remote": {
54            "params": {
55
56            }
57          },
58          "client": {
59            "params": {
60
61            }
62          }
63        },
64        "getproductbyid": {
65          "rest": {
66            "params": {
67
68            },
69            "method": "GET",
70            "link": "/services/apexrest/devops001gs0/v2/cpq/carts/801LT00000kkMXhYAM/products?cartId=801LT00000kkMXhYAM&id=01uLT0000073akTYAQ"
71          },
72          "remote": {
73            "params": {
74
75            }
76          },
77          "client": {
78            "params": {
79              "methodName": "getCartsProductsById",
80              "cartId": "801LT00000kkMXhYAM",
81              "id": "01uLT0000073akTYAQ"
82            }
83          }
84        }
85      },
86      "displaySequence": -1,
87      "productCategories": {
88        "messages": [
89
90        ],
91        "totalSize": 0
92      },
93      "Product2": {
94        "devops001gs0__SubType__c": "None",
95        "devops001gs0__Type__c": "None",
96        "devops001gs0__GlobalGroupKey__c": "1ecc268f-35be-7ae2-21cd-727b56a4d39e",
97        "devops001gs0__IsConfigurable__c": false,
98        "Name": "PRODUCT-46223",
99        "Id": "01tLT0000093Pr7YAE",
100        "attributes": {
101          "url": "/services/data/v65.0/sobjects/Product2/01tLT0000093Pr7YAE",
102          "type": "Product2"
103        },
104        "RecordTypeId": "012LT000001fxpRYAQ"
105      },
106      "productChildItemDefinition": {
107        "devops001gs0__ParentProductId__c": "01tLT0000093Pr7YAE",
108        "Name": "Root PCI",
109        "devops001gs0__ParentProductId__r": {
110          "devops001gs0__ProductSpecId__c": null,
111          "Id": "01tLT0000093Pr7YAE",
112          "Name": "PRODUCT-46223",
113          "devops001gs0__GlobalGroupKey__c": "1ecc268f-35be-7ae2-21cd-727b56a4d39e"
114        },
115        "devops001gs0__MinQuantity__c": 0,
116        "devops001gs0__MaxQuantity__c": 99999,
117        "devops001gs0__MinimumChildItemQuantity__c": 0,
118        "devops001gs0__MaximumChildItemQuantity__c": 99999,
119        "devops001gs0__Quantity__c": 1,
120        "devops001gs0__SeqNumber__c": 1,
121        "devops001gs0__ChildLineNumber__c": "1.0",
122        "devops001gs0__IsRootProductChildItem__c": true,
123        "devops001gs0__IsOverride__c": false,
124        "Id": "a41LT0000006TQjYAM",
125        "devops001gs0__CollapseHierarchy__c": false,
126        "devops001gs0__IsVirtualItem__c": false
127      },
128      "devops001gs0__RecurringPrice__c": {
129        "label": "Recurring Price",
130        "value": 277.37
131      },
132      "UnitPrice": {
133        "label": "List Price",
134        "value": 3472.87
135      },
136      "IsActive": {
137        "label": "Active",
138        "value": true
139      },
140      "Name": {
141        "label": "Product Name",
142        "value": "PRODUCT-46223"
143      },
144      "ProductCode": {
145        "label": "Product Code",
146        "value": "CODE-88388"
147      },
148      "Product2Id": {
149        "label": "Product ID",
150        "value": "01tLT0000093Pr7YAE"
151      },
152      "Pricebook2Id": {
153        "label": "Price Book ID",
154        "value": "01sLT000002oxi5YAA"
155      },
156      "Id": {
157        "label": "Price Book Entry ID",
158        "value": "01uLT0000073akTYAQ"
159      },
160      "defaultQuantity": 1,
161      "minQuantity": 0,
162      "maxQuantity": 99999,
163      "groupMinQuantity": 0,
164      "groupMaxQuantity": 99999,
165      "sequenceNumber": 1,
166      "productChildItemId": "a41LT0000006TQjYAM",
167      "productHierarchyPath": "01tLT0000093Pr7YAE",
168      "productId": "01tLT0000093Pr7YAE",
169      "name": "PRODUCT-46223",
170      "isVirtualItem": false,
171      "hasChildren": false,
172      "itemType": "childProduct",
173      "SellingPeriod": "Present",
174      "CurrencyCode": "USD",
175      "category": "Qualified"
176    },
177    {
178      "messages": [
179
180      ],
181      "actions": {
182        "addtocart": {
183          "rest": {
184            "params": {
185              "validate": true,
186              "items": [
187                {
188                  "itemId": "01uLT0000073aHRYAY"
189                }
190              ],
191              "pagesize": 3,
192              "cartId": "801LT00000kkMXhYAM",
193              "hierarchy": -1,
194              "query": null,
195              "price": true,
196              "includeAttachment": false,
197              "lastRecordId": null
198            },
199            "method": "POST",
200            "link": "/services/apexrest/devops001gs0/v2/cpq/carts/801LT00000kkMXhYAM/items"
201          },
202          "remote": {
203            "params": {
204
205            }
206          },
207          "client": {
208            "params": {
209
210            }
211          }
212        },
213        "getproductbyid": {
214          "rest": {
215            "params": {
216
217            },
218            "method": "GET",
219            "link": "/services/apexrest/devops001gs0/v2/cpq/carts/801LT00000kkMXhYAM/products?cartId=801LT00000kkMXhYAM&id=01uLT0000073aHRYAY"
220          },
221          "remote": {
222            "params": {
223
224            }
225          },
226          "client": {
227            "params": {
228              "methodName": "getCartsProductsById",
229              "cartId": "801LT00000kkMXhYAM",
230              "id": "01uLT0000073aHRYAY"
231            }
232          }
233        }
234      },
235      "displaySequence": -1,
236      "productCategories": {
237        "messages": [
238
239        ],
240        "totalSize": 0
241      },
242      "Product2": {
243        "devops001gs0__SubType__c": "None",
244        "devops001gs0__Type__c": "None",
245        "devops001gs0__GlobalGroupKey__c": "7c64c300-0295-585f-1e4e-188048321ca9",
246        "devops001gs0__IsConfigurable__c": false,
247        "Name": "PRODUCT-51821",
248        "Id": "01tLT0000093PazYAE",
249        "attributes": {
250          "url": "/services/data/v65.0/sobjects/Product2/01tLT0000093PazYAE",
251          "type": "Product2"
252        },
253        "RecordTypeId": "012LT000001fxpRYAQ"
254      },
255      "productChildItemDefinition": {
256        "devops001gs0__ParentProductId__c": "01tLT0000093PazYAE",
257        "Name": "Root PCI",
258        "devops001gs0__ParentProductId__r": {
259          "devops001gs0__ProductSpecId__c": null,
260          "Id": "01tLT0000093PazYAE",
261          "Name": "PRODUCT-51821",
262          "devops001gs0__GlobalGroupKey__c": "7c64c300-0295-585f-1e4e-188048321ca9"
263        },
264        "devops001gs0__MinQuantity__c": 0,
265        "devops001gs0__MaxQuantity__c": 99999,
266        "devops001gs0__MinimumChildItemQuantity__c": 0,
267        "devops001gs0__MaximumChildItemQuantity__c": 99999,
268        "devops001gs0__Quantity__c": 1,
269        "devops001gs0__SeqNumber__c": 1,
270        "devops001gs0__ChildLineNumber__c": "1.0",
271        "devops001gs0__IsRootProductChildItem__c": true,
272        "devops001gs0__IsOverride__c": false,
273        "Id": "a41LT0000006TAbYAM",
274        "devops001gs0__CollapseHierarchy__c": false,
275        "devops001gs0__IsVirtualItem__c": false
276      },
277      "devops001gs0__RecurringPrice__c": {
278        "label": "Recurring Price",
279        "value": 879.39
280      },
281      "UnitPrice": {
282        "label": "List Price",
283        "value": 2544.15
284      },
285      "IsActive": {
286        "label": "Active",
287        "value": true
288      },
289      "Name": {
290        "label": "Product Name",
291        "value": "PRODUCT-51821"
292      },
293      "ProductCode": {
294        "label": "Product Code",
295        "value": "CODE-41677"
296      },
297      "Product2Id": {
298        "label": "Product ID",
299        "value": "01tLT0000093PazYAE"
300      },
301      "Pricebook2Id": {
302        "label": "Price Book ID",
303        "value": "01sLT000002oxi5YAA"
304      },
305      "Id": {
306        "label": "Price Book Entry ID",
307        "value": "01uLT0000073aHRYAY"
308      },
309      "defaultQuantity": 1,
310      "minQuantity": 0,
311      "maxQuantity": 99999,
312      "groupMinQuantity": 0,
313      "groupMaxQuantity": 99999,
314      "sequenceNumber": 1,
315      "productChildItemId": "a41LT0000006TAbYAM",
316      "productHierarchyPath": "01tLT0000093PazYAE",
317      "productId": "01tLT0000093PazYAE",
318      "name": "PRODUCT-51821",
319      "isVirtualItem": false,
320      "hasChildren": false,
321      "itemType": "childProduct",
322      "SellingPeriod": "Present",
323      "CurrencyCode": "USD",
324      "category": "Qualified"
325    },
326    {
327      "messages": [
328
329      ],
330      "actions": {
331        "addtocart": {
332          "rest": {
333            "params": {
334              "validate": true,
335              "items": [
336                {
337                  "itemId": "01uLT0000073bNBYAY"
338                }
339              ],
340              "pagesize": 3,
341              "cartId": "801LT00000kkMXhYAM",
342              "hierarchy": -1,
343              "query": null,
344              "price": true,
345              "includeAttachment": false,
346              "lastRecordId": null
347            },
348            "method": "POST",
349            "link": "/services/apexrest/devops001gs0/v2/cpq/carts/801LT00000kkMXhYAM/items"
350          },
351          "remote": {
352            "params": {
353
354            }
355          },
356          "client": {
357            "params": {
358
359            }
360          }
361        },
362        "getproductbyid": {
363          "rest": {
364            "params": {
365
366            },
367            "method": "GET",
368            "link": "/services/apexrest/devops001gs0/v2/cpq/carts/801LT00000kkMXhYAM/products?cartId=801LT00000kkMXhYAM&id=01uLT0000073bNBYAY"
369          },
370          "remote": {
371            "params": {
372
373            }
374          },
375          "client": {
376            "params": {
377              "methodName": "getCartsProductsById",
378              "cartId": "801LT00000kkMXhYAM",
379              "id": "01uLT0000073bNBYAY"
380            }
381          }
382        }
383      },
384      "displaySequence": -1,
385      "productCategories": {
386        "messages": [
387
388        ],
389        "totalSize": 0
390      },
391      "Product2": {
392        "devops001gs0__SubType__c": "None",
393        "devops001gs0__Type__c": "None",
394        "devops001gs0__GlobalGroupKey__c": "59b61bef-b2a6-9a36-83e9-c2ff42b79642",
395        "devops001gs0__IsConfigurable__c": false,
396        "Name": "PRODUCT-52047",
397        "Id": "01tLT0000093QFJYA2",
398        "attributes": {
399          "url": "/services/data/v65.0/sobjects/Product2/01tLT0000093QFJYA2",
400          "type": "Product2"
401        },
402        "RecordTypeId": "012LT000001fxpRYAQ"
403      },
404      "productChildItemDefinition": {
405        "devops001gs0__ParentProductId__c": "01tLT0000093QFJYA2",
406        "Name": "Root PCI",
407        "devops001gs0__ParentProductId__r": {
408          "devops001gs0__ProductSpecId__c": null,
409          "Id": "01tLT0000093QFJYA2",
410          "Name": "PRODUCT-52047",
411          "devops001gs0__GlobalGroupKey__c": "59b61bef-b2a6-9a36-83e9-c2ff42b79642"
412        },
413        "devops001gs0__MinQuantity__c": 0,
414        "devops001gs0__MaxQuantity__c": 99999,
415        "devops001gs0__MinimumChildItemQuantity__c": 0,
416        "devops001gs0__MaximumChildItemQuantity__c": 99999,
417        "devops001gs0__Quantity__c": 1,
418        "devops001gs0__SeqNumber__c": 1,
419        "devops001gs0__ChildLineNumber__c": "1.0",
420        "devops001gs0__IsRootProductChildItem__c": true,
421        "devops001gs0__IsOverride__c": false,
422        "Id": "a41LT0000006TlhYAE",
423        "devops001gs0__CollapseHierarchy__c": false,
424        "devops001gs0__IsVirtualItem__c": false
425      },
426      "devops001gs0__RecurringPrice__c": {
427        "label": "Recurring Price",
428        "value": 148.57
429      },
430      "UnitPrice": {
431        "label": "List Price",
432        "value": 1945.33
433      },
434      "IsActive": {
435        "label": "Active",
436        "value": true
437      },
438      "Name": {
439        "label": "Product Name",
440        "value": "PRODUCT-52047"
441      },
442      "ProductCode": {
443        "label": "Product Code",
444        "value": "CODE-45662"
445      },
446      "Product2Id": {
447        "label": "Product ID",
448        "value": "01tLT0000093QFJYA2"
449      },
450      "Pricebook2Id": {
451        "label": "Price Book ID",
452        "value": "01sLT000002oxi5YAA"
453      },
454      "Id": {
455        "label": "Price Book Entry ID",
456        "value": "01uLT0000073bNBYAY"
457      },
458      "defaultQuantity": 1,
459      "minQuantity": 0,
460      "maxQuantity": 99999,
461      "groupMinQuantity": 0,
462      "groupMaxQuantity": 99999,
463      "sequenceNumber": 1,
464      "productChildItemId": "a41LT0000006TlhYAE",
465      "productHierarchyPath": "01tLT0000093QFJYA2",
466      "productId": "01tLT0000093QFJYA2",
467      "name": "PRODUCT-52047",
468      "isVirtualItem": false,
469      "hasChildren": false,
470      "itemType": "childProduct",
471      "SellingPeriod": "Present",
472      "CurrencyCode": "USD",
473      "category": "Qualified"
474    }
475  ]
476}

Availability and Eligibility Interface

The Availability and Eligibility Interface enhancement transforms the Communications Cloud Standard Get List of Products API into a context-aware product discovery engine. By integrating with AvailabilityInterface and EligibilityInterface, the API can dynamically filter products based on customer location, existing services, account status, and other contextual factors.

Key Benefits

Context-Aware Filtering: Automatically filter products based on customer location, account details, and eligibility criteria
Improved User Experience: Present only relevant, actionable product options to customers and sales agents
Streamlined Sales Process: Reduce time spent on non-viable product configurations
Flexible Implementation: Implement custom business logic for availability and eligibility checks
Backward Compatible: Existing API behavior is preserved when context is not provided

The enhanced Get List of Products API processes requests through the following sequence:

Initial Product Fetch: The API retrieves products from the catalog based on standard query parameters
Availability Filtering (optional): If availability context is provided, the AvailabilityInterface filters products based on location or service availability
Eligibility Filtering (optional): If eligibility context is provided, the EligibilityInterface filters products based on account status, existing services, or business rules
Response: The API returns the final, contextually filtered product list