Order Status 2.0.0

PROMOTIONAL PRODUCTS DATA INTERFACE SPECIFICATION FOR WEB SERVICES

PromoStandards Logo

Promotional Products Data Interface Specification for Web services

Order Status 2.0.0

Date: 5/18/2023

Document Change Log

VersionDateReason for ChangeAuthors
2.0.02023-05-18Version 2.0.0 FinalStephen Luisser - Hit Promotional ProductsRaj Mukherjee – Hit Promotional Products

Contributors

The following have contributed to the creation of this specification:

Contributors:

  • The PromoStandards Standards Committee

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.

This document assumes that the reader is fluent in web based technologies and has knowledge of the programming language they plan to create or consume the web service with.

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 http://www.w3.org/TR/soap12-part1/ (opens in a new tab).

Service Details

Function: getOrderStatus()

This function provides a mechanism to get order status by specific parameters such as purchase order number, sales order number, or transaction id. This allows the consumer of the service to obtain order status information grouped by purchase order number and sales order number for their needs. This function is required to implement.

Request: GetOrderStatusRequest

FieldDescriptionData TypeRequired
wsVersionThe Standard Version of the Web Service being referenced64 STRINGTRUE
idThe id of the entity making the request or any other agreed upon Id64 STRINGTRUE
passwordThe password associated with the customerId64 STRINGFALSE
queryTypeThe type of query you wish to perform, see the queryType facet for acceptable valuesFACET STRINGTRUE
referenceNumberThe purchase order number for queryType poSearch, the sales order number for queryType soSearch, or the transaction id for queryType transactionId. Required when any of these queryTypes are specified.64 STRINGFALSE
statusTimeStampBeginning datetime since last status change in UTC. This allows an entity to request status for any orders which have been updated since this datetime. 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. Required with queryType lastUpdate.DATETIMEFALSE
returnIssueDetailTypeReturns detailed information regarding order issues including recommended actions to resolve open issues if available when set to TRUE. See the returnIssueDetailsType facet for acceptable values. When this parameter is not included, the noIssues option is used.FACET STRINGFALSE
returnProductDetailReturns detailed information regarding the order/line item information when set to TRUE. The default value FALSE is used when this parameter is not included.BOOLEANFALSE

GetOrderStatusRequest queryType

ValueShort NameDescription
poSearchPO SearchQuery based on the Customer provided Purchase Order Number
soSearchSO SearchQuery based on the Customer provided Sales Order Number
lastUpdateLast Update SearchQuery based on all orders with an updated time greater than the value specified in the statusTimeStamp field
allOpenAll Open SearchQuery based on all Sales Orders that currently have a Status other than Complete or Canceled
allOpenIssuesAll Open IssuesQuery based on all open orders that currently have an issue associated with them with an Issue Status of Open or Pending
transactionIdtransactionId SearchQuery based on the transactionId returned when submitting a Purchase Order to the PromoStandards Purchase Order service. This queryType is not applicable for Purchase Orders submitted another way. This is useful to check up on a Purchase Order that is not yet entered in the Suppliers Order Management system. This option may not be supported by all Suppliers and it is not to replace the PO Search option. If this queryType is not supported return error 210, Query Type not supported.

GetOrderStatusRequest returnIssueDetailType

ValueShort NameDescription
noIssuesNo IssuesThe response does not include issues details.
openIssuesOpen IssuesIf supported, the response includes issues details for issues with an Issue Status of Open or Pending.
allIssuesAll IssuesIf supported, the response includes issues details for all issues.

Reply: GetOrderStatusResponse

FieldDescriptionData TypeRequired
OrderStatusArrayAn array of OrderStatus objectsARRAYFALSE
ServiceMessageArrayAn array of ServiceMessage objectsARRAYFALSE

OrderStatus Object

FieldDescriptionData TypeRequired
purchaseOrderNumberThe associated purchase order64 STRINGTRUE
OrderStatusDetailArrayAn array of OrderStatusDetail objects for all sale orders associated with the purchaseOrderNumber even in the case where the queryType is lastUpdate, allOpen, allOpenIssues.ARRAYTRUE
auditURLThe URL to a page that can be used to find additional details about the Purchase Order. This page may include the XML posted to the PromoStandards Purchase Order service, a visual representation of the Purchase Order, a visual representation of the Invoice, or other relevant information.1024 STRINGFALSE

OrderStatusDetail Object

