---
schema_version: "1"
id: 0550151fb8ea3354fbfdb3ca3ccbca0e2832fc309f07195cf8b93fb4f8b58ed4
title: Add Items to Cart
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/industries/cme/guides/standard_cart/std_comms-add-items-to-cart.md
canonical_url: https://developer.salesforce.com/docs/industries/cme/guide/std_comms-add-items-to-cart.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: f99f35264e1673eb61e84e4de291ffcfdde0c49b8604574a41c39762a8415b13
products:
  - Communications, Media, Energy and Utilities APIs (Managed Package)
  - Industries Developer Documentation
---
# Add Items to Cart

The `postCartsItems` API allows clients to add one or more products to an existing cart. This is a core operation in any CPQ (Configure, Price, Quote) process. The API enforces business rules such as product eligibility, quantity constraints, and cart state validation, ensuring that only valid items are added. It can trigger pricing, validation, and promotion logic as needed. Robust error handling ensures atomicity—either all items are added successfully, or none are—while clear error messages guide users in case of issues. The API is designed for extensibility, supporting guest users.

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


## Apex Remote Service

```nolang
CpqAppHandler
```


## Remote Method

```nolang
postCartsItems
```

## REST Handler

```nolang
APIItemsCartsCpqV2
```


## REST Method

```nolang
createCartItems
```

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


## Resource Information

- **Resource URL:** `/services/apexrest/{namespace}/v2/cpq/carts/{cart_ID}/items`
- **HTTP Method:** POST
- **Content-Type:** application/json
- **Response Format:** JSON

**note:** Starting in the Winter'27 release, you can pass `UnitPrice` and `ListPrice` in `fieldsToUpdate`. To keep caller-supplied price values, set `price` to `false`. When `price` is `true` (the default), the pricing engine runs after `fieldsToUpdate` is applied and can overwrite price fields from pricebook entries and pricing plan rules. Use `price: false` for contract pricing, zero-price items, or any case where the caller owns the price.

**note:** Each object in the `items` array creates a distinct cart line item, even when `itemId` is the same pricebook entry. Classic Cart APIs collapse duplicate pricebook entry IDs in one call into a single line item. To add quantity on one line, pass a single item with `quantity`. Date fields in `fieldsToUpdate` must use ISO format (`yyyy-MM-dd`). Standard Cart APIs do not parse locale-based values such as `dd/mm/yyyy`.

## Example REST Request

### Root Add

```http
POST /v2/cpq/carts/{cart_ID}/items
Content-Type: application/json

{
  "validate": true,
  "items": [
    {
      "itemId": "01uxx00000099gxAAA"
    }
  ],
  "cartId": "801xx000003H4WlAAK",
  "price": true,
  "quantity": 3
}
```

### Root Add with caller-supplied price

```http
POST /v2/cpq/carts/{cart_ID}/items
Content-Type: application/json

{
  "validate": true,
  "items": [
    {
      "itemId": "01uxx00000099gxAAA",
      "fieldsToUpdate": {
        "UnitPrice": 0,
        "ListPrice": 0
      }
    }
  ],
  "cartId": "801xx000003H4WlAAK",
  "price": false
}
```

### Child Add

```http
POST /v2/cpq/carts/{cart_ID}/items
Content-Type: application/json

{
  "validate": true,
  "items": [
    {
      "parentId": "802xx000001ni7fAAA",
      "parentHierarchyPath": "01txx0000006qMaAAI",
      "itemId": "01uxx00000099iZAAQ",
      "fieldsToUpdate": {"vlocity_cmt__AttributeSelectedValues__c": null},
      "parentRecord": {
        "records": [
          {
            "vlocity_cmt__RootItemId__c": { "value": "7769bef4-0a0f-4dd5-be09-a989cad663d7" },
            "vlocity_cmt__AssetReferenceId__c": { "value": "7769bef4-0a0f-4dd5-be09-a989cad663d7" },
            "Id": { "value": "802xx000001ni7fAAA" }
          }
        ]
      }
    }
  ],
  "cartId": "801xx000003H4WlAAK",
  "price": true
}
```

### Child Add Under Virtual Parent

```http
POST /v2/cpq/carts/{cart_ID}/items
Content-Type: application/json

{
  "validate": true,
  "items": [
    {
      "parentId": "802xx000001ni7fAAA",
      "itemId": "01uxx00000099kBAAQ",
      "parentRecord": {
        "records": [
          {
            "isVirtualItem": true,
            "parentLineItemId": "802xx000001ni7fAAA",
            "productHierarchyPath": "01txx0000006qMaAAI<01txx0000006tKSAAY"
          }
        ]
      }
    }
  ],
  "cartId": "801xx000003H4WlAAK",
  "price": true
}
```

## Example REST Response

### Root Bundle Add Response

```nolang
{
  "totalSize": 1,
  "messages": [
    {
      "code": "150",
      "severity": "INFO",
      "message": "Successfully added."
    }
  ],
  "actions": {
    "itempricesupdated": {}
  },
  "records": [
    {
      "messages": [],
      "actions": {},
      "isVirtualItem": false,
      "maxQuantity": 99999,
      "ProductCode": "CODE-77706",
      "hasChildren": true,
      "IsActive": true,
      "defaultQuantity": 1,
      "productGroups": {
        "totalSize": 1,
        "messages": [],
        "records": [ {} ]
      },
      "childProducts": {
        "totalSize": 1,
        "messages": [],
        "records": [ {} ]
      }
    }
  ]
}
```

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