Develop > Persistence layer > WebSphere Commerce Web services with JSP pages > Understand the WebSphere Commerce Web service framework > WebSphere Commerce as a service provider > Inbound Web services provided


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.


Typical use cases


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 Ship 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 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 Ship 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* 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

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

Related reference

Inbound Web services provided