FieldDescriptionData TypeRequired
salesOrderNumberThe associated sales order. For Purchase Orders that do not have a Sales Order in the Supplier Order Management system yet, use the value N/A.64 STRINGTRUE
statusStatus of the sales order, see the status facet for acceptable valuesFACET 64 STRINGTRUE
issueCategoryThe category of the issue that is placing or will place the order on hold, see the issueCategory facet for acceptable valuesFACET 64 STRINGFALSE
expectedShipDateThe expected date the order should ship in the shipper's timezone. This field does not include a time component.DATEFALSE
expectedDeliveryDateThe expected date the order should arrive at the destination, also known as the in hands date. This field does not include a time component.DATEFALSE
additionalExplanationA freeform text field which can include additional details about the status of the sales order1024 STRINGFALSE
qualityProofURLA URL of the product with logo1024 STRINGFALSE
OrderContactArrayAn array of Contact objects. Enables the consumer to know whom to contact about the order.ARRAYFALSE
ProductArrayAn array of Product objects. This field should be populated if returnProductDetail is true in the GetOrderStatusRequest objectARRAYFALSE
IssueArrayAn array of Issue objects. This field should not be populated if returnIssueDetailType is noIssues in the GetOrderStatusRequest objectARRAYFALSE
validTimestampTime in UTC of the last status change for the sales order. This is not the time of the request or response.DATETIMETRUE

Contact Object

FieldDescriptionData TypeRequired
accountNameThe name of the account for the contact if applicable64 STRINGFALSE
accountNumberThe number of the account for the contact if applicable64 STRINGFALSE
contactTypeThe type of contact, see the contactType facet for acceptable valuesFACET 64 STRINGTRUE
ContactDetailsA ContactDetails object which contains the details about the contactOBJECTTRUE

ContactDetails Object

FieldDescriptionData TypeRequired
attentionToAttention To (first and last name of contact, department, or role)35 STRINGFALSE
companyNameThe Company name for the contact. When dealing with a conglomerate or company with multiple divisions, the account name in the Contact Object may differ from the value specified here.35 STRINGFALSE
address1Address line 135 STRINGFALSE
address2Address line 235 STRINGFALSE
address3Address line 335 STRINGFALSE
cityThe city30 STRINGFALSE
regionThe 2 character US state abbreviation or 2-3 character non-US region3 STRINGFALSE
postalCodeThe postal code10 STRINGFALSE
countryThe country in ISO 3166-2 format2 STRINGFALSE
emailEmail address associated with the contact128 STRINGFALSE
phoneThe phone number associated with the contact32 STRINGFALSE
commentsComments regarding the contact for further clarification, use only when absolutely necessarySTRINGFALSE

Product Object

FieldDescriptionData TypeRequired
productIdThe supplier product Id associated to the Order status and supplier sales order line item64 STRINGTRUE
partIdThe supplier part Id associated to the Order Status and supplier sales order line item64 STRINGFALSE
salesOrderLineNumberThe supplier sales order line number64 STRINGTRUE
purchaseOrderLineNumberThe line number on the purchase order supplied by the buyer64 STRINGFALSE
QuantityOrderedA Quantity object, the ordered quantity of the product for the sales order line numberOBJECTTRUE
QuantityShippedA Quantity object, the shipped quantity of the product for the sales order line numberOBJECTFALSE
issueCategoryThe category of the issue that is placing or will place the product for the SO on hold, see the issueCategory facet for acceptable valuesFACET 64 STRINGFALSE
statusStatus of the product for the SO, see the status facet for acceptable valuesFACET 64 STRINGTRUE

Quantity Object

FieldDescriptionData TypeRequired
valueThe quantity valueDECIMALTRUE
uomThe unit of measure for the value, see the quantityUOM facet for acceptable valuesFACET 2 STRINGTRUE

Issue Object

