Order status update service

Order status update service

The order status update service is an inbound web service responsible for updating the status of an order in WebSphere Commerce when a store is configured to use an external system for order processing and fulfillment. This inbound web service is typically called by the external system to update the status of a transferred order in WebSphere Commerce for display purposes when the status of the order is changed in the external system.

Typical use cases

An order was captured by WebSphere Commerce and transferred to an external order management system (OMS) for processing and fulfillment. The status of the order is changed in the external OMS. The status of the same order in WebSphere Commerce must be updated so that the shopper can see this change when they are viewing the order status through WebSphere Commerce.

Endpoint URL and operation

The default endpoint URL of this inbound web service is https://host_name:8000/webapp/wcs/services/OrderServices. The operation of the service is SyncOrder, with the SyncOrder BOD as request and the ConfirmBOD BOD as response.
Note: If you plan to use SyncOrder to update the ORDERS and ORDERITEMS database tables we must set the syncWCSOrderStatus property flag to true in the order component wc-admin-component.xml configuration file. To set this flag, navigate to the workspace_dir/WC/xml/config/com.ibm.commerce.order directory and open the wc-admin-component.xml file for editing. Add the following configuration group with the syncWCSOrderStatus property flag set to true:
<_config:configgrouping name="SyncOrder"> 
<_config:property name="syncWCSOrderStatus" value="true"/>
</_config:configgrouping>
Request

Requests to this inbound web service are in the form of SyncOrder BODs. They are mapped to the OrderStatus command and contain the following information:

XPath* Type Maps to Description Required
ApplicationArea/BusinessContext/ContextData User Data - The business context area of the request. Typically used to provide business context data such as store ID and language ID. -
ApplicationArea/UserArea/SequenceNumber string sequenceNumber The sequence number of the order status update request. Used for determining the sequence of order status update requests for the same order when requests might be received by WebSphere Commerce out of sequence. N
ApplicationArea/CreationDateTime dateTime lastUpdateTime The creation date of the order status update request. Used for determining the sequence of order status update requests for the same order requests might be received by WebSphere Commerce out of sequence and that the sequence numbers of the requests are not provided. N
DataArea/Sync/ActionCriteria/ActionExpression/@actionCode string actionCode The action code. Must be "Update" Y
DataArea/Order/OrderHeader/OrderIdentifier/OrderID long orderId WebSphere Commerce order ID of the order. Y
DataArea/Order/OrderHeader/OrderIdentifier/ExternalOrderID string merchantOrderNumber External order ID of the order. N
DataArea/Order/OrderHeader/OrderCharges/TotalProductPrice/@currency string currency Currency of the order charges. N
DataArea/Order/OrderHeader/OrderCharges/TotalProductPrice decimal priceTotal Total product price of the order. N
DataArea/Order/OrderHeader/OrderCharges/TotalShippingCharge decimal shippingTotal Total shipping charge of the order. N
DataArea/Order/OrderHeader/OrderCharges/TotalSalesTax decimal taxTotal Total sales tax of the order. N
DataArea/Order/OrderHeader/OrderCharges/TotalShippingTax decimal shippingTaxTotal Total shipping tax of the order. N
DataArea/Order/OrderHeader/OrderShippingInfo/RequestedShipDateTime dateTime requestShipDateTime Requested ship date of the order. N
DataArea/Order/OrderHeader/OrderShippingInfo/UserData/UserDataField[@name='shipCondition'] string shipCondition Code indicating whether partial shipment of the order is accepted. Valid values:

SC = ship complete order
SP = ship partial order

N
DataArea/Order/OrderHeader/OrderShippingInfo/UserData/UserDataField[@name='shippingModeFlag'] string shippingModeFlag Code indicating the level for the shipping address and shipping mode. Valid values:

O = order level
I = item level

