Order Shipment Notification 2.0.0

PROMOTIONAL PRODUCTS DATA INTERFACE SPECIFICATION FOR WEB SERVICES

PromoStandards Logo

Order Shipment Notification 2.0.0

Date: 12/23/2022

Document Change Log

VersionDateReason for ChangeAuthors
2.0.02022-12-23Version 2.0.0 FinalStephen Luisser - Essent Corporation

Contributors

The following have contributed to the creation of this specification:

Authors:

  • Stephen Luisser, Vice President, Essent Corporation

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

Service Details

Function : getOrderShipmentNotification()

This function provides a mechanism to get shipment details by specific parameters like (purchase order number, sales order number, or shipment date). This allows the consumer of the service to obtain shipment information grouped by purchase order number and sales order number for their needs.

Request: GetOrderShipmentNotificationRequest

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
queryTypeThe type of query you wish to performFACET INTEGERTRUE
referenceNumberThe purchase order number for queryType =1 or the sales order number for queryType = 264 STRINGFALSE
shipmentDateTimestampThe date for of shipments to return in UTC. Required when the queryType is 3. ISO 8601DATEFALSE

GetOrderShipmentNotificationRequest queryType

queryTypeShort NameDescription
1PO Number SearchReturns all shipments for the Purchase Order
2SO Number SearchReturns all shipments for the Sales Order
3Shipment Date SearchReturns all shipments with a shipment date specified by the shipmentDateTimeStamp

Reply: GetOrderShipmentNotificationResponse

FieldDescriptionData TypeRequired
OrderShipmentNotificationArrayAn array of Order Shipment Notification objectsARRAYFALSE
ServiceMessageArrayAn array of ServiceMessage objectsOBJECTFALSE

OrderShipmentNotification Object

FieldDescriptionData TypeRequired
purchaseOrderNumberThe associated purchase order64 STRINGTRUE
purchaseOrderShippedInFullAll shipments for this purchase order are completeBOOLEANTRUE
SalesOrderArrayAn array of Sales Order objects associated with the purchase orderARRAYTRUE

SalesOrder Object

FieldDescriptionData TypeRequired
salesOrderNumberThe associated sales order64 STRINGTRUE
salesOrderShippedInFullAll shipments for this sales order are completeBOOLEANTRUE
ShipmentArrayAn array of Shipment objectsARRAYTRUE

Shipment Object

FieldDescriptionData TypeRequired
destinationShippedInFullAll shipments for this shipping destination location are completeBOOLEANTRUE
customerPickupThe shipment will be a pickup and will not be shipped. Default to false if pickup cannot be determinedBOOLEANTRUE
shipFromAddressShippingContactDetails Object for the Ship-From addressOBJECTTRUE
shipToAddressShippingContactDetails Object for the Ship-To addressOBJECTTRUE
shipmentDestinationTypeUsed to identify the type of destination for the Ship-To addressFACET 64 STRINGFALSE
PackageArrayAn array of Package objectsARRAYTRUE

ShippingContactDetails Object

FieldDescriptionData TypeRequired
attentionToAttention To (first and last name of contact)35 STRINGFALSE
companyNameCompany Name35 STRINGFALSE
address1Address line 135 STRINGTRUE
address2Address line 235 STRINGFALSE
address3Address line 335 STRINGFALSE
cityThe city30 STRINGTRUE
regionThe 2 character US state abbreviation or 2-3 character non-US region3 STRINGTRUE
postalCodeThe postal code10 STRINGTRUE
countryThe country in ISO 3166-2 format2 STRINGFALSE
emailEmail address associated with the contact128 STRINGFALSE
phoneThe phone number associated with the contact32 STRINGFALSE

Package Object

