# 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.

```nolang
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 `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

```nolang
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 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

```nolang
APIItemsCartsCpqV2
```

## Apex Remote Service

```nolang
CpqAppHandler
```

## Apex Remote Input Map

```nolang
{
 "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](https://developer.salesforce.com/docs/industries/cme/references/cpq?meta=Summary).

:::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)](https://help.salesforce.com/s/articleView?id=sf.admin_supported_date_time_format.htm\&type=5). 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](https://help.salesforce.com/s/articleView?id=ind.comms_configuring_cart_item_refresh_levels.htm).
:::

```nolang
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.
:::

```nolang
{
   "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

```nolang
{
  "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": {} }
    }
  }
}
```