N
DataArea/Order/OrderHeader/OrderStatus/Status string orderStatus Status of the order. N
DataArea/Order/OrderHeader/CustomerComments string comment Customer comments that regard the order. N
DataArea/Order/OrderHeader/PlacedDateTime dateTime placeDateTime Date the order was placed. N
DataArea/Order/OrderItem[i]/OrderItemIdentifier/OrderItemID long orderItemId_i WebSphere Commerce order item ID of the i-th order item, if applicable. Y
DataArea/Order/OrderItem[i]/OrderItemIdentifier/ExternalOrderItemID string merchantItemNumber_i External order ID of the i-th order item. N
DataArea/Order/OrderItem[i]/ProductIdentifier/SKU string partNumber_i SKU of the product associated with the i-th order item. N
DataArea/Order/OrderItem[i]/Quantity double quantityRequested_i Quantity value of the i-th order item. N
DataArea/Order/OrderItem[i]/OrderItemCharges/UnitPrice/Price decimal unitPrice_i Unit price of the product associated with the i-th order item. N
DataArea/Order/OrderItem[i]/OrderItemCharges/UnitPrice/Price/@currency string currency_i Currency of the order item charges. N
DataArea/Order/OrderItem[i]/OrderItemCharges/OrderItemPrice decimal priceTotal_i Order item price of the i-th order item. N
DataArea/Order/OrderItem[i]/OrderItemCharges/ShippingCharge decimal shippingTotal_i Shipping charge of the i-th order item. N
DataArea/Order/OrderItem[i]/OrderItemCharges/SalesTax decimal taxTotal_i Sales tax of the i-th order item. N
DataArea/Order/OrderItem[i]/OrderItemCharges/ShippingTax decimal shippingTaxTotal_i Shipping tax of the i-th order item. N
DataArea/Order/OrderItem[i]/OrderItemShippingInfo/RequestedShipDateTime dateTime requestShipDateTime Requested ship date of the i-th order item. N
DataArea/Order/OrderItem[i]/OrderItemShippingInfo/UserData/UserDataField[@name='shipCondition'] string shipCondition_i Code indicating whether the partial shipment of the order is accepted. Valid values:

SC = ship complete order
SP = ship partial order

N
DataArea/Order/OrderItem[i]/OrderItemShippingInfo/UserData/UserDataField[@name='shippingModeFlag'] string shippingModeFlag_i Code indicating the level for the shipping address and shipping mode. Valid values:

O = order level
I = item level

N

* Namespace prefixes that are ignored for simplicity.

Response

Responses of this inbound web service are in the form of ConfirmBOD BODs. They contain the following information:

XPath* Type Description
DataArea/BOD/BODSuccessMessage - This element is present if the request was successful.

* Namespace prefixes that are ignored for simplicity.

Examples

Sample ConfirmBOD BOD 1 - response of successfully updating the status of order

Exceptions

All exceptions are in the form of ConfirmBOD BODs with a ResponseCriteria element under the Confirm verb. They contain the following information:

XPath* Type Description
DataArea/Confirm/ResponseCriteria/ChangeStatus/Code string The correlation identifier. Can be used to uniquely identify an exception in the server logs.
DataArea/Confirm/ResponseCriteria/ChangeStatus/ReasonCode string The reason code. This code 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. This system error code can be unavailable in the case of application exceptions.
DataArea/Confirm/ResponseCriteria/ChangeStatus/Reason string The exception message.

* Namespace prefixes that are ignored for simplicity.

Examples

Sample ConfirmBOD BOD 4 - exception response when a required parameter is missing.

Related reference
Inbound web services provided

