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.
POST /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
parentRecordnode in the input request. -
In the
parentRecordnode, specify theproductHierarchyPathfield. -
If the immediate parent of the child item that you're adding is a virtual parent, then also include these fields:
-
The
Idfield in theparentRecordnode. Ensure that it's thePricebookEntryIdof the immediate virtual parent. -
The
parentIdfield in theitemsnode. Ensure that it's thelineItemIdof the immediate real parent.
-
Remote Method
postCartsItems
note: 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 <!-- broken link-->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.
REST Handler
APIItemsCartsCpqV2
Apex Remote Service
CpqAppHandler
Apex Remote Input Map
{
"methodName": "postCartsItems",
"cartId": "801360000008eNU",
"items": [
{
{
"itemId": "01t36000000pfcKAAQ",
"parentId": "01t36000000pfcKAAZ",
"fieldsToUpdate": {
"quantity": 6,
"vlocity_cmt__RecurringManualDiscount__c": 10,
"SampleDateTime__c": "2024/10/10 11:46"
}
}
}
]
}
"itemId" = "pricebookEntryId",
"parentId" = "OrderItem.Id"
Package
Communication (vlocity_cmt)
API Parameters and Response Format
For API parameter names and descriptions, see Cart-Based API Swagger Reference.
important: 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).
Resource Information
| Response Format | JSON |
|---|---|
| Resource URL | /services/apexrest/{namespace}/v2/cpq/carts/{cart_ID}/items |
Example Request
note: For more information about levelBasedApproach, see Configuring Cart Item Refresh Levels.
POST
{
"items": [
{
"itemId": "01uf4000000gmRTAAY",
"parentId": "802f4000000PZ1VAAW",
"parentRecord": {
"records": [
{
"messages": [],
"displaySequence": -1,
"Id": {
"messages": [],
"label": "Order Product ID",
"hidden": false,
"fieldName": "Id",
"editable": false,
"dataType": "ID",
"value": "802f4000000PZ1VAAW"
},
"UnitPrice": {
"messages": [],
"label": "Unit Price",
"hidden": true,
"fieldName": "UnitPrice",
"editable": false,
"dataType": "CURRENCY",
"value": 358.95
},
"productId": "01tf4000000Kd0uAAC",
"defaultQuantity": 1,
"minQuantity": 0,
"maxQuantity": 99999,
"groupMinQuantity": 0,
"groupMaxQuantity": 99999,
"sequenceNumber": 1,
"productHierarchyPath": "01tf4000000Kd0uAAC",
"itemType": "lineItem",
"childProducts": {
"records": [
{
"Name": {
"label": "Product Name",
"value": "PRODUCT-77151"
},
"UnitPrice": {
"label": "List Price",
"value": 0
},
"vlocity_cmt__RecurringPrice__c": {
"label": "Recurring Price",
"value": 0
},
"Product2Id": {
"label": "Product ID",
"value": "01tf4000000Kd0zAAC"
},
"Pricebook2Id": {
"label": "Price Book ID",
"value": "01sf4000003LYn3AAG"
},
"Id": {
"label": "Price Book Entry ID",
"value": "01uf4000000gmRTAAY"
},
"defaultQuantity": 0,
"productId": "01tf4000000Kd0zAAC",
"Product2": {
"Name": "PRODUCT-77151",
"RecordTypeId": "012f40000004zEOAAY",
"vlocity_cmt__IsConfigurable__c": false,
"vlocity_cmt__SubType__c": "None",
"vlocity_cmt__Type__c": "None"
},
"messages": [],
"actions": {
"addtocart": {
"rest": {
"params": {
"price": true,
"validate": true,
"includeAttachment": false,
"pagesize": 20,
"items": [
{
"parentId": "802f4000000PZ1VAAW",
"quantity": 0,
"itemId": "01uf4000000gmRTAAY"
}
],
"cartId": "801f4000000ChZjAAK"
},
"method": "POST",
"link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/801f4000000ChZjAAK/items"
},
"remote": {
"params": {
"price": true,
"validate": true,
"includeAttachment": false,
"pagesize": 20,
"items": [
{
"parentId": "802f4000000PZ1VAAW",
"quantity": 0,
"itemId": "01uf4000000gmRTAAY"
}
],
"cartId": "801f4000000ChZjAAK",
"methodName": "postCartsItems"
}
},
"client": {
"params": {
"pagesize": 0,
}
}
}
}
}
]
},
"vlocity_cmt__RecurringPrice__c": 527.96,
"name": "PRODUCT-39982",
"provisioningStatus": "New",
"Product2Id": "01tf4000000Kd0uAAC",
"PricebookEntryId": {
"messages": [],
"label": "Price Book Entry ID",
"hidden": false,
"fieldName": "PricebookEntryId",
"editable": false,
"dataType": "REFERENCE",
"value": "01uf4000000gmRJAAY"
},
"Quantity": {
"messages": [],
"label": "Quantity",
"hidden": false,
"fieldName": "Quantity",
"editable": true,
"dataType": "DOUBLE",
"value": 1
},
"vlocity_cmt__OneTimeTotal__c": {
"messages": [],
"label": "One Time Total",
"hidden": false,
"fieldName": "vlocity_cmt__OneTimeTotal__c",
"editable": false,
"dataType": "CURRENCY",
"value": 358.95
},
"vlocity_cmt__RecurringTotal__c": {
"messages": [],
"label": "Recurring Total",
"hidden": false,
"fieldName": "vlocity_cmt__RecurringTotal__c",
"editable": false,
"dataType": "CURRENCY",
"value": 527.96
},
"vlocity_cmt__ProvisioningStatus__c": {
"messages": [],
"label": "Provisioning Status",
"hidden": true,
"fieldName": "vlocity_cmt__ProvisioningStatus__c",
"editable": false,
"dataType": "STRING",
"value": "New"
},
"vlocity_cmt__ProductHierarchyPath__c": {
"messages": [],
"label": "Product Hierarchy Path",
"hidden": true,
"fieldName": "vlocity_cmt__ProductHierarchyPath__c",
"editable": false,
"dataType": "STRING",
"value": "01tf4000000Kd0uAAC"
},
"vlocity_cmt__LineNumber__c": {
"messages": [],
"label": "LineNumber",
"hidden": true,
"fieldName": "vlocity_cmt__LineNumber__c",
"editable": false,
"dataType": "STRING",
"value": "0001"
},
"vlocity_cmt__RootItemId__c": {
"messages": [],
"label": "RootItemId",
"hidden": true,
"fieldName": "vlocity_cmt__RootItemId__c",
"editable": false,
"dataType": "STRING",
"value": "802f4000000PZ1VAAW"
},
"ListPrice": {
"messages": [],
"label": "List Price",
"hidden": true,
"fieldName": "ListPrice",
"editable": false,
"dataType": "CURRENCY",
"value": 358.95
},
"vlocity_cmt__OneTimeCharge__c": {
"messages": [],
"label": "One Time Charge",
"hidden": true,
"fieldName": "vlocity_cmt__OneTimeCharge__c",
"editable": false,
"dataType": "CURRENCY",
"value": 358.95
},
"vlocity_cmt__RecurringCharge__c": {
"messages": [],
"label": "Recurring Charge",
"hidden": true,
"fieldName": "vlocity_cmt__RecurringCharge__c",
"editable": false,
"dataType": "CURRENCY",
"value": 527.96
},
"vlocity_cmt__RecurringManualDiscount__c": {
"messages": [],
"label": "Recurring Manual Discount",
"hidden": false,
"fieldName": "vlocity_cmt__RecurringManualDiscount__c",
"editable": true,
"dataType": "PERCENT",
"value": 0
},
"vlocity_cmt__OneTimeManualDiscount__c": {
"messages": [],
"label": "One Time Manual Discount",
"hidden": false,
"fieldName": "vlocity_cmt__OneTimeManualDiscount__c",
"editable": true,
"dataType": "PERCENT",
"value": 0
},
"vlocity_cmt__ParentItemId__c": {
"messages": [],
"label": "ParentItemId",
"hidden": true,
"fieldName": "vlocity_cmt__ParentItemId__c",
"editable": false,
"dataType": "STRING"
},
"PricebookEntry": {
"Product2Id": "01tf4000000Kd0uAAC",
"Pricebook2Id": "01sf4000003LYn3AAG",
"Id": "01uf4000000gmRJAAY",
"Product2": {
"Name": "PRODUCT-39982",
"Id": "01tf4000000Kd0uAAC",
"vlocity_cmt__Type__c": "None",
"vlocity_cmt__IsConfigurable__c": "false"
}
},
"Product2": {
"Name": "PRODUCT-39982",
"RecordTypeId": "012f40000004zEOAAY",
"vlocity_cmt__IsConfigurable__c": false,
"vlocity_cmt__SubType__c": "None",
"vlocity_cmt__Type__c": "None"
},
"vlocity_cmt__ItemName__c": {
"messages": [],
"label": "Item Name",
"hidden": false,
"fieldName": "vlocity_cmt__ItemName__c",
"editable": true,
"dataType": "STRING"
},
"actions": {
"addtocart": {
"rest": {
"params": {
"price": true,
"validate": true,
"includeAttachment": false,
"pagesize": 20,
"items": [
{
"parentId": "802f4000000PZ1VAAW",
"quantity": 1,
"itemId": "01uf4000000gmRJAAY"
}
],
"cartId": "801f4000000ChZjAAK"
},
"method": "POST",
"link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/801f4000000ChZjAAK/items"
},
"remote": {
"params": {
"price": true,
"validate": true,
"includeAttachment": false,
"pagesize": 20,
"items": [
{
"parentId": "802f4000000PZ1VAAW",
"quantity": 1,
"itemId": "01uf4000000gmRJAAY"
}
],
"cartId": "801f4000000ChZjAAK",
"methodName": "postCartsItems"
}
},
"client": {
"params": {
"pagesize": 0,
}
}
},
"cloneitem": {
"rest": {
"params": {
"pagesize": 0,
"items": [
{
"quantity": 0,
"itemId": "802f4000000PZ1VAAW"
}
],
"cartId": "801f4000000ChZjAAK"
},
"method": "POST",
"link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/801f4000000ChZjAAK/items/clone"
},
"remote": {
"params": {
"pagesize": 0,
"items": [
{
"quantity": 0,
"itemId": "802f4000000PZ1VAAW"
}
],
"cartId": "801f4000000ChZjAAK",
"methodName": "cloneItems"
}
},
"client": {
"params": {
"pagesize": 0,
}
}
}
},
"isVirtualItem": false
}
]
}
}
],
"pagesize": 0,
"levelBasedApproach": false
}
To use this API to pass child line items, you must also specify the Price Book Entry ID.
{
"items":[
{
"parentRecord":{
"records":[
{
"Id":{
"label":"Price Book Entry ID",
"value":"01uf4000000gmRJAAY"
},
"productHierarchyPath":""
}
]
},
"parentId":" ",
"itemId":""
}
]
}
Example Result
note: An entire result can be thousands of lines long. This example has been truncated.
{
"totalSize": 1,
"messages": [{
"severity": "INFO",
"messageId": null,
"message": "Successfully added.",
"code": "150",
"actions": {}
}],
"records": [{
"messages": [],
"actions": {
"addtocart": {
"rest": {
"params": {
"includeAttachment": false,
"pagesize": 20,
"lastRecordId": null,
"query": null,
"items": [{
"parentId": "80241000000HalXAAS",
"quantity": 1,
"itemId": "01u41000001QPs5AAG"
}]
},
"method": "POST",
"link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items"
},
"remote": {
"params": {
"price": true,
"validate": true,
"includeAttachment": false,
"pagesize": 20,
"lastRecordId": null,
"query": null,
"items": [{
"parentId": "80241000000HalXAAS",
"quantity": 1,
"itemId": "01u41000001QPs5AAG"
}],
"cartId": "80141000000Cg8HAAS",
"methodName": "postCartsItems"
}
},
"client": {
"params": {}
}
},
"updateitems": {
"rest": {
"params": {
"fields": null,
"price": true,
"validate": true,
"filters": null,
"includeAttachment": false,
"pagesize": 20,
"lastRecordId": null,
"query": null,
"items": [{
"itemId": "80241000000HalXAAS"
}]
},
"method": "PUT",
"link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items"
},
"remote": {
"params": {
"fields": null,
"price": true,
"validate": true,
"filters": null,
"includeAttachment": false,
"pagesize": 20,
"lastRecordId": null,
"query": null,
"items": [{
"itemId": "80241000000HalXAAS"
}],
"cartId": "80141000000Cg8HAAS",
"methodName": "putCartsItems"
}
},
"client": {
"params": {}
}
},
"deleteitem": {
"rest": {
"params": {},
"method": "DELETE",
"link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items/80241000000HalXAAS?pagesize=20&includeAttachment=false&validate=true&price=true"
},
"remote": {
"params": {
"price": true,
"validate": true,
"filters": null,
"includeAttachment": false,
"pagesize": 20,
"lastRecordId": null,
"query": null,
"id": "80241000000HalXAAS",
"cartId": "80141000000Cg8HAAS",
"methodName": "deleteCartsItems"
}
},
"client": {
"params": {}
}
},
"cloneitem": {
"rest": {
"params": {
"items": [{
"itemId": "80241000000HalXAAS"
}]
},
"method": "POST",
"link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items/clone"
},
"remote": {
"params": {
"id": "80241000000HalXAAS",
"cartId": "80141000000Cg8HAAS",
"methodName": "cloneItems"
}
},
"client": {
"params": {}
}
},
"modifyattributes": {
"rest": {
"params": {
"fields": null,
"items": [{
"itemId": "80241000000HalXAAS"
}]
},
"method": "PUT",
"link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/80141000000Cg8HAAS/items/80241000000HalXAAS/itemattributes"
},
"remote": {
"params": {
"fields": null,
"items": [{
"itemId": "80241000000HalXAAS"
}],
"itemId": "80241000000HalXAAS",
"cartId": "80141000000Cg8HAAS",
"methodName": "putItemAttributes"
}
},
"client": {
"params": {}
}
}
},
"displaySequence": -1,
"Id": {
"value": "80241000000HalXAAS",
"messages": [],
"label": "Order Product ID",
"hidden": false,
"fieldName": "Id",
"editable": false,
"dataType": "ID",
"actions": {}
},
"Pricebook2Id": "01s41000005dPYQAA2",
"Product2Id": "01t41000000sYZVAA2",
"UnitPrice": {
"value": 2.00,
"messages": [],
"label": "Unit Price",
"hidden": false,
"fieldName": "UnitPrice",
"editable": true,
"dataType": "CURRENCY",
"actions": {}
},
"Name": "Parent 1",
"IsActive": true,
"Product2": {
"attributes": {
"type": "Product2",
"url": "/services/data/v38.0/sobjects/Product2/01t41000000sYZVAA2"
},
"Id": "01t41000000sYZVAA2",
"Name": "Parent 1",
"vlocity_cmt__IsConfigurable__c": false,
"vlocity_cmt__Type__c": "None",
"vlocity_cmt__SubType__c": "None",
"RecordTypeId": "012410000006OWUAA2",
"vlocity_cmt__JSONAttribute__c": null
},
"productId": "01t41000000sYZVAA2",
"defaultQuantity": 1.0,
"minQuantity": 0.0,
"maxQuantity": 99999.0,
"groupMinQuantity": 0,
"groupMaxQuantity": 99999,
"sequenceNumber": 1.00,
"productChildItemDefinition": {
"attributes": {
"type": "vlocity_cmt__ProductChildItem__c",
"url": "/services/data/v38.0/sobjects/vlocity_cmt__ProductChildItem__c/a2541000000G0A1AAK"
},
"Id": "a2541000000G0A1AAK",
"Name": "Root PCI",
"vlocity_cmt__IsVirtualItem__c": false,
"vlocity_cmt__Quantity__c": 1,
"vlocity_cmt__MaxQuantity__c": 99999,
"vlocity_cmt__MinQuantity__c": 0,
"vlocity_cmt__MaximumChildItemQuantity__c": 99999,
"vlocity_cmt__MinimumChildItemQuantity__c": 0,
"vlocity_cmt__IsOverride__c": false,
"vlocity_cmt__ParentProductId__c": "01t41000000sYZVAA2",
"vlocity_cmt__ChildLineNumber__c": "1",
"vlocity_cmt__SeqNumber__c": 1.00,
"vlocity_cmt__CollapseHierarchy__c": false,
"vlocity_cmt__IsRootProductChildItem__c": true,
"vlocity_cmt__ParentProductId__r": {
"attributes": {
"type": "Product2",
"url": "/services/data/v38.0/sobjects/Product2/01t41000000sYZVAA2"
},
"Id": "01t41000000sYZVAA2",
"Name": "Parent 1"
}
},
"productHierarchyPath": "01t41000000sYZVAA2",
"name": "Parent 1",
"isVirtualItem": false,
"itemType": "lineItem",
"PricebookEntryId": {
"value": "01u41000001QPs5AAG",
"messages": [],
"label": "Price Book Entry ID",
"hidden": false,
"fieldName": "PricebookEntryId",
"editable": false,
"dataType": "REFERENCE",
"actions": {}
},
...
Add with noResponseNeeded=true
{
"totalSize": 0,
"messages": [
{
"code": "150",
"severity": "INFO",
"message": "Successfully added."
}
],
"actions": {
"itempricesupdated": {
"rest": {
"params": {},
"method": "GET",
"link": "/services/apexrest/vlocity_cmt/v2/cpq/carts/801xx000003H4WlAAK/price?price=false&cartId=801xx000003H4WlAAK"
},
"remote": { "params": {} },
"client": { "params": {} }
}
}
}