Order Shipment Notification
Summary: 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.
Supplier Best Practices
Provide OSN data as close to real-time as possible
Adhere to service-specific and PromoStandards enumerated error codes/messages
Use error code 999 for specific messages that don’t fall under the standard codes listed in the specification.
Get Order Shipment Notification Request
Field | Description | Required? | Best Practice |
wsVersion | The Standard Version of the Web Service being referenced. | TRUE | |
id | The customerID or any other agreed upon ID. | TRUE | |
password | The password associated with the customerID or agreed upon ID. | FALSE | |
queryType | The type of query you wish to perform.1 | TRUE | It’s best to use queryType 1 or 2 when possible. Querying by date (queryType 3) can result in long response times. |
referenceNumber | The purchase order or sales order number. Required when the queryType is 1 or 2.2 | FALSE | |
shipmentDateTimeStamp | The earliest date for of shipments to return in UTC 3. Required when the queryType is 3. ISO 8601 | FALSE | When using queryType 3, it’s best to consider your order volume, as it could result in large data sets being returned. Some suppliers don’t update shipments until EOD. It’s best to call today and yesterday. Review supplier integration guide for their best practices. |
Get Order Shipment Notification Response
Field | Description | Required? | Best Practice |
OrderShipmentNotificationArray10 | An array of Order Shipment Notifications | FALSE | |
ErrorMessage999 | Response for any error requiring notification to requestor | FALSE | Suppliers should use code 302 for no orders by referenceNumber |
Order Shipment Notification Array
Field | Description | Required | Best Practice |
purchaseOrderNumber | The associated purchase order. | TRUE | |
complete | All shipments for this purchase order are complete. | TRUE | |
SalesOrderArray | An array of sales orders associated with the purchase order. 4 | FALSE |
Sales Order
Field | Description | Required | Best Practice |
salesOrderNumber | The associated sales order. | TRUE | |
complete | All shipments for this sales order are complete. | TRUE | |
ShipmentLocationArray | An array of shipment locations. 5 | TRUE |
Shipment Location
Field | Description | Required | Best Practice |
id | The id of the location. | FALSE | |
complete | All shipments for this location are complete. | TRUE | |
shipFromAddress | Ship-From address 6 | TRUE | |
shipToAddress | Ship-To address 6 | TRUE | |
shipmentDestinationType | Used to identify the type of destination for the Ship-To address. | FALSE | |
PackageArray | An array of shipment packages. 7 | FALSE | Provide as much information as possible such as dimensions, dimension UoM, weight, items. |
Address
Field | Description | Required | Best Practice |
address1 | Address Line 1 | TRUE | |
address2 | Address Line 2 | FALSE | |
address3 | Address Line 3 | FALSE | |
address4 | Address Line 4 | FALSE | |
city | Address City | TRUE | |
region | Address Region | TRUE | |
postalCode | Address Postal Code | TRUE | |
country | Address Country | FALSE | Recommendation is to use ISO 3166 country codes. |
Package
Best practice is to list all items associated with each tracking number. 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.
Field | Description | Required | Best Practice |
id | The id of the package | FALSE | |
trackingNumber | The tracking number for the package | TRUE | |
shipmentDate | The date for the shipment in UTC. 8 ISO 8601 | TRUE | |
dimUOM | The dimensional unit of measure | FALSE | |
length | The length of the package | FALSE | |
width | The width of the package | FALSE | |
height | The height of the package | FALSE | |
weightUOM | The weight unit of measure | FALSE | |
weight | The weight of the package | FALSE | |
carrier | The carrier delivering the package | FALSE | |
shipmentMethod | The method used for shipping (Ground) | FALSE | |
shippingAccount | The shipping account used for this shipment | FALSE | |
shipmentTerms | The terms of the shipment | FALSE | |
ItemArray | A list of items and quantities contained in the package 9 | FALSE | ** (See below) It is recommended that the supplier provide as many item details as possible. |
Item
Field | Description | Required | Best Practice |
supplierProductId | The supplier product Id | FALSE | |
supplierPartId | The supplier part Id associated to the supplier product Id | FALSE | |
distributorProductId | The distributor product Id | FALSE | |
distributorPartId | The distributor part Id associated to the supplier product Id | FALSE | |
purchaseOrderLineNumber | The line number of the item on the purchase order. | FALSE | |
quantity | The quantity of the item. | FALSE |
...
Quantity refers to the number of items in the package, not the quantity ordered. |