XPath*	Type	Maps to	Description	Required
ApplicationArea/BusinessContext/ContextData	User Data	-	The business context area of the request. Typically used to provide business context data such as store ID and language ID.	-
ApplicationArea/UserArea/SequenceNumber	string	sequenceNumber	The sequence number of the order status update request. Used for determining the sequence of order status update requests for the same order when requests might be received by WebSphere Commerce out of sequence.	N
ApplicationArea/CreationDateTime	dateTime	lastUpdateTime	The creation date of the order status update request. Used for determining the sequence of order status update requests for the same order requests might be received by WebSphere Commerce out of sequence and that the sequence numbers of the requests are not provided.	N
DataArea/Sync/ActionCriteria/ActionExpression/@actionCode	string	actionCode	The action code. Must be "Update"	Y
DataArea/Order/OrderHeader/OrderIdentifier/OrderID	long	orderId	WebSphere Commerce order ID of the order.	Y
DataArea/Order/OrderHeader/OrderIdentifier/ExternalOrderID	string	merchantOrderNumber	External order ID of the order.	N
DataArea/Order/OrderHeader/OrderCharges/TotalProductPrice/@currency	string	currency	Currency of the order charges.	N
DataArea/Order/OrderHeader/OrderCharges/TotalProductPrice	decimal	priceTotal	Total product price of the order.	N
DataArea/Order/OrderHeader/OrderCharges/TotalShippingCharge	decimal	shippingTotal	Total shipping charge of the order.	N
DataArea/Order/OrderHeader/OrderCharges/TotalSalesTax	decimal	taxTotal	Total sales tax of the order.	N
DataArea/Order/OrderHeader/OrderCharges/TotalShippingTax	decimal	shippingTaxTotal	Total shipping tax of the order.	N
DataArea/Order/OrderHeader/OrderShippingInfo/RequestedShipDateTime	dateTime	requestShipDateTime	Requested ship date of the order.	N
DataArea/Order/OrderHeader/OrderShippingInfo/UserData/UserDataField[@name='shipCondition']	string	shipCondition	Code indicating whether partial shipment of the order is accepted. Valid values: SC = ship complete order SP = ship partial order	N
DataArea/Order/OrderHeader/OrderShippingInfo/UserData/UserDataField[@name='shippingModeFlag']	string	shippingModeFlag	Code indicating the level for the shipping address and shipping mode. Valid values: O = order level I = item level	N
DataArea/Order/OrderHeader/OrderStatus/Status	string	orderStatus	Status of the order.	N
DataArea/Order/OrderHeader/CustomerComments	string	comment	Customer comments that regard the order.	N
DataArea/Order/OrderHeader/PlacedDateTime	dateTime	placeDateTime	Date the order was placed.	N
DataArea/Order/OrderItem[i]/OrderItemIdentifier/OrderItemID	long	orderItemId_i	WebSphere Commerce order item ID of the i-th order item, if applicable.	Y
DataArea/Order/OrderItem[i]/OrderItemIdentifier/ExternalOrderItemID	string	merchantItemNumber_i	External order ID of the i-th order item.	N
DataArea/Order/OrderItem[i]/ProductIdentifier/SKU	string	partNumber_i	SKU of the product associated with the i-th order item.	N
DataArea/Order/OrderItem[i]/Quantity	double	quantityRequested_i	Quantity value of the i-th order item.	N
DataArea/Order/OrderItem[i]/OrderItemCharges/UnitPrice/Price	decimal	unitPrice_i	Unit price of the product associated with the i-th order item.	N
DataArea/Order/OrderItem[i]/OrderItemCharges/UnitPrice/Price/@currency	string	currency_i	Currency of the order item charges.	N
DataArea/Order/OrderItem[i]/OrderItemCharges/OrderItemPrice	decimal	priceTotal_i	Order item price of the i-th order item.	N
DataArea/Order/OrderItem[i]/OrderItemCharges/ShippingCharge	decimal	shippingTotal_i	Shipping charge of the i-th order item.	N
DataArea/Order/OrderItem[i]/OrderItemCharges/SalesTax	decimal	taxTotal_i	Sales tax of the i-th order item.	N
DataArea/Order/OrderItem[i]/OrderItemCharges/ShippingTax	decimal	shippingTaxTotal_i	Shipping tax of the i-th order item.	N
DataArea/Order/OrderItem[i]/OrderItemShippingInfo/RequestedShipDateTime	dateTime	requestShipDateTime	Requested ship date of the i-th order item.	N
DataArea/Order/OrderItem[i]/OrderItemShippingInfo/UserData/UserDataField[@name='shipCondition']	string	shipCondition_i	Code indicating whether the partial shipment of the order is accepted. Valid values: SC = ship complete order SP = ship partial order	N
DataArea/Order/OrderItem[i]/OrderItemShippingInfo/UserData/UserDataField[@name='shippingModeFlag']	string	shippingModeFlag_i	Code indicating the level for the shipping address and shipping mode. Valid values: O = order level I = item level	N

XPath*	Type	Description
DataArea/Confirm/ResponseCriteria/ChangeStatus/Code	string	The correlation identifier. Can be used to uniquely identify an exception in the server logs.
DataArea/Confirm/ResponseCriteria/ChangeStatus/ReasonCode	string	The reason code. This code 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. This system error code can be unavailable in the case of application exceptions.
DataArea/Confirm/ResponseCriteria/ChangeStatus/Reason	string	The exception message.