shipcloud is a shipping service provider that makes it easy for developers to integrate shipping using one of the major carriers on the German market into their own software, onlineshop or ERP solution. We’ve basically built a wrapper around the carriers’ webservices we support so you won’t have to integrate each and every carrier by yourself.
To make it easier for you the developer, we’ve created the shipcloud API deliberately using the RESTful architectural style. This means if you’re familiar with REST and using RESTful services, you will have no problems using our API. As it’s common when implementing a REST-API we’re using resource-oriented URLs and HTTP authentication.
To make it easier for you to start working with the shipcloud api and also to give you a better overview of the features we’re supporting and we’d like you to integrate into your software as well, we wrote a handy integration guide that you can download. In it, aside from what you can find here, we’re also giving you a few pro tips to present your customers with a seamless user experience as well as showing you what we’re calling the core features of the shipcloud api.
For developers to test their code before shipping it, we’re supplying every account with test and live API keys. Every call to our API is secured by an API key. This key is tied specificly to your account and therefore should never be given to anyone else outside of your control. You are able to manage your API keys from your account page.
To use the API key you’ll have to send it with every request being made. We’re using http Basic
Authentication to our API has to be done via HTTP Basic Auth. You’ll have to provide your API key as the basic auth username. You don’t have to provide a password.
Be advised: The API key has to be Base64 encoded.
Aside from sending your API key all API requests must be made using HTTPS. Don’t bother trying to use HTTP. It will fail!
Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:
For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’:
As with every API we will be releasing new versions from time to time. We do promise to adhere to the following API contract:
- No value types or fields will be changed or deleted in the same API version
- What we will change within the same API version:
- add new fields to an object
- add new API endpoints
- required fields can become optional
- endpoints can become deprecated
In case we introduce breaking changes we will adjust the API base path to reflect each new major version. So consecutive releases will be called using /v2/, /v3/ and so on.
from parameters you have to specify a contact for the shipment. This can
either be a
company or a person identified by
although the entries are marked as being optional, one of them has to be specified in the request.
There are some carrier specific things you have to take in mind.
We’ve been giving you the possibility to specifiy a reference number when creating a shipment to make it easier for you to find out, which shipcloud shipment belongs to which order in your shop or system. When creating a shipment you are now able to send us additional data, that we store for you. This so called metadata is a structured object and can be any combination of key-value pairs.
The services of the carriers we’re supporting can be very slow at times. Since we’re not queing requests to create shipping labels at a later point in time, please account for slow response times. We’d suggest setting a timeout of a little more than a minute to be absolutely sure that you’re not missing our responses.
Carrier specific address handling
With the carrier DHL it is possible to send shipments to post offices and PACKSTATION parcel pickup stations.
Post office delivery
To address a post office put the word Postfiliale into the street parameter and the number of the post office into the street_no. You also need to put a DHL customer number into the care_of parameter.
Parcel pickup station (Packstation) delivery
To address one of DHL’s automated parcel pickup stations put the word Packstation into the street parameter and the station number into the street_no. You also need to put the DHL customer number of the recipient into the care_of parameter.
Carrier specific field lengths
Due to the different handling every carrier has for managing addresses, there are different restrictions for submitting data to them. Since we don’t want to restrict you we’re sending the data as is to the specific carriers’ backend and will receive errors in return if something wasn’t correct according to the carrier.
company2 - 30 characters
last_name1 - 30 characters (firstname + last_name < 30 characters)
care_of0 - 30 characters
street1- 40 characters
street_no1 - 5 characters
city1 - 50 characters
phone0 - 20 characters
company1 - 35 characters (only 30 characters will be printed on the label)
last_name1 - 35 characters (only 30 characters will be printed on the label)
care_of0 - 35 characters (only 30 characters will be printed on the label)
street_no1 - 35 characters (only 30 characters will be printed on the label)
zip_code1 - 9 characters
city1 - 30 characters (only 15 characters will be printed on the label)
phone0 - 15 characters
company1 - 27 characters
last_name1 - 22 characters
care_of0 - 35 characters
street_no1 - 73 characters
zip_code1 - 8 characters
city1 - 50 characters
state1 - 50 characters
phone0 - 25 characters
MyDPD Pro / MyDPD Business
company1 - 35 characters
last_name1 - 35 characters
street1 - 35 characters
street_no0 - 8 characters
zip_code1 - 9 characters
city1 - 35 characters
phone0 - 30 characters
Carrier specific label sizes
Each carrier can provide label sizes in a specific DIN format. Here’s an overview of the label sizes that are available and can be configured within your shipcloud account:
|A5 / A6||A5 / A6||A5 / A6||-||A5 / A6|
|A5 / A6||A5||A5||-||A5|
|A5 / A6||-||-||-||-|
|A5 / A6||A5 / A6||-||-||-|
|A5 / A6||A5 / A6||A5 / A6||-||A5 / A6|
|A5 / A6||-||-||-||-|
Carrier specific cutoff times
When requesting shipments to be picked up, each carrier has a specific strategy. Since not every carrier is making clear what their cutoff times are, we can give you the following advices.
When requesting a pickup by UPS, the carrier is validating your request if it’s possible for them to reach you within the requested time period. This validation factors in if there is enough time for the driver to come to you and how far their depot is located from you.
UPS also has a list of cutoff times for postcodes in Germany, you can find within a service pdf which is provided as a download on the UPS website.
If the volume is below 2m3, you can request a pickup for the next day until 9pm the day before. If the volume exceeds this limit you’ll have to request the pickup until 2pm the previous day.
Misc carrier specifics
- when using the service one_day or one_day_early the parameter package.description is mandatory
- shipments will receive a carrier tracking number (
carrier_tracking_no) with the first scan by the carrier, which is why this parameter won’t be included in the response when creating a shipment.
Shipments with Pickup Requests
If you don’t have regular pickups by TNT you will have to request pickups by the carrier. In contrast to other carriers we support, pickup requests for TNT have to be done a little differently. When creating a shipment for TNT a pickup request has to be made at the same time. Therefore you can add a pickup element when creating your shipment request.
The following rules apply for pickups:
- the date for
pickup_time.latesthas to be same
- supplying a
- when using the service returns the parameter package.description is mandatory
- if one of the following conditions is true, the parameter description is mandatory:
- from and to countries are not the same
- from and/or to countries are not in the EU
- from and to countries are in the EU and the shipments service is not standard
We currently support sending packages via the following carriers and services:
shipment services explained:
- standard: A normal shipment without any extra charges for faster delivery or stuff like that
- one_day: A express shipment that will be delivered the next working day
- one_day_early: Same as one_day. The only difference is, that the carrier will deliver the shipment before noon
- same_day: A shipment that will be delivered on the same day it was picked up
- returns: A shipment that the customer sends back to the store / sender
Sandbox vs. Production
When creating an account at shipcloud you get access for 2 systems. A sandbox and a production system. The first one can be used to tinker with (e.g. for developing the integration of shipcloud into your own platform) while the production system is used for the actual creation of shipping labels.
Therefore when you create an account at shipcloud, 2 api keys get generated. A sandbox key that you can use for testing our api and a live key, that can be used to create the actual shipping labels you’re going to put on the packages you’re sending.
If at any time you feel the need to generate a new set of api keys (e.g. because you get the feeling, that your system
has been compromised) you can do that in the shipcloud backoffice by clicking your email address at the upper right
corner and selecting the menu item
We’re currently deleting sandbox shipments 2 weeks after they’ve been created. So it’s best practice to create a new shipment first if you want to test updating or deleting it.
If you feel like tinkering with our api you can always register for free using our developer plan. If you’re satisfied with our service feel free to upgrade to a payed plan. Upgrades from one payed plan to a higher one can be done at any time. We use the balance of your current plan against the first month of your new one, so you won’t be billed extra for upgrading before your current plan runs out.
Prices & Vat
All of our prices are displayed in Euro and without VAT. We will however charge you with the full German value added tax which is 19% at the moment.
If you automatically want to react to events happening within the shipcloud system, webhooks are the right thing for you. All you need to do is provide us with a URL we should call once something happens. You can also specify which events should trigger calling your URL. Maybe you only want to be notified, when a package gets delivered to one of your customers.
When an event is triggered, we’ll send an HTTP POST request to your URL, containing a JSON payload, with all the information necessary. Here’s our sample payload you get when testing a webhook through our website:
Notice: Our payload only contains the data that was mentioned above. This means that after a webhook was fired, you will have to call our api to get detailed information about the shipment. This way only someone with the correct api key is able to access your customers data.
You can currently subscribe to the following event types:
|shipment.tracking.label_created||A label has been created|
|shipment.tracking.picked_up||Shipment was picked up by carrier|
|shipment.tracking.transit||Shipment is in transit|
|shipment.tracking.out_for_delivery||Out for delivery|
|shipment.tracking.awaits_pickup_by_receiver||Awaiting pickup by the receiver|
|shipment.tracking.canceled||label has been deleted|
|shipment.tracking.delayed||Delivery will be delayed|
|shipment.tracking.exception||There's a problem with the shipment|
|shipment.tracking.destroyed||Destroyed by customs or other higher authorities.|
|shipment.tracking.notification||Carrier internal notification. Tracking events within the shipment will carry more elaborate information.|
To configure webhooks just click on Configurations in the shipcloud backoffice to reveal a webhook nav entry. There you can add webhooks and specify which events should trigger sending a message to your URL.
There are a lot of tools out there for testing webhooks. If you’d like a starting point check out this blogpost called 60+ Tools and Services for API and Webhook Logging, Debugging, Testing, Monitoring, Documentation and Discovery. We’d recommend using a service like requestb.in or mocky.io to have reliable responses for your tests. This way you don’t have to create shipments just for testing handling shipments afterwards.
If you’re usind TDD (test driven development) another thing we’d recommend is creating a second account at shipcloud for all your testing needs. This way you can separate further development on your platform from your live processes.
If the URL you provided when configuring the webhook can’t be reached, we’ll try to contact it a few minutes later. After 10 failed attempts to send you the data, we’re giving up and the webhook will be deactivated automatically. You can reactivate it in shipcloud once your system is up and reachable again.