--- schema_version: "1" id: 977918f4e1bd2d263ee1080289ef002ff18c5f4ccf9df89c6ddb32c1c1f41915 title: Cart Validation SPI collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/cart-validation-spi.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/cart-validation-spi source_site: developer.salesforce.com content_type: documentation content_hash: ebb139a9c2446bba2a6704e86aa32a11c7ee27b79d840b7380afd83d048c13f6 products: - Point of Sale for Developers - Salesforce APIs --- Cart Validation SPI # Cart Validation SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cart-validation-spi/cart-validation-spi-oas-public.yaml) Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are configured in CMS so that the POS can use them during all cart operations. **Version:** 2.3.4 ## Tags ### Cart Validation SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cart-validation-spi/cart-validation-spi-oas-public.yaml) Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are configured in CMS so that the POS can use them during all cart operations. ## Operations ### POST Validate cart. `POST /merchant/spi/sample/endpoint/sa/cartValidation` Operation ID: `cartValidation`. Tags: Cart Validation SPI. This SPI endpoint enables POS to send a cart to the merchant's external system for validation. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details: 1. Under **API Config**: * **API Key:** `CART_VALIDATION` * **API Endpoint:** Provide the external endpoint to get the cart validation, for example: [https://sample/external/endpoint/cartValidation](https://sample/external/endpoint/cartValidation) 2. Under **JSON Config**: * **Integration Type:** `HTTP_POST` * **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"Content-Type":"application/json"}. #### Request body Media type: `*/*`. Schema: `ExternalCart`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `CartValidationResponse`. ## Schemas ### ExternalCart * `cartId` (_string_, required) Unique identifier for the cart. * `editOrderId` (_string_) Order ID for the order being edited. * `cartItemList` (_array of ExternalProduct_, required) All the items from the cart. Each item has a link to its delivery group via deliveryGroupId. * `deliveryGroupList` (_array of ExternalDeliveryGroup_) All delivery groups corresponding to the delivery items from the cart. * `billingAddress` (_ExternalAddress_) * `profile` (_ExternalCustomerProfile_) * `pickUpDetailList` (_array of ExternalPickUpDetail_, nullable) Pickup details. ### CartValidationResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `displayMessage` (_string_, nullable) This message is for informational purposes only and is intended for display to users or associates. Please ensure it is not used in error scenarios. For error messages, use 'errorMessage' instead, as this will trigger the creation of a new cart and the execution of tax and other SPI calls. * `error` (_boolean_) ### ExternalProduct Products. * `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU. * `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID. * `name` (_string_, required) Name of the item. * `price` (_number_, required) Price of the item. * `quantity` (_integer (int32)_, required) Item's Quantity. * `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string. Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`. * `imageURL` (_string_, required) Image URL of the item. * `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT. * `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied. * `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts. * `size` (_string_, required) Item's size. Example: `39-42 or M or 38 etc...`. * `color` (_string_, required) Item's color. Example: `Light Grey or Black etc...`. * `itemStatus` (_string_, required) Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below. The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item. To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility | | --- | --- | --- | --- | --- | | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. | | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. | | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. | | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. | | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. | | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. | | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. | Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`. * `gtin` (_string_, required) Item's GTIN. * `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item). Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`. * `fulfillmentSubType` (_string_, required) 1. DEFAULT: Either item will be available from the current store for  cash & carry or for delivery to shipping address from a warehouse.   Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item 2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items. 3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store. 4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse. 5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store. \---------------------------------------------------------------------------------- | Fulfillment Type | Fulfillment SubType | Item | | --- | --- | --- | | IN\_STORE | DEFAULT | Cash & carry | | ONLINE | DEFAULT | Ship to home from warehouse | | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out | | IN\_STORE | PICKUP\_LATER | Pickup from current store | | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store | | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup | | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) | | IN\_STORE | PICKUP\_NEARBY | Pickup from another store | . Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`. * `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate. * `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID. * `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart. Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items. * `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items. * `productClass` (_string_, required) Product class of the item. * `serialNumber` (_string_) Serial number of the item (if applicable). * `productCondition` (_string_) Product condition. Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`. * `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item. * `dateTimeSlot` (_DateTimeSlot_) * `priceCorrection` (_ExternalProductPriceCorrection_) * `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items. Maximum length: 32. * `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product. * `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product. Points to the corresponding pickup details from pickupDetailList in the transaction. Maximum length: 128. * `productTax` (_ExternalProductTax_) * `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item. It includes all the price adjustments like transaction discount, price override etc... Mandatory if any type of price adjustments is applied. * `returnsEligibility` (_string_, nullable) Returns eligibility of the item. Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`. * `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'. Maximum length: 128. * `pickupStoreId` (_string_, nullable) Pickup store ID. * `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID. * `totalAdditionalCharge` (_number_, nullable) Total additional charges. * `tlogCustomProductAttributes` (_string_, nullable) Custom attributes. * `externalId` (_string_, nullable) External ID of the product. Maximum length: 128. * `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle. * `noteList` (_array of ExternalNote_, nullable) Note associated with the product. * `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product. All these attributes will be available at item level that are configured in Store Setting: spiCustomProductAttributes. _Example_ ``` [ { "key": "color", "value": "red" } ] ``` * `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item. * `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store. * `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store. ### ExternalDeliveryGroup In the event that the transaction comprises any delivery item, a list of delivery groups is required. Each delivery item is associated with a delivery group via a deliveryGroupId link. * `deliveryGroupId` (_string_, required) Delivery group ID. * `fulfillmentType` (_string_, required) Fulfillment type. Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`. * `fulfillmentSubType` (_string_, required) 1. DEFAULT: Either item will be available from the current store for  cash & carry or for delivery to shipping address from a warehouse.   Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item 2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items. 3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store. 4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse. 5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store. \---------------------------------------------------------------------------------- | Fulfillment Type | Fulfillment SubType | Item | | --- | --- | --- | | IN\_STORE | DEFAULT | Cash & carry | | ONLINE | DEFAULT | Ship to home from warehouse | | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out | | IN\_STORE | PICKUP\_LATER | Pickup from current store | | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store | | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup | | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup, i.e., buy online ship to store | | IN\_STORE | PICKUP\_NEARBY | Pickup from another store | . Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`. * `shippingMethod` (_ShippingMethod_, required) * `shippingAddress` (_ExternalAddress_, required) * `dateTimeSlot` (_DateTimeSlot_, required) * `fulfillmentAddress` (_ExternalAddress_) * `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification. Maximum length: 128. ### ExternalAddress Billing address. * `salutation` (_string_, nullable) Salutation. * `firstName` (_string_, required, nullable) Customer first name saved for address. Maximum length: 64. * `lastName` (_string_, nullable) Customer last name saved for address. Maximum length: 64. * `addressLine1` (_string_, required, nullable) Address Line 1. Maximum length: 256. * `addressLine2` (_string_, nullable) Address Line 2. Maximum length: 256. * `city` (_string_, required, nullable) City. Maximum length: 64. * `state` (_string_, required, nullable) State. Maximum length: 32. * `postalCode` (_string_, required, nullable) Postal Code. Maximum length: 16. * `countryCode` (_string_, required, nullable) Country Code. Maximum length: 32. * `phone` (_string_, nullable) Phone. Maximum length: 24. * `storeId` (_string_, nullable) Store ID if it is store address. * `addressType` (_string_, nullable) Address type- Home, Business. * `emailAddress` (_string_, nullable) Customer Email Address. Maximum length: 64. * `country` (_string_, nullable) Country. ### ExternalCustomerProfile Customer profile. It is mandatory for customer logged-in during the transaction. It is optional for guest customer. * `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer. Maximum length: 128. * `alternateCustomerId` (_string_, nullable) Alternate Customer ID. Maximum length: 128. * `email` (_string_, nullable) Customer Email ID. Optional for guest customer. Mandatory for logged-in customer. * `salutation` (_string_, nullable) Salutation. * `firstName` (_string_, nullable) Customer first name Optional for guest customer. Mandatory for logged-in customer. * `secondName` (_string_, nullable) Customer second name. * `lastName` (_string_, nullable) Customer last name Optional for guest customer. Mandatory for logged-in customer. * `suffix` (_string_, nullable) Suffix. * `phoneHome` (_string_, nullable) Phone Home. * `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer. * `phoneBusiness` (_string_, nullable) Phone Business. * `fax` (_string_, nullable) Fax. * `loyaltyId` (_string_, nullable) Loyalty Id of the customer. ### ExternalPickUpDetail Pickup details. * `pickupDetailId` (_string_) * `storeId` (_string_) * `storeAssociateId` (_string_) * `firstName` (_string_) * `lastName` (_string_) * `email` (_string_) * `phone` (_string_) ### ExternalStoreAssociateAttribution Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate. * `storeAssociateId` (_string_, required) ID of the associate that completed the sale transaction. * `contributionPercentage` (_number_, required) Associate's contribution towards sales. * `attributionNote` (_string_) Note related to attribution. * `firstName` (_string_, required) Associate's first name. * `lastName` (_string_, required) Associate's last name. ### Reason Reason for returning the item. * `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT. Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64. * `reasonCode` (_string_, required) Reason code. Maximum length: 64. * `reasonText` (_string_, nullable) Reason text. Maximum length: 256. ### DateTimeSlot Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings. * `slotId` (_string_) Slot ID. Example: `1234`. * `slotDate` (_integer (int64)_, required) Delivery date in epoch. * `selectedTimeSlot` (_string_, required) Time slot. Example: `09:00 - 12:00`. * `dateTimeSlotType` (_string_, nullable) Time slot type. Allowed values: `Delivery`, `Pickup`. Default: `Delivery`. ### ExternalProductPriceCorrection Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price. * `originalPrice` (_number_) Original price of the item. * `approvingManagerId` (_string_) ID of the manager who approved the price correction request. ### ProductFormAttribute Details about a product form attribute. * `key` (_string_) The identifier of the attribute. Example: `color`. * `value` (_string_) The value associated with the key. Example: `blue`. _Example_ ``` [ { "key": "color", "value": "red" } ] ``` ### ExternalProductTax Tax/Vat details. * `totalTax` (_number_, required) Total tax. Required in case of tax countries. * `taxExemption` (_number_, nullable) Tax Exemption. * `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates. * `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates. * `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries. * `taxableAmount` (_number_, required) Taxable amount. ### ExternalPriceAdjustment Price adjustments applied on the item. It includes all the price adjustments like transaction discount, price override etc... Mandatory if any type of price adjustments is applied. * `description` (_string_, required) Price adjustment description. * `adjustment` (_string_, required) Price adjustment. * `id` (_string_) Promotion Id for applied coupon or auto promotion. * `price` (_number_, required) Price adjustment amount. * `priceAdjustmentType` (_string_, required) Price adjustment type. Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`. * `reason` (_Reason_) * `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion. It is used to identify the promotion in external system and is relevant only if it is configured in CMS Applicable only for promotions. * `promoCode` (_string_, nullable) Coupon code corresponding to promotion applied. Not applicable for auto promotions, manual price adjustments like price override & transaction discount. * `auto` (_boolean_, nullable) Applied promotion is auto or not. * `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format. * `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price. Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`. * `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns. Maximum length: 128. ### ExternalNote Notes for the transaction. * `cartId` (_string_) * `noteId` (_string_) * `noteText` (_string_) * `transactionId` (_string_) ### ShippingMethod Available shipping methods corresponding to this delivery group. * `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method. Maximum length: 45. Example: `001`. * `name` (_string_, required) Shipping Method Name. Maximum length: 128. Example: `Standard Shipping`. * `description` (_string_, nullable) Shipping Method Description. Maximum length: 128. * `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL. Maximum length: 32. Example: `UPS`. * `serviceLevel` (_string_, nullable) Service Level Description. E.g. 3-5 Days, 1-Day, Express, Standard, Overnight. Maximum length: 128. Example: `3-5 Days`. * `price` (_number_, required) Shipping cost. * `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only. * `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount. * `sortOrder` (_integer (int32)_) Display Order. Default: `0`. * `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable. * `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable. * `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable. * `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable. * `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class. * `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied. * `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis. * `deliveryTimeSlot` (_string_, required) Expected delivery time slot. Example: `09:00 - 12:00`. * `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount. ### ProductTaxRate VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable. * `countryCode` (_string_, required) Country Code. Maximum length: 2. Example: `US`. * `state` (_string_, nullable) State. Applicable if the tax rate is specific to state. Maximum length: 128. * `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code. Maximum length: 10. * `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT. Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`. * `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE. Allowed values: `TAX`, `FEE`. Default: `TAX`. * `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable. Default: `false`. * `taxRate` (_number (float)_, required) % tax/vat rate. Example: `7.25`. * `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate. Example: `Tax Class for Shoes and Clothing - PS0001`. * `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item. * `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate. Example: `7.25`. * `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate. Example: `1.25`. * `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag. Maximum length: 64. * `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%. * `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number. Example: `HST-74252RT0001`. * `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%. * `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems. * `isExempt` (_boolean_, nullable) Indicates if tax is exempted. Default: `false`. * `taxDescription` (_string_, nullable) Tax Description text. * `jurisdiction` (_string_, nullable) Jurisdiction. Maximum length: 128. * `registrationNumber` (_string_, nullable) Registration Number. Maximum length: 128. * `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns. Maximum length: 128. ### PriceAdjustment Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only. * `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional. Maximum length: 1500. * `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items. Example: `-155.5`. * `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items. Example: `-155.5`. * `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID. * `priceAdjustmentType` (_string_) Price adjustment type. Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`. * `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions. * `fulfillmentType` (_string_) Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`. * `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions. * `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion. It is used to identify the promotion in external system and is relevant only if it is configured in CMS Applicable only for promotions. * `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT. * `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments. * `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format. * `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price. Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`. * `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts. * `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts. * `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns. Maximum length: 128. * `adjustmentAmount` (_number_) * `referenceAdjustmentId` (_string_) * `referenceAdjustmentID` (_string_, write-only) * `adjustmentType` (_string_) Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`. * `reasonText` (_string_) ### ItemLevelCharge Item level breakdown for the shipping cost and shipping discount. * `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group. Example: `It can have values like 1, 2, 3, etc...
which represents line item number within the order or Delivery Group.`. * `itemShippingCharge` (_number_) Item level shipping charge. * `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward. * `discountText` (_string_, nullable) Discount text of an applied promotion. Maximum length: 1500. * `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.