Point of Sale Cart Validation SPI allows the POS app to send a cart to a merchant’s external system for validation before order placement. The SPI also reserves inventory, ensuring that items are held for the customer until the order is confirmed. Triggered early in the order flow, this can help merchants manage stock and prevent fraud.
For details on this SPI, see Cart Validation SPI in the Point of Sale reference documentation.
For a comprehensive list of Point of Sale APIs and SPIs, see Point of Sale API, SPI, and Webhook Overview.
Note
In CMS, go to Integrations | Custom Connectors.
Click Create.
For Connector Type, select SPI.
For Endpoint Name, select CART_VALIDATION.
For API Endpoint, specify the external endpoint.
For Integration Type, select HTTP_POST.
Specify any required JSON headers. For example, {"Content-Type":"application/json"}. See Point of Sale API, SPI, and Webhook Overview for examples.
Configure the rest of the fields as needed.
Save your changes.
This section covers optional configurations that can help with inventory tracking, tax calculation, and delivery flexibility. While not required for basic functionality, configuring these settings can unlock advanced features like store-level inventory visibility, SPI-based tax handling, and support for complex fulfillment scenarios.
Configure an inventory. See Inventory Configuration in Salesforce Help.
Select SPI as the Provider.
Enable Track Store Inventory in the same Inventory Configuration.
Configure a tax engine. See Integrate Tax Engines in Salesforce Help.
Select SPI as the Tax Engine.
Configure the Tax Calculation SPI.
Enable these Omnichannel settings.
Enable Order Delivery Grouping
Allow Multiple Shipments Per Cart/Order
Allow Multiple Delivery and Pickup Dates Per Order
Allow Multiple Shipping Addresses Per Order
Configure the Delivery Group SPI.
The Cart Validation SPI is triggered just before an order is placed, validating the cart’s contents. It can also manage inventory, such as making reservations. There are two phases during the order placement process: phase 1 and phase 2.
Once a tender type is selected, the app makes the phase 1 call to Point of Sale backend services. During this phase, the POS app invokes the Cart Validation SPI. Because phase 1 occurs before payment is fully processed, inventory reservation also takes place at this stage. The SPI is called only once, even in multi-tender or remote Pay By Link scenarios. Regardless of the number or type of tenders, only one phase 1 call is made.
In this example, if a product’s quantity exceeds 4, a validation failure occurs, displaying an error that the product is out of inventory. For quantities below 4, the validation completes successfully and does not block the checkout flow. The quantity of 4 is just an example, and merchants can customize the validation rules, including the thresholds and error messages, according to their needs.
POST/merchant/spi/sample/endpoint/sa/cartValidation
The request includes all cart items and their associated details. The cartItemList contains information for each product in the cart. Key product identifiers such as productId and variantGroupId are paired with attributes like name, size, color, and quantity. Pricing fields include base price, discounts, subtotal, and total. Each item also includes fulfillment data, such as fulfillmentType, fulfillmentSubType, and delivery or pickup time slots. Tax information is provided at both item and unit levels, with support for VAT, exemptions, and detailed tax rate metadata. The request also accounts for price adjustments, including promotional discounts and manager-approved overrides.
Additionally, each item supports metadata such as sales associate attribution, return eligibility, required deposits, serial numbers, product condition, and optional notes or return reasons. These details ensure all validations—pricing, taxes, fulfillment, and returnability—are covered before proceeding to checkout.
In the Delivery Group SPI, merchants can pass custom product attributes as part of the request. These attributes are defined in the CMS under Store Management | Store Settings | Product, by setting the Merchant-specific product attributes to be provided in SPI request (spiCustomProductAttributes). Merchants can enter a comma-separated list of case-insensitive fields from the product collection. For example, variantGroupId, salePrice, manufacturer, and brand. After configuration, these attributes are included in the Delivery Group SPI response.
Note that these custom attributes must be real fields in the product schema and configured at the store level. The overall request schema includes cartId, editOrderId, cartItemList, and deliveryGroupList.
1{
2 "cartId": "string",
3 "editOrderId": "string",
4 "cartItemList": [
5 {
6 "productId": "string",
7 "variantGroupId": "string",
8 "name": "string",
9 "price": 0,
10 "quantity": 0,
11 "orderItemId": "It can have values like 1, 2, 3, etc... which represents line item number within the order.",
12 "imageURL": "string",
13 "subTotal": 0,
14 "discount": 0,
15 "total": 0,
16 "size": "39-42 or M or 38 etc...",
17 "color": "Light Grey or Black etc...",
18 "itemStatus": "COMPLETED",
19 "gtin": "string",
20 "fulfillmentType": "IN_STORE",
21 "fulfillmentSubType": "DEFAULT",
22 "salesAssociateAttributionList": [
23 {
24 "storeAssociateId": "string",
25 "contributionPercentage": 0,
26 "attributionNote": "string",
27 "firstName": "string",
28 "lastName": "string"
29 }
30 ],
31 "epc": "string",
32 "masterProductId": "string",
33 "subProducts": [
34 "string"
35 ],
36 "productClass": "string",
37 "serialNumber": "string",
38 "productCondition": "NEW",
39 "reasons": [
40 {
41 "reasonCodeType": "TRANSACTION_DISCOUNT",
42 "reasonCode": "string",
43 "reasonText": "string"
44 }
45 ],
46 "dateTimeSlot": {
47 "slotId": "1234",
48 "slotDate": 0,
49 "selectedTimeSlot": "09:00 - 12:00",
50 "dateTimeSlotType": "Delivery"
51 },
52 "priceCorrection": {
53 "originalPrice": 0,
54 "approvingManagerId": "string"
55 },
56 "deliveryGroupId": "string",
57 "formAttributes": [
58 [
59 {
60 "key": "color",
61 "value": "red"
62 }
63 ]
64 ],
65 "pickupDetailId": "string",
66 "productTax": {
67 "totalTax": 0,
68 "taxExemption": 0,
69 "taxRateList": [
70 {
71 "countryCode": "US",
72 "state": "string",
73 "postalCode": "string",
74 "taxType": "CLASS",
75 "chargeType": "TAX",
76 "nonRefundable": false,
77 "taxRate": 7.25,
78 "taxClass": "Tax Class for Shoes and Clothing - PS0001",
79 "taxCode": "string",
80 "taxAmount": 7.25,
81 "perUnitTaxAmount": 1.25,
82 "taxName": "string",
83 "displayTaxName": "string",
84 "corporateTaxId": "HST-74252RT0001",
85 "printTaxName": "string",
86 "externalTaxId": "string",
87 "isExempt": false,
88 "taxDescription": "string",
89 "jurisdiction": "string",
90 "registrationNumber": "string"
91 }
92 ],
93 "vatRateList": [
94 {
95 "countryCode": "US",
96 "state": "string",
97 "postalCode": "string",
98 "taxType": "CLASS",
99 "chargeType": "TAX",
100 "nonRefundable": false,
101 "taxRate": 7.25,
102 "taxClass": "Tax Class for Shoes and Clothing - PS0001",
103 "taxCode": "string",
104 "taxAmount": 7.25,
105 "perUnitTaxAmount": 1.25,
106 "taxName": "string",
107 "displayTaxName": "string",
108 "corporateTaxId": "HST-74252RT0001",
109 "printTaxName": "string",
110 "externalTaxId": "string",
111 "isExempt": false,
112 "taxDescription": "string",
113 "jurisdiction": "string",
114 "registrationNumber": "string"
115 }
116 ],
117 "valueAddedTax": 0,
118 "taxableAmount": 0
119 },
120 "priceAdjustmentList": [
121 {
122 "description": "string",
123 "adjustment": "string",
124 "id": "string",
125 "price": 0,
126 "priceAdjustmentType": "PRICE_OVERRIDE",
127 "promoCode": "string",
128 "auto": true,
129 "discountValue": 0,
130 "discountType": "AMOUNT"
131 }
132 ],
133 "returnsEligibility": "ELIGIBLE_FOR_RETURNS",
134 "returnsEligibilityText": "string",
135 "pickupStoreId": "string",
136 "fulfillmentStoreId": "string",
137 "totalAdditionalCharge": 0,
138 "tlogCustomProductAttributes": "string",
139 "externalId": "string",
140 "productBundleId": "string",
141 "noteList": [
142 {
143 "cartId": "string",
144 "noteId": "string",
145 "noteText": "string",
146 "transactionId": "string"
147 }
148 ],
149 "registryId": "string",
150 "requiredDeposit": 0,
151 "paidDeposit": 0
152 }
153 ],
154 "deliveryGroupList": [
155 {
156 "deliveryGroupId": "string",
157 "fulfillmentType": "IN_STORE",
158 "fulfillmentSubType": "DEFAULT",
159 "shippingMethod": {
160 "shippingMethodId": "001",
161 "name": "Standard Shipping",
162 "description": "string",
163 "carrier": "UPS",
164 "serviceLevel": "3-5 Days",
165 "price": 0,
166 "priceAfterShippingDiscount": 0,
167 "sortOrder": 0,
168 "taxRates": [
169 {
170 "countryCode": "US",
171 "state": "string",
172 "postalCode": "string",
173 "taxType": "CLASS",
174 "chargeType": "TAX",
175 "nonRefundable": false,
176 "taxRate": 7.25,
177 "taxClass": "Tax Class for Shoes and Clothing - PS0001",
178 "taxCode": "string",
179 "taxAmount": 7.25,
180 "perUnitTaxAmount": 1.25,
181 "taxName": "string",
182 "displayTaxName": "string",
183 "corporateTaxId": "HST-74252RT0001",
184 "printTaxName": "string",
185 "externalTaxId": "string",
186 "isExempt": false,
187 "taxDescription": "string",
188 "jurisdiction": "string",
189 "registrationNumber": "string"
190 }
191 ],
192 "vatRates": [
193 {
194 "countryCode": "US",
195 "state": "string",
196 "postalCode": "string",
197 "taxType": "CLASS",
198 "chargeType": "TAX",
199 "nonRefundable": false,
200 "taxRate": 7.25,
201 "taxClass": "Tax Class for Shoes and Clothing - PS0001",
202 "taxCode": "string",
203 "taxAmount": 7.25,
204 "perUnitTaxAmount": 1.25,
205 "taxName": "string",
206 "displayTaxName": "string",
207 "corporateTaxId": "HST-74252RT0001",
208 "printTaxName": "string",
209 "externalTaxId": "string",
210 "isExempt": false,
211 "taxDescription": "string",
212 "jurisdiction": "string",
213 "registrationNumber": "string"
214 }
215 ],
216 "shippingTax": 0,
217 "shippingValueAddedTax": 0,
218 "taxExemption": 0,
219 "deliveryDate": 0,
220 "deliveryTimeSlot": "09:00 - 12:00"
221 },
222 "shippingAddress": {
223 "salutation": "string",
224 "firstName": "string",
225 "lastName": "string",
226 "addressLine1": "string",
227 "addressLine2": "string",
228 "city": "string",
229 "state": "string",
230 "postalCode": "string",
231 "countryCode": "string",
232 "phone": "string",
233 "storeId": "string",
234 "addressType": "string",
235 "emailAddress": "string",
236 "country": "string"
237 },
238 "dateTimeSlot": {
239 "slotId": "1234",
240 "slotDate": 0,
241 "selectedTimeSlot": "09:00 - 12:00",
242 "dateTimeSlotType": "Delivery"
243 },
244 "fulfillmentAddress": {
245 "salutation": "string",
246 "firstName": "string",
247 "lastName": "string",
248 "addressLine1": "string",
249 "addressLine2": "string",
250 "city": "string",
251 "state": "string",
252 "postalCode": "string",
253 "countryCode": "string",
254 "phone": "string",
255 "storeId": "string",
256 "addressType": "string",
257 "emailAddress": "string",
258 "country": "string"
259 }
260 }
261 ]
262}The response includes an error code and error message if there’s a validation issue. The schema follows a standard response format, including fields such as errorMessage, errorCode, and error.
1{
2 "errorMessage": "Invalid request. Please check the request and try again.",
3 "errorCode": "INTERNAL_ERROR",
4 "error": true
5}If the cart validation fails, any reserved inventory is released. Merchants must configure the Inventory Service SPI to make sure that all reserved inventory is properly reverted. For more information, see Retail Cloud API, SPI, and Webhook Overview.
j