- Creating shipment and quick bookings in transport management systems
- Business customers of DHL Global Forwarding
- Air, Ocean, Rail, and Road Freight shipments
Shipment Booking API allows developer to book Air Freight and Ocean Freight shipments in various DHL Global Forwarding transport management systems.
The API accepts the following shipment information:
- Goods Lines & Packages
- Notes & References
The API returns a unique DGF Booking ID which you can use to check on the status of the booking. We recommend to check the status of the booking at 5 minutes interval. Once shipment is created, you will receive additional information about the shipment e.g. Housebill Number and Shipment ID.
|Booking data is validated and accepted by the API. Next status is "In-progress".
|Shipment is being processing in system. Next status is "Shipment Created" or "Shipment could not be created"
Shipment is created successfully. Use the housebill number to track the movement of your shipment using Shipment Tracking API.
New feature: If you are subscribed to Timestamp Notification Push API, DHL will automatically notify your API about the latest status of your shipments.
|Shipment could not be created
|Unfortunately shipment could not be created due to data or unexpected issues. Please contact email@example.com for support.
Once your request is approved, you are automatically granted access to Timestamp Notification Push API. The API will automatically push notifications about the status of your shipments to your API endpoint. It helps you to keep track of the shipments you created using the Shipment Booking API.
For more information on the Timestamp Notification API, visit https://developer.dhl.com/api-reference/dgf-push-api#get-started-section/overview
Shipment Booking Update
Developers are also able to update their shipment booking with DHL Global Forwarding. Business rule validation applies.
The table below details the timeframe on when a shipment booking update is allowed:(e.g. Updating Notes of a sea shipment, Z42 timestamp should not be populated.)
|Update Mode 1
|Manual via Note (Priority)
|Manual via Note (Alternate)
|Warehouse Upd Received
1 Update Mode
- Automatic = Data from the API is automatically updated into the TMS
- Manual via Note = Data from API is sent as a note, which serves as the Operator's guide for manually applying updates in the TMS
- For SEA/RAI, alternate mapping of the Consignee Account via Note will take effect if IRP is populated and Z42 is not populated
- IRP = Arrival at Origin Terminal
- Z42 = Shipping Instructions sent to Carrier
- WHS Upd Received= Pack Updates Received from Warehouse
- Notes Type is unique and can only be used once within the message.
The API provides access to create shipment bookings in various transport management systems at DHL Global Forwarding.
Using the API
You must have an eligible shipper / consignee account number (DHL Global Forwarding accounts) and a valid oAuth2 access token to use the API.
Once access to the API is requested, please send us an email at firstname.lastname@example.org describing your use case and tell us the name/email address of your DHL contact person. We will verify your identity before granting the access.
For additional information, please contact email@example.com
You must request credentials for any applications you develop
To register your app and get your API subscription keys:
- Click My Apps on the portal website.
- Click the + Add App button to create a new app
The “Add App” form appears.
- If you wish to add the API to an existing App, click on App's "Edit" button
- Fill in the form
Select "Shipment Booking (DHL Global Forwarding) - Environment: Sandbox - Rate Limit: Standard" from the API drop down list
- When you have completed the form, click the Add App button or Save button
- Please email firstname.lastname@example.org for API request approval
Shipment Booking API uses oAuth 2.0 protocol to authenticate and authorize access to API consumers. For implementation details, please see Swagger specification on the "Reference Docs" tab.
To view your API credentials :
- From the My Apps screen, click on the name of your app.
The Details screen appears.
- If you have access to more than one API, click the name of the relevant API.
Note: The APIs are listed under the “Credentials” section.
- Click the Show link below the asterisks that is hiding the Consumer Key.
The Consumer Key appears.
The addressable API base URL/URI environments are:
Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.
The table below details the main request limits:
|Maximum calls per minute
|Maximum calls per day
|400 per minute
Please contact email@example.com if you need a different service level.
When the limit is reached, you will receive an HTTP Status code:
429: Too many requests.
Specifics for the use of Shipment Booking (DHL Global Forwarding) API
- The API Productive Key for the Shipment Booking (DHL Global Forwarding) API is a private and individual key for you and your DGF customer account only, i.e. it shall not be used by or for other DGF (transportation) customers. You may not allow your developer or IT services provider to use your API Productive Key for potential other DGF (transportation) customers.
- For the avoidance of doubt, when data has been sent or received outside of DGF’s business hours, the processing of data and/or execution of the (transportation) services will start according to the terms and conditions set out in the applicable Agreement or, absent thereof, as soon as reasonably practicable. Unless otherwise expressly agreed upon in writing (e.g. in the Agreement), the transmission of a set of data via the Shipment Booking (DHL Global Forwarding) API by you shall be deemed a proposal to enter into an individual (transportation or other) contract and has to be acknowledged/accepted by the receiving DGF entity before a contract with regards to e.g. the transport is effected. The parties expressly waive any rights to contest the validity of an individual (transportation or other) contract effected by the use of the Shipment Booking (DHL Global Forwarding) API in accordance with these API Legal Terms on the sole ground that it was effected via API. DGF may determine which of the offered data fields need to be filled by you, to use the Shipment Booking (DHL Global Forwarding) API properly. You are responsible for the correctness and completeness of the data provided. DGF reserve the right to transform, adapt and/or amend data provided by you to process such data accordingly. It is in your responsibility to review and check the booking confirmation received by DGF in order to make sure that the data provided by you (e.g. number of containers) has been adopted correctly.
- Neither DGF nor any other affiliate within DP DHL, is responsible for storing a record of any data (API-call or -request data or the actual contents of the data sets), that has been exchanged via the Shipment Booking (DHL Global Forwarding) API, unless expressly agreed upon in writing (e.g. in the Agreement).
- You shall use the services and/or data that you receive via the Shipment Booking (DHL Global Forwarding) API only for the legitimate business purposes, only in connection with DGF’s transportation and/or other services, and in compliance with all applicable laws and regulations, including but not limited to, laws regarding the use of personal data.
- Please note, that we provide free text boxes (e.g. for customer references) to improve the functionalities and user experience of the Shipment Booking (DHL Global Forwarding) API. We explicitly ask you to refrain from sending any personal or business critical data and/or information as free text. It is within your sole responsibility to ensure that the data or information you send does not infringe upon applicable law, esp. data protection law, and that you are entitled to use the respective data and/or information accordingly.
- You acknowledge that material and information you may acquire, including (but not limited to) transportation methods, booking information, financial or other accounting information and other procedures and processes relating to the Shipment Booking (DHL Global Forwarding) API and the API Service (“Materials”) are proprietary, confidential, and owned by DGF. Other than described herein, you shall have no additional rights to the Materials.
- Added externalBookingID (Live: 13.02.2024)
- Added customsClassification under goodsLines (in testing)
- Added shipmentBranchCode to the shipment update API (Live: 13.02.2024)
- Shipment Booking Update: Only consignee account number can be updated and this will reflect to the Notes section.
- Added productCode
- New ProductCode codelist
- Added shipmentSubType
- New shipmentSubType codelist
- Added goodsLines.originCountryCode
- Added innerPackageType
- Handling of min/max temperature only if temperature control is set to true.
- Customer group is referring to Controlling Customer - description updated
- transportUnitID and transportUnitType under goodsLines are for future use - description updated
- Updated assembly description.
- Added shipmentBranchCode field.
- Increased the max length of serviceCode from 3 to 4.
- Added Timestamp Notification API
- You are automatically granted access to subscribe to Timestamp Notification Push API, DHL will automatically notify your API about the latest status of your shipments
- added _DGFInsure
- added Delivery Transport Company (DeliveryLocalCartage) to partyType enum
- Added parties, goodsLine.hazardousMaterial and goodsLine.temperatures groups.
- New PartyType, GoodsTemperatureUoM, and FlashpointTemperatureUoM codelist.
- Added transport mode of Rail.
- Added TID (Template ID) to ReferenceType codelist.
- Added assembly field for quick bookings.
- New PartyType, GoodsTemperatureUoM, and FlashpointTemperatureUoM codelist.
- Initial release