Order preprocessing service

The order preprocessing service is an inbound Web service responsible for validating an external order (for example, an order that has been transferred to an external order management system) against contracts in HCL Commerce, and for calculating its prices, discounts, shipping charges, taxes and so forth using settings in HCL Commerce. This inbound Web service is typically called by an external system in integrated solutions where the external system is responsible for order processing but uses HCL Commerce for contract validation, pricing, discount calculation, shipping charge calculation, tax calculation etc.

When to use this interface

You should use the order preprocessing service interface when working with new projects or development tasks.

If you are working on an existing project or development task, it might use the Order preprocessing interface instead.

Typical use cases

  • An order was captured by HCL Commerce and transferred to an external order management system for processing and fulfillment. The order was already validated and priced by HCL Commerce before the transfer, but is modified post-transfer by customer request and needs to be revalidated and repriced.
  • An order is captured by a channel not managed by HCL Commerce but needs HCL Commerce for contract validation, pricing, discount calculation, shipping charge calculation, tax calculation etc.

Endpoint URL and operation

The default endpoint URL of this inbound Web service is https://hostname:8000/webapp/wcs/services/OrderServices. The operation of this inbound Web service is ProcessOrder, with the ProcessOrder BOD as request and the AcknowledgeOrder BOD as response.

Request

Requests to this inbound Web service are in the form of ProcessOrder BODs. They will be mapped to the SalesOrderPreprocess command and should contain the following information:

XPath*TypeMaps to the following command parameterDescription Required
DataArea/Process/ActionCriteria/

ActionExpression/@actionCode

string actionCode The action code. Must be " Preprocess".Y
DataArea/Order/OrderHeader

/OrderIdentifier/OrderID

long orderId HCL Commerce ID of the order, if applicable.N
DataArea/Order/OrderHeader

/OrderIdentifier/

ExternalOrderID

string externalOrderId External ID of the order. Can be any string.N
DataArea/Order/OrderHeader

/OrderIdentifier/StoreID

int storeId HCL Commerce ID of the store under which the order should be processed.Y
DataArea/Order/OrderHeader/OrderReferences/

CustomerIdentifier/UniqueID

long customerId HCL Commerce user ID of the customer who placed the order.Y
DataArea/Order/OrderHeader/OrderPaymentInfo

/PromotionCode[i]

string promotionCode_i Promotion codes that should be applied to the order. N
DataArea/Order/OrderItem[j]/OrderItemIdentifier/OrderItemID long orderItemId_j HCL Commerce ID of the j-th order item, if applicable. N
DataArea/Order/OrderItem[j]/OrderItemIdentifier/ExternalOrderItemID string field2_j External ID of the j-th order item. For correlating order items in the request and response BODs.N
DataArea/Order/OrderItem[j]/ProductIdentifier/CatalogEntryID long catEntryId_j HCL Commerce catalog entry ID of the product associated with the j-th order item. Required if the order item is new and the SKU of the product is not specified.N
DataArea/Order/OrderItem[j]

/ProductIdentifier/SKU

string partNumber_j SKU of the product associated with the j-th order item. Required if the order item is new and the HCL Commerce catalog entry ID of the product is not specified.N
DataArea/Order/OrderItem[j]/Quantity double quantity_j Quantity value of the j-th order item. Required if the order item is new.N
DataArea/Order/OrderItem[j]

/Quantity/@uom

string UOM_j Unit of measure of the quantity value, for example, "C62" for unitless. See quantity units.N
DataArea/Order/OrderItem[j]/OrderItemCharges/UnitPrice/Price decimal price_j Unit price of the product associated with the j-th order item. Will be calculated using settings in HCL Commerce if not specified. N
DataArea/Order/OrderItem[j]/OrderItemCharges/

UnitPrice/Price/@currency

string currency_j Currency of the unit price. Required if unit price of the product is specified.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingAddress

/AddressLine[1]

string address1_j Line 1 of the shipping address of the j-th order item.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingAddress

/AddressLine[2]

string address2_j Line 2 of the shipping address of the j-th order item.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingAddress

/AddressLine[3]

string address3_j Line 3 of the shipping address of the j-th order item.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/City

string city_j City field of the shipping address of the j-th order item.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingAddress

/StateOrProvinceName

string state_j State/province field of the shipping address of the j-th order item.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/Country

string country_j Country field of the shipping address of the j-th order item.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/PostalCode

