Use CpqCartDocument

The CpqCartDocument is a trimmed and flexible JSON structure that you can use in the CPQ on Core services. You can then use the output JSON to send responses to upper layer APIs such as the Digital Commerce APIs.

Key Capabilities

Cart Field Management: Manage and update cart-level fields.
Line Item Operations: Add, update, or remove items from the cart.
Pricing Operations: Execute and manage pricing calculations.
Attribute Management: Handle product or line item attributes.
Promotion Handling: Apply and manage cart-level and item-level promotions.
External Pricing Integration: Integrate with external systems for pricing data.

Implementation Basics

In Standard Cart APIs, the CpqCartDocument instance is passed through the input map.

1global with sharing class CustomCPQHook implements VlocityOpenInterface {
2    global Boolean invokeMethod(String methodName, Map<String, Object> input,
3                              Map<String, Object> output, Map<String, Object> options) {
4        CpqCartDocument cartDoc = null;
5        try {
6            // Get cart document from input
7            cartDoc = (CpqCartDocument)input.get('cartDocument');
8
9            // Your implementation using the available methods
10
11            return true;
12        } catch(Exception e) {
13            System.debug('Error: ' + e.getMessage());
14            return false;
15        }
16    }
17}

Initialization Methods

1// Method 1: Initialize from JSON string (for tests)
2vlocity_cmt.CpqCartDocument cart = vlocity_cmt.CpqCartDocument.initializeCartFromString(cartJson);
3
4// Method 2: Get from input map (in hooks)
5vlocity_cmt.CpqCartDocument cart = (vlocity_cmt.CpqCartDocument)input.get('cartDocument');

Cart Field Operations

This section provides examples of working with Cart fields, including performing updates on individual fields as well as handling multiple field changes in a single operation.

Single Field Operations

1// Get a single field
2Map<String, Object> output = cart.call('getCartField',
3    new Map<String, Object>{
4        'field' => 'vlocity_cmt__EffectiveOneTimeTotal__c'
5    }
6);
7Decimal total = (Decimal)output.get('result');
8
9// Set a single field
10cartDoc.call('setCartField',
11    new Map<String, Object>{
12        'field' => 'vlocity_cmt__EffectiveOneTimeCostTotal__c',
13        'value' => 100.00
14    }
15);

The setCartField can only update total-related fields associated with Usage Pricing or the Cost and Margin feature fields such as:

vlocity_cmt__EffectiveOneTimeCostTotal__c
vlocity_cmt__EffectiveRecurringCostTotal__c
vlocity_cmt__RecurringMarginTotal__c
vlocity_cmt__EffectiveUsageCostTotal__c
vlocity_cmt__OneTimeMarginTotal__c
vlocity_cmt__OrderMarginTotal__c
vlocity_cmt__UsageMarginTotal__c

Note

Multiple Field Operations

1// Get multiple fields
2Set<String> fields = new Set<String>{
3    'vlocity_cmt__EffectiveOneTimeTotal__c',
4    'vlocity_cmt__EffectiveRecurringTotal__c'
5};
6Map<String, Object> fieldsOutput = cart.call('getCartFields',
7    new Map<String, Object>{
8        'fields' => fields
9    }
10);
11Map<String, Object> fieldValues = (Map<String, Object>)fieldsOutput.get('result');

Line Item Operations

This section provides examples of managing cart line items, from retrieving all items in the cart to getting and setting multiple fields on an individual line item.

Get All Cart Line Items

1// Get all item IDs in the cart
2Map<String, Object> output = cart.call('getItemIds', null);
3Set<String> itemIds = (Set<String>)output.get('result');
4
5// Get all items
6Map<String, Object> itemsOutput = cartDoc.call('getAllItems',
7    new Map<String, Object>{
8        'hierarchyLevel' => -1  // optional: -1 full hierachy
9    }
10);
11 Map<String, vlocity_cmt.CpqCartDocumentItem> allItemsMap = (Map<String, vlocity_cmt.CpqCartDocumentItem>) itemsOutput.get('result');
12
13// Root items
14Map<String, Object> rootItems = cart.call('getAllItems',
15    new Map<String, Object>{
16        'hierarchyLevel' => 1  // Only root items
17    }
18);
19
20// Get specific item from AssetReferenceId
21vlocity_cmt.CpqCartDocumentItem lineItem = allItemsMap.get('36ad500b-b3eb-bdf3-12f7-7703efcfdcab');

