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.

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

CpqAppHandler

Remote Method

postCartsItems

REST Handler

APIItemsCartsCpqV2

REST Method

createCartItems

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}/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

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

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

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

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

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

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