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 WebSphere Commerce, and for calculating its prices, discounts, shipping charges, taxes and so forth using settings in WebSphere 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 WebSphere 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 WebSphere Commerce and transferred to an external order management system for processing and fulfillment. The order was already validated and priced by WebSphere Commerce before the transfer, but is modified post-transfer by customer request and needs to be revalidated and reprised.
An order is captured by a channel not managed by WebSphere Commerce but needs WebSphere 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/` `ActionExpression/@actionCode`	string	`actionCode`	The action code. Must be " `Preprocess`".	Y
`DataArea/Order/OrderHeader` `/OrderIdentifier/OrderID`	long	`orderId`	WebSphere 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`	WebSphere Commerce ID of the store under which the order should be processed.	Y
`DataArea/Order/OrderHeader/OrderReferences/` `CustomerIdentifier/UniqueID`	long	`customerId`	WebSphere 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`	WebSphere 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`	WebSphere 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 WebSphere 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 WebSphere 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`	WebSphere 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`	WebSphere 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

Sample ProcessOrder BOD 1 - validating and pricing an order originating from WebSphere Commerce
Sample ProcessOrder BOD 2 - validating and pricing an order not originating from WebSphere 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	WebSphere 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	WebSphere Commerce store ID of the store under which the order was processed.
`DataArea/Order/OrderHeader/OrderReferences` `/BuyerOrganizationIdentifier/UniqueID`	long	WebSphere Commerce organization ID of the buyer organization.
`DataArea/Order/OrderHeader/OrderReferences` `/BuyerOrganizationIdentifier/DistinguishedName`	string	DN of the buyer organization.
`DataArea/Order/OrderHeader/OrderReferences/CustomerIdentifier/UniqueID`	long	WebSphere Commerce user ID of the customer who placed the order.
`DataArea/Order/OrderHeader/OrderReferences` `/CustomerIdentifier/DistinguishedName`	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	WebSphere 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	WebSphere 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` `/UnitPrice/Price/@currency`	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` `/UnitPrice/Quantity/@uom`	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 WebSphere 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` `/OrderItemPrice/@currency`	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 WebSphere Commerce.
`DataArea/Order/OrderItem[j]/OrderItemCharges` `/Adjustment[k]/Description`	String	External description of the k-th adjustment to the j-th order item.
`DataArea/Order/OrderItem[j]/OrderItemCharges/Adjustment[k]` `/Description/@languageID`	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]` `/Amount/@currency`	string	Currency of the adjustment amount.
`DataArea/Order/OrderItem[j]/OrderItemCharges` `/Adjustment[k]/DisplayLevel`	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` `/ShippingAddress/AddressLine[1]`	string	Line 1 of the shipping address of the j-th order item.
`DataArea/Order/OrderItem[j]/OrderItemShippingInfo` `/ShippingAddress/AddressLine[2]`	string	Line 2 of the shipping address of the j-th order item.
`DataArea/Order/OrderItem[j]/OrderItemShippingInfo` `/ShippingAddress/AddressLine[3]`	string	Line 3 of the shipping address of the j-th order item.
`DataArea/Order/OrderItem[j]/OrderItemShippingInfo` `/ShippingAddress/City`	string	City field of the shipping address of the j-th order item.
`DataArea/Order/OrderItem[j]/OrderItemShippingInfo` `/ShippingAddress/StateOrProvinceName`	string	State/province field of the shipping address of the j-th order item.
`DataArea/Order/OrderItem[j]/OrderItemShippingInfo` `/ShippingAddress/Country`	string	Country field of the shipping address of the j-th order item.
`DataArea/Order/OrderItem[j]/OrderItemShippingInfo` `/ShippingAddress/PostalCode`	string	ZIP code/postal code field of the shipping address of the j-th order item.
`DataArea/Order/OrderItem[j]/OrderItemShippingInfo/ShippingModeID`	int	WebSphere 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`	long	WebSphere Commerce ID of the shipping charge policy associated with the j-th order item, if applicable.
`DataArea/Order/OrderItem[j]/OrderItemShippingInfo` `/ShippingCarrierAccountNumber`	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 WebSphere Commerce
Sample AcknowledgeOrder BOD 2 - response of successfully pricing and validating an order not originating from WebSphere 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` `/ChangeStatus/ReasonCode`	string	The reason code, which is either a WebSphere Commerce system error code if available, or the EC message key plus an optional secondary error code if the WebSphere 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.