Get/Set Single Fields on a Cart Line Item

1// Get single field on a line item
2Map<String, Object> itemField = lineItem.call('getItemField',
3    new Map<String, Object>{
4        'field' => new Set<String>{
5            'vlocity_cmt__OneTimeCharge__c'
6        }
7    }
8);
9
10// Set a single field on a line item
11Map<String, Object> output = lineItem.call('setItemField',
12    new Map<String, Object>{
13        'field' => 'vlocity_cmt__OneTimeCharge__c',
14        'value' => 100.00
15    }
16);

Get/Set Multiple Fields on a Cart Line Item

1// Get multiple fields on a line item
2Map<String, Object> itemOutput = lineItem.call('getItemFields',
3    new Map<String, Object>{
4        'fields' => new Set<String>{
5            'vlocity_cmt__OneTimeCharge__c',
6            'vlocity_cmt__RecurringCharge__c'
7        }
8    }
9);
10
11
12// Set multiple fields on a line item
13Map<String, Object> output = lineItem.call('setItemFields',
14    new Map<String, Object>{
15        'fieldValueMap' => new Map<String, Object>{
16            'vlocity_cmt__OneTimeCharge__c' => 100.00,
17            'vlocity_cmt__RecurringCharge__c' => 50.00,
18            'vlocity_cmt__LineNumber__c' => '0001'
19        }
20    }
21);

Get Child Item

1// Get child item IDs for a line item
2Map<String, Object> output = lineItem.call('getChildItemIds', null);
3Set<String> childItemIds = (Set<String>)output.get('result');
4
5
6// Get child items of a parent
7Map<String, Object> childOutput = cartDoc.call('getChildItems',
8    new Map<String, Object>{
9        'vlocity_cmt__AssetReferenceId__c' => parentItemId
10    }
11);
12Map<String, vlocity_cmt.CpqCartDocumentItem> childItems = (Map<String, vlocity_cmt.CpqCartDocumentItem>)childOutput.get('result');

Promotion Operation

1// Get all active promotion codes in the cart
2Map<String, Object> output = cart.call('getPromoCodes', null);
3Set<String> promoCodes = (Set<String>)output.get('result');

Cart Level Pricing Operations

This section provides examples of cart-level pricing operations, including how to apply or clear externally provided prices and how to retrieve pricing variable maps for further processing.

Set External Price

1// Set external price for items in the cart
2Map<String, Object> priceArgs = new Map<String, Object>{
3    // Item pricing information for multiple items
4    'itemFieldsInfo' => new Map<String, Object>{
5        // First item
6        '58f1a32b-a0f9-4455-9e53-dcd4dd839bb0' => new Map<String, Object>{. //Asset Reference Id for Item
7            'vlocity_cmt__OneTimeCharge__c' => new Map<String, Object>{
8                'value' => 100,
9                'detail' => 'Priced from AttributePricingProcedure',
10                'source' => 'ABP',
11                'code' => 'OT_STD_PRC'
12            },
13            'vlocity_cmt__RecurringCharge__c' => new Map<String, Object>{
14                'value' => 50,
15                'detail' => 'Priced from AttributePricingProcedure',
16                'source' => 'ABP',
17                'code' => 'REC_MNTH_STD_PRC'
18            }
19        },
20        // Second item
21        '57d29a96-59c0-49b9-b4f8-a61f5d51a7ef' => new Map<String, Object>{
22            'vlocity_cmt__OneTimeCharge__c' => new Map<String, Object>{
23                'value' => 70,
24                'detail' => 'Priced from AttributePricingProcedure',
25                'source' => 'ABP',
26                'code' => 'OT_STD_PRC'
27            },
28            'vlocity_cmt__RecurringCharge__c' => new Map<String, Object>{
29                'value' => 80,
30                'detail' => 'Priced from AttributePricingProcedure',
31                'source' => 'ABP',
32                'code' => 'REC_MNTH_STD_PRC'
33            }
34        }
35    },
36    // Time plan policies for the items
37    'timePlanPolicyList' => new List<Map<String, Object>>{
38        new Map<String, Object>{
39            'ID' => '57d29a96-59c0-49b9-b4f8-a61f5d51a7ef',
40            'TimePolicyName' => 'Purchase Date To End Of Plan Duration',
41            'TimePlanName' => '12 Months Time Plan'
42        },
43        new Map<String, Object>{
44            'ID' => '58f1a32b-a0f9-4455-9e53-dcd4dd839bb0',
45            'TimePolicyName' => 'Purchase Date To End Of Plan Duration',
46            'TimePlanName' => '6 Months Time Plan'
47        }
48    }
49};
50
51// Call setExternalPrice
52Map<String, Object> output = cart.call('setExternalPrice', priceArgs);