string zipCode_j ZIP code/postal code field of the shipping address of the j-th order item.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingModeID int shipModeId_j HCL Commerce ID of the shipping mode associated with the j-th order item. Defaults to the default shipping mode of the store if not specified.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingChargePolicyID

long shipChargTypeId_j HCL Commerce ID of the shipping charge policy associated with the j-th order item, if applicable.N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingCarrierAccountNumber

string shipCarrAccntNum_j Shipping carrier account number of the shipping mode, if applicable. N
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingChargeAdjustmentPercentage

double adjustmentPercentageValue

_j

Adjustment percentage on the shipping charge, if applicable. N

* Namespace prefixes ignored for simplicity.

Examples

Response

Responses of this inbound Web service are in the form of AcknowledgeOrder BODs. They will contain the following information:

XPath*Type Description
DataArea/Order/OrderHeader/OrderIdentifier/OrderID longHCL Commerce ID of the order, if applicable.
DataArea/Order/OrderHeader/OrderIdentifier/ExternalOrderID stringExternal ID of the order if specified in the request.
DataArea/Order/OrderHeader/OrderIdentifier/StoreID intHCL Commerce store ID of the store under which the order was processed.
DataArea/Order/OrderHeader/OrderReferences

/BuyerOrganizationIdentifier/UniqueID

longHCL Commerce organization ID of the buyer organization.
DataArea/Order/OrderHeader/OrderReferences

/BuyerOrganizationIdentifier/DistinguishedName

stringDN of the buyer organization.
DataArea/Order/OrderHeader/OrderReferences/CustomerIdentifier/UniqueID longHCL Commerce user ID of the customer who placed the order.
DataArea/Order/OrderHeader/OrderReferences

/CustomerIdentifier/DistinguishedName

stringDN of the customer who placed the order.
DataArea/Order/OrderHeader/OrderCharges/TotalProductPrice decimalTotal price of the order before adjustments, shipping charge and taxes.
DataArea/Order/OrderHeader/OrderCharges/TotalProductPrice/@currency stringCurrency of the total product price.
DataArea/Order/OrderHeader/OrderCharges/TotalAdjustment decimalTotal adjustment of the order.
DataArea/Order/OrderHeader/OrderCharges/TotalAdjustment/@currency stringCurrency of the total adjustment.
DataArea/Order/OrderHeader/OrderCharges/TotalShippingCharge decimalTotal shipping charge of the order.
DataArea/Order/OrderHeader/OrderCharges/TotalShippingCharge/@currency stringCurrency of the total shipping charge.
DataArea/Order/OrderHeader/OrderCharges/TotalSalesTax decimalTotal sales tax of the order.
DataArea/Order/OrderHeader/OrderCharges/TotalSalesTax/@currency stringCurrency of the total sales tax.
DataArea/Order/OrderHeader/OrderCharges/TotalShippingTax decimalTotal shipping tax of the order.
DataArea/Order/OrderHeader/OrderCharges/TotalShippingTax/@currency stringCurrency of the total shipping tax.
DataArea/Order/OrderHeader/OrderPaymentInfo/PromotionCode[i] stringPromotion codes that were applied to the order.
DataArea/Order/OrderItem[j]/OrderItemIdentifier/OrderItemID longHCL Commerce ID of the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemIdentifier/ExternalOrderItemID stringExternal ID of the j-th order item if specified in the request.
DataArea/Order/OrderItem[j]/ProductIdentifier/CatalogEntryID longHCL Commerce catalog entry ID of the product associated with the j-th order item.
DataArea/Order/OrderItem[j]/ProductIdentifier/SKU stringSKU of the product associated with the j-th order item.
DataArea/Order/OrderItem[j]/Quantity doubleQuantity value of the j-th order item.
DataArea/Order/OrderItem[j]/Quantity/@uom stringUnit of measure of the quantity value, for example, "C62" for unitless. See quantity units.
DataArea/Order/OrderItem[j]/OrderItemCharges/UnitPrice/Price decimalUnit price of the product associated with the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemCharges

/UnitPrice/Price/@currency

stringCurrency of the unit price.
DataArea/Order/OrderItem[j]/OrderItemCharges/UnitPrice/Quantity doubleQuantity value representing a single unit in the unit price.
DataArea/Order/OrderItem[j]/OrderItemCharges

/UnitPrice/Quantity/@uom