FieldDescriptionData TypeRequired
issueIdA unique identifier to retrieve the details behind the issue. The issueId is used in conjunction with the getIssue method.64 STRINGFALSE
issueStatusThe status of the issue, see the issueStatus facet for acceptable valuesFACET 64 STRINGTRUE
issueCategoryThe category of the issue that is placing or will place the order on hold, see the issueCategory facet for acceptable valuesFACET 64 STRINGTRUE
issueNameThe name of the issue which should provide more specific information than issueCategory and less specific than issueDescription. If no additional information is available use the value from the issueCategory field.64 STRINGFALSE
urgentResponseRequiredIndicates that the order is currently on hold pending information and order is blocked from progressing to completionBOOLEANTRUE
issueDescriptionA detailed description of the issue1024 STRINGFALSE
responseRequiredByThe date/time in UTC that the issue needs to be resolved by in order to not delay the order.ISO 8601FALSE
issueResolutionURLA supplier-hosted URL which provides a custom user interface that allows the consumer to resolve the issue1024 STRINGFALSE
ResolutionArrayAn array of Resolution objectsARRAYFALSE
issueBlockingStatusThe earliest status to which the order cannot progress without resolution, see the status facet for acceptable valuesFor example, without an address the order can be produced (In Production) but cannot ship (Shipped) so the issueBlockingStatus would be "Shipped".FACET 64 STRINGFALSE
ContactArrayAn array of Contact objects. Enables the consumer to know whom to contact about the order.ARRAYFALSE
productIdThe supplier product Id if the issue is for a specific product. For order level issues this field should not be set.64 STRINGFALSE

1This object currently provides data regarding issues. A future standard, Order Management is currently under development. This object will communicate issues where resolutions can be electronically sent to a supplier and programmatically resolved. The intent of this is to automate customer service-related activities involving orders. As such, the Issues object and its contained objects may undergo revisions in subsequent versions as Order Management is published.

Resolution Object

FieldDescriptionData TypeRequired
resolutionIdA unique identifier related to the resolution64 STRINGTRUE
resolutionNameShort name to describe the resolution64 STRINGTRUE
resolutionDescriptionDetailed description of the resolution1024 STRINGTRUE
ParameterArrayParameters to resolve the issueARRAYFALSE

Parameter Object

FieldDescriptionData TypeRequired
parameterIdThe identifier for the parameter64 STRINGTRUE
nameShort name of the parameter64 STRINGTRUE
typeThe type of variable that the parameter represents Recommended to use ANSI SQL Data Types64 STRINGFALSE
displayOrderThe order in which to display the parameter to the userINTEGERFALSE
requiredIs the parameter required to process the itemBOOLEANTRUE
lengthThe length of the parameterINTEGERFALSE
pspoFieldNameThe field name of the parameter name in PromoStandards Purchase Order format64 STRINGFALSE
pspoVersionThe version of the PromoStandards Purchase Order pspoFieldName is referencing. This must be set if the pspoFieldName is set.64 STRINGFALSE
validResponseArrayAn array of valid responses for this parameterOBJECTFALSE

ValidResponse Object

FieldDescriptionData TypeRequired
valueA valid response for the related parameterSTRINGTRUE

ServiceMessage Object

FieldDescriptionData TypeRequired
codeThe numerical value of the codeINTEGERTRUE
descriptionResponse for any message requiring notification to requestor256 STRINGTRUE
severityThe severity of the message, see the serviceMessageSeverity facet for acceptable valuesFACET 64 STRINGTRUE

Function: getIssue()

This function provides a mechanism to get details for an issue. This function is optional to implement.

Request: GetIssueRequest

FieldDescriptionData TypeRequired
wsVersionThe Standard Version of the Web Service being referenced64 STRINGTRUE
idThe customerId or any other agreed upon Id64 STRINGTRUE
passwordThe password associated with the customerId64 STRINGFALSE
issueIdThe issueId for which the latest information should be returned64 STRINGTRUE

Reply: GetIssueResponse

FieldDescriptionData TypeRequired
IssueArrayAn array of Issue objects.ARRAYFALSE
ServiceMessageArrayAn array of ServiceMessage objectsARRAYFALSE

Function: getServiceMethods()

This function provides a mechanism to get a methods supported by the implementation of the service. This function is required to implement.

Request: GetServiceMethodsRequest

FieldDescriptionData TypeRequired
wsVersionThe Standard Version of the Web Service being referenced64 STRINGTRUE
idThe customerId or any other agreed upon Id64 STRINGTRUE
passwordThe password associated with the customerId64 STRINGFALSE

Reply: GetServiceMethodsResponse

FieldDescriptionData TypeRequired
ServiceMethodArrayAn array of ServiceMethod objectsARRAYFALSE
ServiceMessageArrayAn array of ServiceMessage objectsARRAYFALSE

ServiceMethod Object

FieldDescriptionData TypeRequired
serviceMethodThe name of a function that the implementation of the service supports. Acceptable values: {getOrderStatus, getIssue, getServiceMethods}128 STRINGTRUE

Guidance

The ContactDetails object should include at a minimum an address, email, or phone.

All functions in this service have an optional array to return data and a ServiceMessageArray. As such, at least one array should be populated in the response.

