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
- 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 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
- 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 Ship 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
The releaseID and versionID attributes should be blank when calling the service and ignore the attributes returned in response BOD.
Related reference