stringUnit of measure of the quantity value.
DataArea/Order/OrderItem[j]/OrderItemCharges/PriceOverride booleanTrue if unit price of the j-th order item is not calculated using settings in HCL Commerce, false otherwise.
DataArea/Order/OrderItem[j]/OrderItemCharges/FreeGift booleanTrue if the j-th order item is a free gift, false otherwise.
DataArea/Order/OrderItem[j]/OrderItemCharges/OrderItemPrice decimalTotal price of the j-th order item before adjustments, shipping charge and taxes.
DataArea/Order/OrderItem[j]/OrderItemCharges

/OrderItemPrice/@currency

stringCurrency of the order item price.
DataArea/Order/OrderItem[j]/OrderItemCharges/Adjustment[k]/Type StringAdjustment type of the k-th adjustment to the j-th order item, for example, "Coupon", "Discount", "Surcharge".
DataArea/Order/OrderItem[j]/OrderItemCharges/Adjustment[k]/Code StringAdjustment code of the k-th adjustment to the j-th order item. Corresponds to the internal name of the underlying coupon code, promotion, surcharge code etc. in HCL Commerce.
DataArea/Order/OrderItem[j]/OrderItemCharges

/Adjustment[k]/Description

StringExternal description of the k-th adjustment to the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemCharges/Adjustment[k]

/Description/@languageID

intLanguage of the description.
DataArea/Order/OrderItem[j]/OrderItemCharges/Adjustment[k]/Amount decimalAdjustment amount of the k-th adjustment to the j-th order item. Positive for a charge, negative for a discount.
DataArea/Order/OrderItem[j]/OrderItemCharges/Adjustment[k]

/Amount/@currency

stringCurrency of the adjustment amount.
DataArea/Order/OrderItem[j]/OrderItemCharges

/Adjustment[k]/DisplayLevel

stringDisplay level of the k-th adjustment to the j-th order item. "Order" for an order level adjustment, "OrderItem" for an order item level adjustment.
DataArea/Order/OrderItem[j]/OrderItemCharges/ShippingCharge decimalTotal shipping charge of the order.
DataArea/Order/OrderItem[j]/OrderItemCharges/ShippingCharge/@currency stringCurrency of the total shipping charge.
DataArea/Order/OrderItem[j]/OrderItemCharges/SalesTax decimalTotal sales tax of the order.
DataArea/Order/OrderItem[j]/OrderItemCharges/SalesTax/@currency stringCurrency of the total sales tax.
DataArea/Order/OrderItem[j]/OrderItemCharges/ShippingTax decimalTotal shipping tax of the order.
DataArea/Order/OrderItem[j]/OrderItemCharges/ShippingTax/@currency stringCurrency of the total shipping tax.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/AddressLine[1]

stringLine 1 of the shipping address of the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/AddressLine[2]

stringLine 2 of the shipping address of the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/AddressLine[3]

stringLine 3 of the shipping address of the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/City

stringCity field of the shipping address of the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/StateOrProvinceName

stringState/province field of the shipping address of the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/Country

stringCountry field of the shipping address of the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingAddress/PostalCode

stringZIP code/postal code field of the shipping address of the j-th order item.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingModeID intHCL Commerce ID of the shipping mode associated with the j-th order item. Defaults to the default shipping mode of the store if not specified.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingChargePolicyID

longHCL Commerce ID of the shipping charge policy associated with the j-th order item, if applicable.
DataArea/Order/OrderItem[j]/OrderItemShippingInfo

/ShippingCarrierAccountNumber

stringShipping carrier account number of the shipping mode, if applicable.

* Namespace prefixes ignored for simplicity.

Examples

Exceptions

All exceptions will be returned in the form of AcknowledgeOrder BODs with a ResponseCriteria element under the Acknowledge verb. They will contain the following information:

XPath*TypeDescription
DataArea/Acknowledge/ResponseCriteria/ChangeStatus/Code stringThe correlation identifier. Can be used to uniquely identify an exception in the server logs.
DataArea/Acknowledge/ResponseCriteria

/ChangeStatus/ReasonCode

stringThe reason code, which is either a HCL Commerce system error code if available, or the EC message key plus an optional secondary error code if the HCL Commerce system error code is unavailable (usually in the case of application exceptions).
DataArea/Acknowledge/ResponseCriteria/ChangeStatus/Reason stringThe exception message.

* Namespace prefixes ignored for simplicity.

Examples

Note: The releaseID and versionID attributes should be blank when calling the service and ignore the attributes returned in response BOD.