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* | Type | Maps to the following command parameter | Description | Required |
|---|---|---|---|---|
DataArea/Process/ActionCriteria/ |
string | actionCode | The
action code. Must be " Preprocess". | Y |
DataArea/Order/OrderHeader |
long | orderId | HCL Commerce ID of the order, if applicable. | N |
DataArea/Order/OrderHeader |
string | externalOrderId |
External ID of the order. Can be any string. | N |
DataArea/Order/OrderHeader |
int | storeId | HCL Commerce ID of the store under which the order should be processed. | Y |
DataArea/Order/OrderHeader/OrderReferences/ |
long | customerId | HCL Commerce user ID of the customer who placed the order. | Y |
DataArea/Order/OrderHeader/OrderPaymentInfo |
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] |
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] |
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/ |
string | currency_j | Currency of the unit price. Required if unit price of the product is specified. | N |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingAddress |
string | address1_j | Line
1 of the shipping address of the j-th order item. | N |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingAddress |
string | address2_j | Line
2 of the shipping address of the j-th order item. | N |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingAddress |
string | address3_j | Line
3 of the shipping address of the j-th order item. | N |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | city_j | City
field of the shipping address of the j-th order item. | N |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingAddress |
string | state_j | State/province
field of the shipping address of the j-th order
item. | N |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | country_j | Country
field of the shipping address of the j-th order item. | N |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
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 |
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 |
string | shipCarrAccntNum_j |
Shipping carrier account number of the shipping mode, if applicable. | N |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
double | adjustmentPercentageValue |
Adjustment percentage on the shipping charge, if applicable. | N |
* Namespace prefixes ignored for simplicity.
Examples
- Sample ProcessOrder BOD 1 - validating and pricing an order originating from HCL Commerce
- Sample ProcessOrder BOD 2 - validating and pricing an order not originating from HCL Commerce
- Sample ProcessOrder BOD 3 - validating and pricing an order with price overrides
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 |
long | HCL Commerce ID of the order, if applicable. |
DataArea/Order/OrderHeader/OrderIdentifier/ExternalOrderID |
string | External ID of the order if specified in the request. |
DataArea/Order/OrderHeader/OrderIdentifier/StoreID |
int | HCL Commerce store ID of the store under which the order was processed. |
DataArea/Order/OrderHeader/OrderReferences |
long | HCL Commerce organization ID of the buyer organization. |
DataArea/Order/OrderHeader/OrderReferences |
string | DN of the buyer organization. |
DataArea/Order/OrderHeader/OrderReferences/CustomerIdentifier/UniqueID |
long | HCL Commerce user ID of the customer who placed the order. |
DataArea/Order/OrderHeader/OrderReferences |
string | DN of the customer who placed the order. |
DataArea/Order/OrderHeader/OrderCharges/TotalProductPrice |
decimal | Total price of the order before adjustments, shipping charge and taxes. |
DataArea/Order/OrderHeader/OrderCharges/TotalProductPrice/@currency |
string | Currency of the total product price. |
DataArea/Order/OrderHeader/OrderCharges/TotalAdjustment |
decimal | Total adjustment of the order. |
DataArea/Order/OrderHeader/OrderCharges/TotalAdjustment/@currency |
string | Currency of the total adjustment. |
DataArea/Order/OrderHeader/OrderCharges/TotalShippingCharge |
decimal | Total shipping charge of the order. |
DataArea/Order/OrderHeader/OrderCharges/TotalShippingCharge/@currency |
string | Currency of the total shipping charge. |
DataArea/Order/OrderHeader/OrderCharges/TotalSalesTax |
decimal | Total sales tax of the order. |
DataArea/Order/OrderHeader/OrderCharges/TotalSalesTax/@currency |
string | Currency of the total sales tax. |
DataArea/Order/OrderHeader/OrderCharges/TotalShippingTax |
decimal | Total shipping tax of the order. |
DataArea/Order/OrderHeader/OrderCharges/TotalShippingTax/@currency |
string | Currency of the total shipping tax. |
DataArea/Order/OrderHeader/OrderPaymentInfo/PromotionCode[i] |
string | Promotion codes that were applied to the order. |
DataArea/Order/OrderItem[j]/OrderItemIdentifier/OrderItemID |
long | HCL Commerce ID of the j-th order
item. |
DataArea/Order/OrderItem[j]/OrderItemIdentifier/ExternalOrderItemID |
string | External ID of the j-th order item if
specified in the request. |
DataArea/Order/OrderItem[j]/ProductIdentifier/CatalogEntryID |
long | HCL Commerce catalog entry ID of the
product associated
with the j-th order item. |
DataArea/Order/OrderItem[j]/ProductIdentifier/SKU |
string | SKU of the product associated with the
j-th order item. |
DataArea/Order/OrderItem[j]/Quantity |
double | Quantity value of the j-th order item. |
DataArea/Order/OrderItem[j]/Quantity/@uom |
string | Unit of measure of the quantity value, for example, "C62" for unitless. See quantity units. |
DataArea/Order/OrderItem[j]/OrderItemCharges/UnitPrice/Price |
decimal | Unit price of the product associated
with the j-th order item. |
DataArea/Order/OrderItem[j]/OrderItemCharges |
string | Currency of the unit price. |
DataArea/Order/OrderItem[j]/OrderItemCharges/UnitPrice/Quantity |
double | Quantity value representing a single unit in the unit price. |
DataArea/Order/OrderItem[j]/OrderItemCharges |
string | Unit of measure of the quantity value. |
DataArea/Order/OrderItem[j]/OrderItemCharges/PriceOverride |
boolean | True 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 |
boolean | True if the j-th order item is a free
gift, false otherwise. |
DataArea/Order/OrderItem[j]/OrderItemCharges/OrderItemPrice |
decimal | Total price of the j-th order item before
adjustments, shipping
charge and taxes. |
DataArea/Order/OrderItem[j]/OrderItemCharges |
string | Currency of the order item price. |
DataArea/Order/OrderItem[j]/OrderItemCharges/Adjustment[k]/Type |
String | Adjustment 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 |
String | Adjustment 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 |
String | External description of the k-th adjustment
to the j-th order
item. |
DataArea/Order/OrderItem[j]/OrderItemCharges/Adjustment[k] |
int | Language of the description. |
DataArea/Order/OrderItem[j]/OrderItemCharges/Adjustment[k]/Amount |
decimal | Adjustment 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] |
string | Currency of the adjustment amount. |
DataArea/Order/OrderItem[j]/OrderItemCharges |
string | Display 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 |
decimal | Total shipping charge of the order. |
DataArea/Order/OrderItem[j]/OrderItemCharges/ShippingCharge/@currency |
string | Currency of the total shipping charge. |
DataArea/Order/OrderItem[j]/OrderItemCharges/SalesTax |
decimal | Total sales tax of the order. |
DataArea/Order/OrderItem[j]/OrderItemCharges/SalesTax/@currency |
string | Currency of the total sales tax. |
DataArea/Order/OrderItem[j]/OrderItemCharges/ShippingTax |
decimal | Total shipping tax of the order. |
DataArea/Order/OrderItem[j]/OrderItemCharges/ShippingTax/@currency |
string | Currency of the total shipping tax. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | Line 1 of the shipping address of the
j-th order item. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | Line 2 of the shipping address of the
j-th order item. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | Line 3 of the shipping address of the
j-th order item. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | City field of the shipping address of
the j-th order item. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | State/province field of the shipping address
of the j-th order
item. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | Country field of the shipping address
of the j-th order item. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | ZIP code/postal code field of the shipping
address of the j-th
order item. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingModeID |
int | 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. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
long | HCL Commerce ID of the shipping charge
policy associated
with the j-th order item, if applicable. |
DataArea/Order/OrderItem[j]/OrderItemShippingInfo |
string | Shipping carrier account number of the shipping mode, if applicable. |
* Namespace prefixes ignored for simplicity.
Examples
- Sample AcknowledgeOrder BOD 1 - response of successfully pricing and validating an order originating from HCL Commerce
- Sample AcknowledgeOrder BOD 2 - response of successfully pricing and validating an order not originating from HCL Commerce
- Sample AcknowledgeOrder BOD 3 - response of successfully pricing and validating and order with price overrides
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* | Type | Description |
|---|---|---|
DataArea/Acknowledge/ResponseCriteria/ChangeStatus/Code |
string | The correlation identifier. Can be used to uniquely identify an exception in the server logs. |
DataArea/Acknowledge/ResponseCriteria |
string | The 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 |
string | The exception message. |
* Namespace prefixes ignored for simplicity.
Examples
- Sample AcknowledgeOrder BOD 4 - exception response when missing a required parameter
- Sample AcknowledgeOrder BOD 5 - exception response when product entitlement validation failed
Note: The releaseID and versionID attributes should
be blank
when calling the service and ignore the attributes returned in response
BOD.