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 you 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 WC_eardir/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 that is 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 that is 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

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