FieldDescriptionData TypeRequired
idThe id of the packageNUMBERFALSE
trackingNumberThe tracking number for the package. Guidance is to always provide a tracking number if available128 STRINGFALSE
shipmentDateThe date for the shipment in UTC. ISO 8601ISO 8601TRUE
DimensionPhysical dimensions and weight. Include this object if you have either a size or weight dimensionOBJECTFALSE
FreightDetailsThe details on the freight: carrier and serviceOBJECTFALSE
shippingAccountThe shipping account used for this shipment128 STRINGFALSE
shipmentTermsThe terms of the shipment (i.e. Prepaid, Collect, Third Party, PPD., etc.)128 STRINGFALSE
ItemArrayA list of items and quantities contained in the packageARRAYFALSE
preProductionProofSignifies if the order is a pre-production proof. Valid options: "Yes", "No", "Unknown"FACET 64 STRINGTRUE

Dimension Object

FieldDescriptionData TypeRequired
DimensionSizePhysical dimensions. Include only if you have at least one physical dimensionOBJECTFALSE
DimensionWeightWeightOBJECTFALSE

DimensionSize Object

FieldDescriptionData TypeRequired
dimensionUomThe dimensional unit of measureFACET 2 STRINGTRUE
lengthThe length of the part using the unit of measure specified in dimensionUomDECIMALFALSE
widthThe width of the part using the unit of measure specified in dimensionUomDECIMALFALSE
heightThe height of the part using the unit of measure specified in dimensionUomDECIMALFALSE

DimensionWeight Object

FieldDescriptionData TypeRequired
weightUomThe weight unit of measure for the partFACET 2 STRINGTRUE
weightThe weight of the part using the unit of measure specified in dimensionUomDECIMALTRUE

FreightDetails Object

FieldDescriptionData TypeRequired
carrierThe carrier name of the shipping vendor being requested. (i.e. "UPS", "FEDEX", etc.)64 STRINGTRUE
serviceThe service code of the shipping vendor for the service being requested. (i.e. GROUND, 2DAY, NEXTDAY, etc.)64 STRINGTRUE

Item Object

FieldDescriptionData TypeRequired
supplierProductIdThe supplier product Id64 STRINGTRUE
supplierPartIdThe supplier part Id associated to the supplier product Id64 STRINGFALSE
distributorProductIdThe distributor product Id64 STRINGFALSE
distributorPartIdThe distributor part Id associated to the supplier product Id64 STRINGFALSE
purchaseOrderLineNumberThe line number of the item on the purchase orderINTEGERFALSE
QuantityThe quantity of the item shippedOBJECTTRUE

Quantity Object

FieldDescriptionData TypeRequired
valueThe quantity valueDECIMALTRUE
uomThe unit of measure for the valueFACET 2 STRINGTRUE

Guidance

If you are unable to determine the quantity of items shipped by tracking number for a shipment due to process or system limitations, PromoStandards guidance is to attach all products and quantities to a single tracking number and leave the other tracking numbers without products or quantities.

Enumerated Type Restrictions (FACET)

FieldDescriptionData TypeEnumeration Values
dimUOMThe dimensional unit of measureFACET 64 STRINGInches
Feet
mm
cm
Meters
preProductionProofTypeIdentifies if the item is a pre-production proofFACET 64 STRINGYes
No
Unknown
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)ST (Set)SL (Sleeve)TH (Thousand)
serviceMessageSeverityThe severity of the message.FACET 64 STRINGError
Information
Warning
shipmentDestinationTypeThe type of shipment destinationFACET 64 STRINGCommercial
Residential
Other
weightUOMThe weight unit of measureFACET 64 STRINGOunces
Pounds
Grams
KG

Appendix A: Service Messages

ServiceMessage Object

FieldDescriptionData TypeRequired
codeThe numerical value of the codeINTEGERTRUE
descriptionResponse for any message requiring notification to requestor256 STRINGTRUE
severityThe severity of the message. Values are enumerated: {Error, Information, Warning}FACET 64 STRINGTRUE

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
999General Error – Contact the System Service Provider

Service Specific Codes

These error codes are only for this service.

CodeDescription
300queryType not found
301referenceNumber not found
302shipmentDateTimeStamp is incorrect or is an invalid date range

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://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."

Diagrams

getOrderShipmentNotification Function