Fields with the DATETIME data type are to be in UTC using the ISO 8601 format and not include a time zone. An example of a properly formatted ISO 8601 UTC date is 2022-06-14T15:26:32Z

There may be limitations with the amount of data that can be processed or returned with a call to GetOrderStatusRequest. An example is limiting the date search to 60 days. For cases such as this, you can return Service Message 125 - Not Supported with the appropriate severity.

It is recommended that the getOrderStatus function when called by lastUpdate supports going back at least a minimum of 7 days.

For Status at the order and product level. Issues such as a back order should be reported as the status even if the majority of items are not backordered. The worst status should be returned when there are products on the order with different statuses. If the preference is to discretely show backordered products for a purchase order, backordered products can be moved to another sales order.

For scenarios for a Purchase Order using Sales Order Number N/A.

  • If the Purchase Order is still being processed or in a manual review, the Status returned should be Order Received and any relevant details should be included in the additionalExplanation field.
  • If the Purchase Order has been rejected, the Status returned should be Canceled and any relevant details should be included in the additionalExplanation field.
  • If the Purchase Order was not found, even when searching by transactionId, a service message with Code 220, No Orders were found for the requested criteria

Enumerated Type Restrictions (FACET)

status Facet

NameDescriptionEnumeration Value
ReceivedOrder or line item has been receivedreceived
ConfirmedOrder or line item has been received, entered, and acceptedconfirmed
PreproductionVendor has begun to process the order, but it is not in productionpreproduction
In ProductionProduction of the order has startedinProduction
In StorageOrder or line item is complete, but the vendor is waiting to ship goodsinStorage
Partially ShippedOrder or line item has shipped in Part; remaining items in productionpartiallyShipped
ShippedOrder or line item has shipped in fullshipped
CompleteOrder or line item has shipped in full and invoiced, No further updates will be givencomplete
CanceledOrder or line item has been canceled, no further updates will be givencanceled

issueCategory Facet

NameDescriptionEnumeration Value
Order Entry HoldVendor has a problem with the data in the purchase order, and it is preventing the order from being enteredorderEntryHold
General HoldSomething is preventing the order from being enteredgeneralHold
Credit HoldVendor is awaiting payment from the customercreditHold
Proof HoldVendor is awaiting response to proofproofHold
Art HoldVendor is awaiting suitable artwork from the customerartHold
Back Order HoldOrder or line item has been backordered; Nothing has shipped yetbackOrderHold
Shipping HoldOrder or line item has been produced and is on hold preventing shippingshippingHold
Customer Supplied Item HoldOrder or line item is on hold waiting for customer owned goodscustomerSuppliedItemHold

Simple Facets

FieldDescriptionData TypeEnumeration Values
contactTypeThe type of contactFACET 64 STRINGArt
Bill
Expeditor
Order
Sales
Sold
issueStatusThe status of an IssueFACET 64 STRINGPending
Open
Closed
quantityUOMThe unit of measure for quantity based fieldFACET 2 STRINGBX (Box)
CA (Case)
DZ (Dozen)
EA (Each)
KT (Kit)
PK (Package)
PR (Pair)
RL (Roll)
SL (Sleeve)
ST (Set)
TH (Thousand)
serviceMessageSeverityThe severity of the messageFACET 64 STRINGError
Information
Warning

DATA MINING / ABUSE GUIDELINE

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 located at: https://www.promostandards.org/PromoStandards-Service-Validator (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."

Appendix A: Service Messages

Standardized Codes

The range of 100-199 has been reserved for standardized error codes. The number 999 has been reserved for an error codes that is a "General Error - Contact System Service Provider"

CodeDescription
100ID (customerID) not found
104This account is unauthorized to use this service. Please contact the service provider
105Authentication Credentials failed
110Authentication Credentials required
115wsVersion not found
120The following field(s) are required [Comma Delimited field names]
125Not Supported
130Function not supported
999General Error – Contact the System Service Provider

Service Specific Codes

These error codes are only for this service.

CodeDescription
200queryType not found
210queryType not supported
212Function does not support returning issues
[This message is used when the implementation does not support returning issues.]
213returnIssueDetailType not supported
[This message is used when the implementation supports returning issues but not the type requested. For example, allIssues is specified but the function can only return openIssues.
214Function does not support returning Product Details
220No Orders were found for the requested criteria
230No Issue was found for the given issue identifier
240The specified Issue has already been resolved
250statusTimeStamp is incorrect or is an invalid date range

Diagrams

getOrderStatusDetails Function