Order Status 1.0.0


PromoStandards Logo

Order Status 1.0.0

Version: 1.0.0
Release Date: 2015-07-01

Document Change Log

VersionDateReason for ChangeAuthor
0.0.12014-05-12Initial DraftJon Norris, System Operations Manager, Starline USA
0.0.22014-05-13- Changed Order Status Detail into multidimensional array to accommodate multiple sales orders to one purchase order. - Added Credit Hold and Backorder Statuses. - Added In Hands Date Field - Added Ship MethodEric Shonebarger, CIO, Hit Promotional Products Inc
0.0.32014-05-30- Added support for requesting single purchase order or array of purchase orders based on date - Added statusTimeStampto request - Changed function name: getOrderStatusDetails() - Fixing array naming to OrderStatusDetailArray - Created function getOrderStatusTypes()Jon Norris, System Operations Manager, Starline USA
0.0.42014-07-07- Added unique request and response names for both methods - Fixed Required Flag on expectedInHandsDateJon Norris, System Operations Manager, Starline USA
0.0.52015-04-13- Changed purchaseOrder references to referenceNumber (more generic) - Changed to more rigid search parameters and warned everyone to account for time jitter - Changed Search parameter to UTC - Changed Status Codes to reflect desire for logical progression and to conform to traditional 855/997 documentsEric Shonebarger, CIO, Hit Promotional Products, Inc
0.0.8- Made some adjustments to status codes in order to facilitate adoption as well as their descriptions - Changed “inHandsDate” to “expectedDeliveryDate” and adjusted description to be more descriptive - Adjusted factoryOrderNumber description - Made the ResponseToArray description a little more descriptive - Adjusted customMessage to 1024 - Added the boolean responseRequired to determine if a status requires a response from the distributor - Made the “Custom Message” more descriptiveEric Shonebarger, CIO, Hit Promotional Products, Inc
0.0.9- Updated explanation for purchase order naming. - Renamed custom message to “additionalExplanation” - Changed statusID data type to Integer (Enumeration) from NumberJon Norris, VP Operations, Starline

Abstract and Recommended Audience

This document describes the technologies for integration of suppliers and distributors in the Promotional Products Industry. This document will discuss in detail the technology required in order to build the interface. Additionally, this document will provide sample code in order to use the interface.

This document will assume that the reader is fluent in web based technologies, and has knowledge of the language they plan to consume the web service in.

Background Information

All specifications will be built using the Simple Object Access Protocol (SOAP) over HTTPS as the foundation for the web services protocol stack in order to provide a standards based secure form of communication.

More information on SOAP can be found at w3 (opens in a new tab)

Service Details:




FieldDescriptionData TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced64 STRINGTRUE
idThe customerID or any other agreed upon ID.64 STRINGTRUE
passwordThe password associated with the customerID.64 STRINGFALSE
queryTypeThe type of query you wish to perform1INTTRUE
referenceNumberThe purchase order/sales order associated with the order.64 STRINGFALSE
statusTimeStampBeginning date time since last status change in UTC2ISO 8601FALSE
queryTypeShort NameDescription
1PO SearchQuery based on customer provided purchase order number.
2SO SearchQuery based on vendor assigned sales order number
3Last Update SearchQuery based on all orders with an update time greater than the value specified in statusTimeStamp.
4All Open SearchQuery based on all orders that currently have a status other than “Complete” and “Cancelled”



FieldDescriptionData TypeRequired?
OrderStatusArray3An array of order statusARRAYTRUE
errorMessageResponse for any error requiring notification to requestor256 STRINGFALSE

OrderStatus Object

FieldDescriptionData TypeRequired?
purchaseOrderNumberThe associated Purchase Order Number from the customer64 STRINGTRUE
OrderStatusDetailArray4Array of OrderStatusDetailsARRAYTRUE

OrderStatusDetail Object