Clear External Price

1// Clear all external pricing in the cart
2Map<String, Object> output = cart.call('clearExternalPrice', null);

Get Pricing Variable Maps

1// Get pricing variable information
2Map<String, Object> output = cart.call('getPricingVariableMaps', null);
3Map<String, Object> pricingVars = (Map<String, Object>)output.get('result');

This is the Standard Cart equivalent of the classic method used to retrieve the pricing variable map.

1vlocity_cmt.PricingPlanService.getFromPricingContext('PricingVariableDefinitionsMap');

Attribute Operations

This section provides examples of how to work with attributes, including retrieving attribute definitions, updating attribute values, and managing referred attributes within the cart or its line items.

Retrieve Attributes

1// Get all attributes for a line item
2Map<String, Object> categoryToAttrCodeValueMap = (Map<String, Object>) lineItem.call('getItemAttributes', null).get('result');
3
4// Get attributes for a specific category (e.g., 'MLS')
5Map<String, Object> attrCodeValueMap = (Map<String, Object>) categoryToAttrCodeValueMap.get('MLS');
6
7// Get value of specific attribute (e.g., 'CodeMLS')
8Double attributeValue = (Double) attrCodeValueMap.get('CodeMLS');

Update Attribute Values

1// Modify attribute value
2attrCodeValueMap.put('CodeMLS', newValue);
3
4// Update attributes on the line item
5Map<String, Object> output = lineItem.call('setItemAttributes',
6    new Map<String, Object>{
7        'attributeCodeToValueMap' => categoryToAttrCodeValueMap
8    }
9);

Get Referred Attributes

1// Get referred attributes for a line item
2Map<String, Object> output = lineItem.call('GET_ITEM_REFERRED_ATTRIBUTES', null);
3Map<String, Object> referredAttributes = (Map<String, Object>)output.get('result');

The cartDocument object is not accessible in the pre- or post-hooks of cpqAppHandler.
For migrated Standard Cart APIs, custom logic—such as validations or pricing—should rely on cartDocument rather than a list of line-item sObjects.
Because not all APIs have migrated to the Standard Cart framework, custom implementations must accommodate both Classic and Standard Cart flows and switch dynamically based on context.
Setting custom fields to null using setItemFields() causes the update to fail. Use setItemField() instead when assigning a null value.
In Standard Cart APIs, the CpqCartDocument contains only the bundles and line items affected by the current operation. As a result:
- Methods like getItemIds() or getAllItems() return only the impacted items, not the entire cart.
- Products or bundles not affected by the current transaction are excluded from the cart document.
In Standard Cart APIs, cart data remains in-memory as a CpqCartDocument and is not persisted until the pricing step is completed. All cart objects stay in memory throughout the operation, and persistence occurs only after pricing has finished.
During Add/Update/Delete item API calls, not all cart line items are loaded into the cart document—only the item being processed is included. The GetCartsItems API is the only call that returns all line items in the cart document. If access to all cart line items is required during Add/Update/Delete operations, customers must explicitly query and retrieve the necessary records within their custom pricing step.

Important