> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dekhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# getOrderShipmentNotification

> Returns shipments for your orders, with ship-from and ship-to addresses and package tracking: by purchase order number, by sales order number, or shipped since a time.

Returns shipments for your orders, with ship-from and ship-to addresses and package tracking: by purchase order number, by sales order number, or shipped since a time.

## Endpoint

`POST https://partners.dekhq.com/api/promostandards/order-shipment-notification`

* **WSDL:** [`https://partners.dekhq.com/api/promostandards/order-shipment-notification?wsdl`](https://partners.dekhq.com/api/promostandards/order-shipment-notification?wsdl). The schemas it imports are served beside it.
* **Service:** PromoStandards Order Shipment Notification 1.0.0, SOAP 1.1 (document/literal)
* **Namespace:** `http://www.promostandards.org/WSDL/OrderShipmentNotificationService/1.0.0/`
* **Request headers:** `Content-Type: text/xml; charset=utf-8`. `SOAPAction: "getOrderShipmentNotification"` is accepted but not required; DEKHQ picks the operation from the body element.
* **Responses:** `text/xml; charset=utf-8`, HTTP 200 on success.

## Authentication

Send the `id` and `password` DEKHQ issued you in the request body. Your credential must be enabled for the `osn` scope. Each credential is limited to 300 requests per minute; above that you get a rate-limit fault with a `Retry-After` header.

## How DEKHQ handles it

* Only orders for the clients your credential is linked to are returned.
* At most 5,000 orders per response. There is no paging in OSN 1.0.0, so poll with queryType 3 for new shipments.

## Request fields

Element `GetOrderShipmentNotificationRequest`.

| Field | Type | Required | Description |
| - | - | - | - |
| `wsVersion` | string (max 64 chars) | Yes | The Standard Version of the Web Service being referenced **DEKHQ:** Accepted; DEKHQ does not check it. Send `1.0.0`. |
| `id` | string (max 64 chars) | Yes | The customer Id or any other agreed upon Id. |
| `password` | string (max 64 chars) | No | The password associated with the Id |
| `queryType` | integer (one of `1`, `2`, `3`, `4`) | Yes | The type of query you wish to perform. **DEKHQ:** DEKHQ supports 1 (PO number), 2 (sales order number) and 3 (shipped since `shipmentDateTimeStamp`). 4 is not supported and returns an empty array. |
| `referenceNumber` | string (max 64 chars) | No | The purchase order or sales order number. Required when the queryType is 1 or 2. **DEKHQ:** Required for queryType 1 and 2. |
| `shipmentDateTimeStamp` | dateTime | No | The earliest date for of shipments to return in UTC. Required when the queryType is 3. ISO 8601 **DEKHQ:** Required for queryType 3. |

## Response fields

Element `GetOrderShipmentNotificationResponse`.

| Field | Type | Required | Description |
| - | - | - | - |
| `OrderShipmentNotificationArray` | object | No | An Array of order shipment notifications |
| ↳ `OrderShipmentNotification` | object\[] | Yes | |
| ↳ ↳ `purchaseOrderNumber` | string | Yes | The associated purchase order. |
| ↳ ↳ `complete` | boolean | Yes | All shipments for this purchase order are complete. |
| ↳ ↳ `SalesOrderArray` | object | No | An Array of sales orders |
| ↳ ↳ ↳ `SalesOrder` | object\[] | Yes | |
| ↳ ↳ ↳ ↳ `salesOrderNumber` | string (max 64 chars) | Yes | The associated sales order. |
| ↳ ↳ ↳ ↳ `complete` | boolean | Yes | All shipments for this sales order are complete. |
| ↳ ↳ ↳ ↳ `ShipmentLocationArray` | object | Yes | An array of shipment locations. |
| ↳ ↳ ↳ ↳ ↳ `ShipmentLocation` | object\[] | Yes | |
| ↳ ↳ ↳ ↳ ↳ ↳ `id` | integer | No | The id of the location. |
| ↳ ↳ ↳ ↳ ↳ ↳ `complete` | boolean | Yes | All shipments for this location are complete. |
| ↳ ↳ ↳ ↳ ↳ ↳ `ShipFromAddress` | object | Yes | |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `address1` | string (max 64 chars) | Yes | Ship address Line 1. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `address2` | string (max 64 chars) | No | Ship address Line 2. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `address3` | string (max 64 chars) | No | Ship address Line 3. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `address4` | string (max 64 chars) | No | Ship address Line 4. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `city` | string (max 64 chars) | Yes | Ship address city. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `region` | string (max 2 chars) | Yes | Ship address region. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `postalCode` | string (max 10 chars) | Yes | Ship address postal code. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `country` | string (max 128 chars) | No | Ship address country. |
| ↳ ↳ ↳ ↳ ↳ ↳ `ShipToAddress` | object | Yes | |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `address1` | string (max 64 chars) | Yes | Ship address Line 1. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `address2` | string (max 64 chars) | No | Ship address Line 2. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `address3` | string (max 64 chars) | No | Ship address Line 3. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `address4` | string (max 64 chars) | No | Ship address Line 4. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `city` | string (max 64 chars) | Yes | Ship address city. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `region` | string (max 2 chars) | Yes | Ship address region. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `postalCode` | string (max 10 chars) | Yes | Ship address postal code. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `country` | string (max 128 chars) | No | Ship address country. |
| ↳ ↳ ↳ ↳ ↳ ↳ `shipmentDestinationType` | string (one of `Commercial`, `Residential`, `None`) | No | Used to identify the type of destination for the Ship-To address. |
| ↳ ↳ ↳ ↳ ↳ ↳ `PackageArray` | object | No | An array of shipment packages. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ `Package` | object\[] | Yes | |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `id` | integer | No | The id of the package. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `trackingNumber` | string (max 128 chars) | Yes | The tracking number for the package. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `shipmentDate` | dateTime | Yes | The date for the shipment in UTC. ISO 8601 |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `dimUOM` | string (one of `Inches`, `Feet`, `mm`, `cm`, `Meters`) | No | The dimensional unit of measure. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `length` | decimal | No | The length of the package. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `width` | decimal | No | The width of the package. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `height` | decimal | No | The height of the package. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `weightUOM` | string (one of `Ounces`, `Pounds`, `Grams`, `KG`) | No | The dimensional unit of measure. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `weight` | decimal | No | The weight of the package. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `carrier` | string | No | The carrier delivering the package |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `shipmentMethod` | string (max 128 chars) | No | The method used for shipping (Ground). |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `shippingAccount` | string (max 128 chars) | No | The shipping account used for this shipment. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `shipmentTerms` | string (max 128 chars) | No | The terms of the shipment. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `ItemArray` | object | No | A list of items and quantities contained in the package. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `Item` | object\[] | Yes | |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `supplierProductId` | string (max 64 chars) | No | The supplier product Id |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `supplierPartId` | string (max 64 chars) | No | The supplier part Id associated to the supplier product Id |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `distributorProductId` | string (max 64 chars) | No | The distributor product Id |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `distributorPartId` | string (max 64 chars) | No | The distributor part Id associated to the supplier product Id |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `purchaseOrderLineNumber` | string (max 64 chars) | No | The line number of the item on the purchase order. |
| ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ ↳ `quantity` | decimal | No | The length of the package. |
| `errorMessage` | object | No | Response for any error requiring notification to requestor **DEKHQ:** Not used. DEKHQ reports errors as SOAP faults (see Errors). |
| ↳ `code` | int | Yes | Response for any error requiring notification to requestor |
| ↳ `description` | string (max 256 chars) | Yes | Response for any error requiring notification to requestor |

## Errors

Errors come back as SOAP 1.1 faults. The schema's `errorMessage` element is not used.

| faultcode | faultstring | HTTP status | When |
| - | - | - | - |
| `soap:Client` | Malformed SOAP request | 500 | The body is not a SOAP envelope with an operation element. |
| `soap:Client` | Invalid id or password | 500 | The `id`/`password` pair is unknown or inactive. |
| `soap:Client` | Credential not permitted for scope: osn | 500 | Your credential is not enabled for this service. |
| `soap:Client` | Unsupported operation: \<operation> | 500 | The operation is not one this endpoint serves. |
| `soap:Server` | Rate limit exceeded — retry later | 429 | More than the allowed requests per minute. Wait for the `Retry-After` header (seconds). |
| `soap:Server` | Internal error | 500 | An unexpected error on our side. It is logged; retry later. |

## Example

Sample data is fictional.

<CodeGroup>
  ```xml Request theme={null}
  <?xml version="1.0" encoding="UTF-8"?>
  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
      <ns:GetOrderShipmentNotificationRequest xmlns:ns="http://www.promostandards.org/WSDL/OrderShipmentNotificationService/1.0.0/" xmlns:shar="http://www.promostandards.org/WSDL/OrderShipmentNotificationService/1.0.0/SharedObjects/">
        <shar:wsVersion>1.0.0</shar:wsVersion>
        <shar:id>example-partner</shar:id>
        <shar:password>example-password</shar:password>
        <ns:queryType>1</ns:queryType>
        <ns:referenceNumber>PO-10042</ns:referenceNumber>
      </ns:GetOrderShipmentNotificationRequest>
    </soap:Body>
  </soap:Envelope>
  ```

  ```xml Response theme={null}
  <?xml version="1.0" encoding="UTF-8"?>
  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
      <ns:GetOrderShipmentNotificationResponse xmlns:ns="http://www.promostandards.org/WSDL/OrderShipmentNotificationService/1.0.0/" xmlns:shar="http://www.promostandards.org/WSDL/OrderShipmentNotificationService/1.0.0/SharedObjects/">
        <ns:OrderShipmentNotificationArray>
          <ns:OrderShipmentNotification>
            <ns:purchaseOrderNumber>PO-10042</ns:purchaseOrderNumber>
            <ns:complete>true</ns:complete>
            <ns:SalesOrderArray>
              <ns:SalesOrder>
                <ns:salesOrderNumber>SO-58817</ns:salesOrderNumber>
                <ns:complete>true</ns:complete>
                <ns:ShipmentLocationArray>
                  <ns:ShipmentLocation>
                    <ns:id>1</ns:id>
                    <ns:complete>true</ns:complete>
                    <ns:ShipFromAddress>
                      <shar:address1>100 Example Ave</shar:address1>
                      <shar:city>Springfield</shar:city>
                      <shar:region>IL</shar:region>
                      <shar:postalCode>62701</shar:postalCode>
                      <shar:country>US</shar:country>
                    </ns:ShipFromAddress>
                    <ns:ShipToAddress>
                      <shar:address1>200 Sample St</shar:address1>
                      <shar:address2>Suite 300</shar:address2>
                      <shar:city>Riverton</shar:city>
                      <shar:region>WY</shar:region>
                      <shar:postalCode>82501</shar:postalCode>
                      <shar:country>US</shar:country>
                    </ns:ShipToAddress>
                    <ns:PackageArray>
                      <ns:Package>
                        <ns:trackingNumber>1Z999AA10123456784</ns:trackingNumber>
                        <ns:shipmentDate>2026-02-12T18:00:00Z</ns:shipmentDate>
                        <ns:weightUOM>Pounds</ns:weightUOM>
                        <ns:weight>12.5</ns:weight>
                        <ns:carrier>UPS</ns:carrier>
                        <ns:shipmentMethod>Ground</ns:shipmentMethod>
                      </ns:Package>
                    </ns:PackageArray>
                  </ns:ShipmentLocation>
                </ns:ShipmentLocationArray>
              </ns:SalesOrder>
            </ns:SalesOrderArray>
          </ns:OrderShipmentNotification>
        </ns:OrderShipmentNotificationArray>
      </ns:GetOrderShipmentNotificationResponse>
    </soap:Body>
  </soap:Envelope>
  ```

  ```xml Fault theme={null}
  <?xml version="1.0" encoding="UTF-8"?>
  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
      <soap:Fault>
        <faultcode>soap:Client</faultcode>
        <faultstring>Invalid id or password</faultstring>
      </soap:Fault>
    </soap:Body>
  </soap:Envelope>
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.