FieldDescriptionData TypeRequired?
factoryOrderNumberThe associated factory sales order number (This is used in the example of internal PO splitting at the factory level)64 STRINGTRUE
statusID2Paired standard order status from allowed valuesIntegerTRUE
statusName2Textual description of statusID256 STRINGTRUE
expectedShipDateThe expected ship date for the purchase orderISO 8601FALSE
expectedDeliveryDateThe expected date the order should arrive at customer also known as the “in hands date”ISO 8601FALSE
ResponseToArray1An array of human contact information such as email, phone, and rep name so the distributor knows who to get in contact to fix an issue.ARRAYFALSE
additionalExplanation5This allows further detail about the status1024 STRINGFALSE
responseRequiredTrue or False to determine if it is necessary to provide information back to the supplier to complete the orderBooleanTRUE
validTimestampTime of order statusISO 8601TRUE
  • If the Order Status is 43 (Artwork Hold), The custom message could be “Size of Text is too small.”
  • If the Order Status is 11 (Order Entry Hold) The custom message could be “We can’t meet your delivery date with the ship method provide.”

Using additionalExplanation in conjunction with the ResponseToArray will point the distributor who to contact to fix the issue.

ResponseTo Object

FieldDescriptionData TypeRequired?
nameThe name of the person to respond to256 STRINGFALSE
emailAddressA monitored email address that a recipient can send their response to256 STRINGFALSE
phoneNumberThe phone number of the person to respond256 STRINGFALSE



FieldDescriptionData TypeRequired?
wsVersionThe Standard Version of the Web Service being referenced64 STRINGTRUE
idThe customerID or any other agreed upon ID.64 STRINGTRUE
passwordThe password associated with the customerID.64 STRINGFALSE


GetOrderStatusTypes Response

FieldDescriptionData TypeRequired?
StatusArray1An array of order statusARRAYTRUE
errorMessageResponse for any error requiring notification to requestor256 STRINGFALSE


FieldDescriptionData TypeRequired?
idThe numerical value of the order statusNUMBERTRUE
nameThe string status name from possible values2256 STRINGTRUE
StatusIDStatus NameDescription
10Order ReceivedOrder has been received.
11Order Entry HoldVendor has a problem with the data in the purchase order, and it is preventing the order from being entered.
20Order ConfirmedOrder has been received, entered, and accepted
30Pre-ProductionVendor has begun to process the order, but it is not in production
40General HoldSomething is preventing the order from being entered
41Credit HoldVendor is awaiting payment from customer
42Proof HoldVendor is awaiting response to proof
43Art HoldVendor is awaiting suitable artwork from customer
44Back Order HoldOrder has been backordered; Nothing has shipped yet.
60In ProductionProduction of the order has started
70In StorageOrder is complete, but vendor is waiting to ship goods
75Partial ShipmentOrder has shipped in Part; remaining items in production
80CompleteOrder has shipped in full—No further updates will be given
99CanceledOrder has been canceled—No further updates will be given

Code Samples

To be published under separate specification: “Inventory Interface Standards Use Examples”


The use of services detailed within this specification are to be conducted within the current guidelines of the “Interface Data Use Guidelines Standards”

Validation of Services

Before you publish your endpoint, please ensure that it adheres to the promostandards.org spec by using the web service validation tool.

http://services.promostandards.org/webserviceValidator/home (opens in a new tab)

Select the service, version, method and input your endpoint. If the endpoint is correct you should receive a message of:

"The XML response is valid."


getOrderStatusDetails Function

getOrderStatusTypes Function


  1. This indicates the type of query you are trying to perform. Valid Options: 2 3

  2. This field will indicate the change date time for any status change GREATER than the date time stamp provided. Note: Make sure to account for some jitter between the two systems and make sure to specify your time request in UTC and not in the local time zone. 2 3 4

  3. OrderStatusArray

  4. OrderStatusDetailArray

  5. customMessage Examples: