Jamie Thompson edited this page Jun 26, 2018 · 17 revisions

Despatch Bay SOAP API v14

Important: Please note that version 14 has been superseded by version 15. This documentation is provided for the benefit of existing users of the v14 API. If you are building a new integration please consult the v15 API documentation

To access and manage your Despatch Bay (www.despatchbay.com) account using the Despatch Bay API, you build a client application that connects to one or more of the provided web services. While each service can be used independently, most real-world scenarios require that a client application uses multiple services.

The core messaging technology for the Despatch Bay API is SOAP, which is an XML and HTTP-based protocol supported by most programming languages and frameworks.


The web services are secured by means of HTTP Basic Authentication.

Within the Despatch Bay API settings control panel (despatchbay.com/account/api-integration) it is possible to generate one or more sets of API credentials. A single set of API credentials consists of two tokens, an apiuser and an apikey. These tokens must be used as the values of login and password respectively when authenticating against the API.

Example using the native PHP SoapClient

$apiuser = 'YOUR_API_USER';
$apikey = 'YOUR_API_KEY';
$soapUrl = "https://api.despatchbay.com/soap/v14/shipping?wsdl";
$soapOptions = array ('login' => $apiuser,'password' => $apikey);
$client = new SoapClient($soapUrl, $soapOptions);

For more details on how to use HTTP Basic Authentication you should consult the documentation for your chosen SOAP client.

Rate Limiting

To ensure quality of service for all customers we have implemented a system of rate limiting within each of the services. Each service has a rate limiting window and a corresponding maximum number of requests.

None of the services currently support returning rate limiting headers so your application will need to monitor it's own usage in order to prevent running into rate limits. When a rate limit is exceeded, the service will return HTTP/1.1 429 Too Many Requests

Rate Limits

Service Window Max Requests
Account 1 hour 60
Addressing 1 min 2
Shipping 1 min 60
Tracking 1 min 10

Note: If you would like to discuss increased rate limits with us, please get in touch. We will assess requests for increased limits on a case by case basis.

DateTime Format and Time Zone

Despatch Bay uses the ISO 8601 combined format for dateTime stamps being submitted to and returned from the API. Please be sure to submit all dateTime values as yyyy-mm-dd hh:mm:ss (24 hour notation). Example - 2016-11-29 23:59:59

The time zone represented in all API responses is Europe/London. We ask that you make any time zone conversions before submitting DateTime data to the Despatch Bay API.


You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.