When talking to our API you can receive the following status codes:
Code
Name
Description
200
ok
Everything went fine.
204
no content
There is no message body. You'll get this code when
deleting a shipment
was successful.
400
bad request
Your request was not correct. Please see the response body for more detailed information.
401
Unauthorized
You didn't authorize with our api. Probably because you forgot to send your api key for
authorizing at our api.
402
payment required
You've reached the maximum of your current plan. Please upgrade to a higher plan.
403
forbidden
You are not allowed to talk to this endpoint. This can either be due to a wrong
authentication or when you're trying to reach an endpoint that your account isn't
allowed to access.
404
not found
The api endpoint you were trying to reach can't be found.
422
unprocessable entity
Your request was well-formed but couldn't be followed due to semantic errors. Please see the response body
for more detailed information.
500
internal server error
Something has seriously gone wrong. Don't worry, we'll have a look at it.
502
bad gateway
Something has gone wrong while talking to the carrier backend. Please see the response body for more
detailed information.
504
gateway timeout
Unfortunately we couldn't connect to the carrier backend. It is either very slow or not reachable at all.
If you want to stay informed about the carrier status, follow our developer twitter account at
@shipcloud_devs.
Addresses
The following is a section of resources related to addresses.
first_name (string, optional), the receivers first name
last_name (string), the receivers last name
care_of (string, optional), name of the person that should be able to receive
the package
street (string), street name
street_no (string), house number
zip_code (string), zip code
city (string), city
state (string, optional), state
country (string), country as uppercase ISO 3166-1 alpha-2 code
phone (string, optional), telephone number (mandatory when using UPS and the
following terms apply: service is one_day or one_day_early or ship to country is different than
ship from country)
email (string, optional), Corresponding email address. Some carrier will need
this to be provided (e.g. to notify the sender/receiver).
drop_off_point_id (string, optional), ID of the drop off point where the shipment should be send to. The ID can be determined through the [GLS parcelshop search](https://gls-group.eu/DE/en/depot-parcelshop-search)
type (string, optional), drop off point type
Creating an address
If you want to create an Address, this is the way to go!
We only return services, package_types,
additional services and label_formats that are available for the
user who is making the request. For a list of all supported entries, see our
JSON schema.
By creating orders you can send shipcloud your order data with details about what your
customer has ordered. After creating an order, you can create an association between
shipments and orders by providing the order_id upon creating a shipment.
This is especially useful if you want to use our
Return Portal
Plus where the customer can tell you, which items they are going to return.
There are two ways you can request shipments to be picked up by a specific carrier. By simply
stating that all shipments that haven't been picked up already should be picked up or by specifying
which shipments should by picked up.
Notice:
If you don't supply a pickup_address in your request, we're using the default from
address that's being defined in the shipcloud profile for requesting a pickup by the
carrier. Please keep in mind there are
carrier specific field lengths you have to
take into account.
carrier (string), the carrier you want to use. Possible values are "dpd",
"hermes", "ups".
pickup_time (object), contains the earliest and latest pickup time in iso8601.
earliest (datetime), the date the shipments are ready for pickup.
latest (datetime), the latest date for pick up.
pickup_address (object, optional), address where the carrier should pick up
shipments. See address request for a
detailed definition.
shipments (array of shipment objects, optional), if you want only certain
shipments to get picked up, you can send the specific shipment objects with the request. Please
keep in mind that return shipments can't be picked up.
Deprecated Parameters:
pickup_date (string), pickup date (e.g. 2014/02/12). Please use
pickup_time instead.
Here's an example for having all shipments being picked up by a specific carrier:
Notice:
Some carriers (e.g. Hermes) are using the address that's being defined at
the carrier account for picking up shipments. In those cases we'll return
null as pickup_address.
carrier (string, optional), the carrier you want to use. Possible values are
angel_de, cargo_international, dhl, dhl_express, dpag, dpd, gls, go, hermes, iloxx, parcel_one, ups
carrier* (string), the carrier you want to use. Possible values are
angel_de, cargo_international, dhl, dhl_express, dpag, dpd, gls, go, hermes, iloxx, parcel_one, ups
to* (object), describes the receivers address. See
address request
for a detailed definition.
from* (object), describes the senders address. If missing, the default sender
address (if defined in your shipcloud account) will be used. See
address request
for a detailed definition.
cover_address (object, optional), this overwrites the sender address on the
shipping label. See
cover address
for details.
package*, object describing the package dimensions
width (float), width of the package in cm
length (float), length of the package in cm
height (float), height of the package in cm
weight (float), weight in kg
declared_value, object describing the value of the package contents. Use
this to book additional insurance or expand the liability for a shipment. Caution: Please
keep in mind that additional fees are charged by the carrier.
amount (float), value of package contents
currency (string), currency as uppercase ISO 4217 code
description (string), if you're using UPS with service returns
this is mandatory otherwise it's optional
type (string, optional), carrier specific package type declaration.
Available values are books, bulk, letter,
parcel and parcel_letter.
service (string, optional), service that should be used. Available values are
standard, one_day, one_day_early, returns, cargo_international_express, dhl_europaket, dhl_prio, dhl_warenpost, dpag_warenpost, dpag_warenpost_signature, dpag_warenpost_untracked, gls_express_0800, gls_express_0900, gls_express_1000, gls_express_1200, ups_express_1200
additional_services (array, optional), array of objects where you can define
additional services to be used.
pickup (object, optional), describes the pickup request.
pickup_time (object), contains the earliest and latest pickup time in
iso8601
earliest (datetime), timestamp describing the earliest time the carrier
should pickup the shipment
latest (datetime), timestamp describing the latest time the carrier should
pickup the shipment
pickup_address (object, optional), describes the pickup address. See
address request
for a detailed definition.
customs_declaration (object, optional), customs declaration information
contents_type (string), type of shipment contents. Possible values are
commercial_goods, commercial_sample, documents,
gift, returned_goods
contents_explanation (string, optional), description of contents. Mandatory
if contents_type is commercial_goods. Max 256 characters, when using DHL as
your carrier
currency (string), currency as uppercase ISO 4217 code
additional_fees (float, optional), additional custom fees to be payed
drop_off_location (string, optional), location where the package will be
dropped of with the carrier
exporter_reference (string, optional), a note for the exporter
importer_reference (string, optional), a note for the importer
movement_reference_number (string, optional), the movement reference number (MRN)
posting_date (string, optional), date of commital at carrier
invoice_number (string, optional), invoice number for the order
total_value_amount (float, optional), the overall value of the shipments'
contents. Has to be between 0 and 1000
items (array), array of objects describing the items included in the
shipments
origin_country (string), country as uppercase ISO 3166-1 alpha-2 code
description (string), a description of this item
hs_tariff_number (integer, optional), customs tariff number. See
wikipedia
for detailed information on region specific tariff numbers
quantity (integer), Number that defines how many items of this kind are
in the shipment
value_amount (float), Value of a single item of this kind
net_weight (float), Net weight of a single item of this kind
gross_weight (float), Gross weight of a single item of this kind
reference_number (string, optional), a reference number (max. 30 characters)
that you want this shipment to be identified with. You can use this afterwards to easier find
the shipment in the shipcloud.io backoffice
description (string), mandatory if you're using UPS and the following
conditions are true: 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
label (object, optional), specify label specific things
format (string), the format you want the label to have. See
label format
for detailed information
label_voucher (object, optional), label voucher specific definitions
format (string), file format the label voucher should be in
type (string), the type of label voucher that should be returned
notification_email (string, optional), email address that we should notify once
there's an update for this shipment. notice: since Amazon
doesn't allow a direct communication with buyers, all Amazon email addresses are excluded from
receiving our notification emails
create_shipping_label (boolean), determines if a shipping label should be
created at the carrier (this means you will be charged when using the production api key)
Creating a shipment
If you want to create a shipment, this is the way to go!
carrier_tracking_no, e.g. 'carrier_tracking_no=43128000105'
created_at_gt, e.g. 'created_at_gt=20180712T1300Z'
created_at_lt, e.g. 'created_at_lt=20180712T1400Z'
page, show page number x, e.g. 'page=2'
per_page, show x number of shipments on a page (default & max: 100), e.g.
'per_page=25'
reference_number, e.g. 'reference_number=ref123456'
service, e.g. 'service=returns'
shipcloud_tracking_no, e.g.
'shipcloud_tracking_no=86afb143f9c9c0cfd4eb7a7c26a5c616585a6271'
shipment_type, e.g. 'shipment_type=prepared'
source, e.g. 'source=api'
tracking_status, e.g. 'tracking_status=out_for_delivery'
tracking_status_not, e.g. 'tracking_status_not=delivered'
shipment_type: Specifies the type of a shipment. The following types are available:
prepared: a shipment which was saved in shipcloud but doesn't have a shipping
label yet
label_created: a shipment containing a shipping label.
tracking_only: a shipment that was imported via its carrier tracking number (see
trackers
for more details)
created_at_gt / created_at_lt: You can filter the list by using these parameters
to specify a timerange to find the shipments that were created during this time. The timestamp
will be evaluated as ISO 8601 using the following format: YYYYMMDDThhmmZ.
source: Filter shipments by platform they were created through. The following
keys can be used:
api: a shipment created through our api
webui: a shipment created using the shipcloud ui
return_portal: a shipment created using the shipcloud return portal
Response
200 (OK)
{"shipments":[{"id":"86afb143f9c9c0cfd4eb7a7c26a5c616585a6271","carrier_tracking_no":"43128000105","carrier":"hermes","service":"standard","created_at":"2014-11-12T14:03:45+01:00","price":3.5,"reference_number":null,"tracking_url":"https://track.shipcloud.io/86afb143f9","to":{"company":null,"first_name":"Hans","last_name":"Meier","care_of":null,"street":"Semmelweg","street_no":"1","zip_code":"12345","city":"Hamburg","state":null,"country":"DE"},"from":{"company":"webionate GmbH","first_name":null,"last_name":"Fahlbusch","care_of":null,"street":"Lüdmoor","street_no":"35a","zip_code":"22175","city":"Hamburg","state":null,"country":"DE"},"packages":[{"id":"be81573799958587ae891b983aabf9c4089fc462","length":10.0,"width":10.0,"height":10.0,"weight":1.5,"tracking_events":[{"timestamp":"2014-11-12T14:03:45+01:00","location":"shipcloud","status":"label_created","details":"Es wurde eine Sendung angelegt"}]}]},{"id":"be598a2fd27304cf2d82669b197517623629d94e","carrier_tracking_no":"1Z12345E1305277940","carrier":"ups","service":"standard","created_at":"2014-11-12T14:03:45+01:00","price":3.0,"reference_number":null,"tracking_url":"https://track.shipcloud.io/be598a2fd2","to":{"company":null,"first_name":"Test","last_name":"Kunde","care_of":null,"street":"Gluckstr.","street_no":"57","zip_code":"22081","city":"Hamburg","state":null,"country":"DE"},"from":{"company":"webionate GmbH","first_name":null,"last_name":"Fahlbusch","care_of":null,"street":"Lüdmoor","street_no":"35a","zip_code":"22175","city":"Hamburg","state":null,"country":"DE"},"packages":[{"id":"74d4f1fc193d8a7ca542d1ee4e2021f3ddb82242","length":15.0,"width":20.0,"height":10.0,"weight":2.0,"tracking_events":[{"timestamp":"2014-11-12T14:03:45+01:00","location":"shipcloud","status":"label_created","details":"Es wurde eine Sendung angelegt"}]}]}]}
Getting information about a shipment
Only shipments where create_shipping_label is true contain prices
and may contain tracking_events
Shipments that are created on the sandbox system aren't send to the carriers. Therefore they
won't contain tracking events.
id, the id attribute that was returned when creating the shipment
Response
200 (OK)
{"carrier":"dhl","carrier_tracking_no":"84168117830018","created_at":"2013-04-16T10:43:04Z","from":{"company":"Musterfirma","first_name":"Hans","last_name":"Meier","care_of":null,"street":"Musterstraße","street_no":"22","city":"Musterstadt","zip_code":"12345","state":null,"country":"DE"},"id":"3a186c51d4281acbecf5ed38805b1db92a9d668b","label_url":"https://shipping-labels.shipcloud.io/shipments/01370b4d/199f803bf8/label/shipping_label_199f803bf8.pdf","notification_email":"receiver@notification.com","packages":[{"id":"3af8f7e5af196e1950deebd389a87406e1e5bb80","weight":1.5,"length":10.0,"width":6.0,"height":8.0,"tracking_events":[{"timestamp":"2013-05-26T16:55:24+02:00","location":"Hamburg, Deutschland","status":"delivered","details":"Die Sendung wurde erfolgreich zugestellt."},{"timestamp":"2013-05-26T08:12:12+02:00","location":"Hamburg, Deutschland","status":"out_for_delivery","details":"Die Sendung wurde in das Zustellfahrzeug geladen."},{"timestamp":"2013-05-25T11:46:34+02:00","location":"Hamburg, Deutschland","status":"transit","details":"Die Sendung wurde im Start-Paketzentrum bearbeitet."}]}],"price":3.4,"reference_number":"ref123456","service":"standard","shipper_notification_email":"shipper@notification.com","to":{"company":"Receiver Inc.","first_name":"Max","last_name":"Mustermann","street":"Beispielstrasse","street_no":"42","city":"Hamburg","zip_code":"22100","state":null,"country":"DE"},"tracking_url":"https://track.shipcloud.io/3a186c51d4"}
Prepared shipments (create_shipping_label is false) can be deleted
at any time, because no transaction with the carrier has happened until this point and no
actual shipping label has been created. In case you've created a shipping label you can
delete it before the cutoff time of the carrier. Cutoff times differ from carrier to carrier
and are some time between 5pm and 8pm.
carrier* (string), the carrier you want to use. Possible values are
angel_de, cargo_international, dhl, dhl_express, dpag, dpd, gls, go, hermes, iloxx, parcel_one, ups
service (string), service that should be used. Available values are
standard, one_day, one_day_early, returns, cargo_international_express, dhl_europaket, dhl_prio, dhl_warenpost, dpag_warenpost, dpag_warenpost_signature, dpag_warenpost_untracked, gls_express_0800, gls_express_0900, gls_express_1000, gls_express_1200, ups_express_1200
to* (object), describes the receivers address. See
address request
for a detailed definition.
from (object, optional), describes the senders address. See
address request
for a detailed definition.
package*, object describing the package dimensions
You can also omit the from parameter if the users has configured a standard ship from address
in her/his shipcloud profile.
Response
200 (OK)
{"shipment_quote":{"price":42.12}}
Trackers
Trackers make it possible to track a shipment that wasn't created using shipcloud. They are
basically a way to monitor shipments created elsewhere. All you have to do is provide us with the
tracking number you received from the carrier as well as its corresponding name acronym.
Notice: Since we're always tracking shipments created
using shipcloud contracts, trackers can only be used with your own carrier contracts.
carrier_tracking_no (string), the tracking number provided by the carrier
carrier (array), name of the carrier you want to use. Possible values are
DHL, DPD, GLS, UPS
to* (object, optional), describes the receivers address. See
address request
for a detailed definition.
from* (object, optional), describes the senders address. If missing, the
default sender address (if defined in your shipcloud account) will be used. See
address request
for a detailed definition.
notification_email (string, optional), email address that we should notify once
there's an update for this shipment. notice: since Amazon
doesn't allow a direct communication with buyers, all Amazon email addresses are excluded from
receiving our notification emails
Creating a tracker
This is the way to create a tracker based on a tracking number provided by one of our supported carriers. Not
all carriers are providing the option to just track shipments. For a list of carriers please look at our
Open API specification.
{"trackers":[{"id":"4a6922e2-09ad-4724-807c-7b4e572d3c6b","carrier_tracking_no":"723558934169","to":{"company":null,"first_name":"Hans","last_name":"Meier","care_of":null,"street":"Semmelweg","street_no":"1","zip_code":"12345","city":"Hamburg","state":null,"country":"DE"},"status":"delivered","created_at":"2015-07-20T09:35:23+02:00","tracking_status_updated_at":"2015-08-01T11:35:23+02:00","last_polling_at":"2015-08-03T10:23:45+02:00","next_polling_at":"2015-08-03T12:23:45+02:00","shipment_id":"6306d78506af51913c89b0af45b1ba7d430e4208","carrier":"ups","tracking_events":[{"id":"0aa3479-8695-4a6a-8326-ed55df65b9a6","timestamp":"2015-07-21T08:57:44+02:00","location":"Hamburg","status":"out_for_delivery","details":"Some details"},{"id":"0aa3479-8695-4a6a-8326-ed55df65b9a6","timestamp":"2015-07-21T10:57:44+02:00","location":"Hamburg","status":"delivered","details":"Some more details"}]},{"id":"5452ec46-560e-42ba-adf7-8a1b46d60ece","carrier_tracking_no":"JJD000390006125214950","to":{"company":null,"first_name":"Hans","last_name":"Meier","care_of":null,"street":"Semmelweg","street_no":"1","zip_code":"12345","city":"Hamburg","state":null,"country":"DE"},"from":{"company":"webionate GmbH","first_name":null,"last_name":"Fahlbusch","care_of":null,"street":"Lüdmoor","street_no":"35a","zip_code":"22175","city":"Hamburg","state":null,"country":"DE"},"status":"delivered","created_at":"2016-12-26T08:48:21+02:00","tracking_status_updated_at":"2016-12-28T12:16:44+02:00","last_polling_at":"2016-12-28T22:10:45+02:00","next_polling_at":"2016-12-28T22:12:45+02:00","shipment_id":"cbceeb51314c88e8047b8b5dfd92313528238b88","carrier":"dhl","tracking_events":[{"id":"0aa3479-8695-4a6a-8326-ed55df65b9a6","timestamp":"2016-12-26T08:48:21+02:00","location":"Radefeld","status":"transit","details":"Lieferung hat das Logistikzentrum verlassen und ist unterwegs."},{"id":"0aa3479-8695-4a6a-8326-ed55df65b9a6","timestamp":"2016-12-28T09:34:11+02:00","location":"Hamburg","status":"out_for_delivery","details":"Sendung wird zugestellt."},{"id":"0aa3479-8695-4a6a-8326-ed55df65b9a6","timestamp":"2016-12-28T12:16:44+02:00","location":"Hamburg","status":"delivered","details":"Ihre Sendung wurde zugestellt. Die Sendung wurde zugestellt an Simon Fröhler shipcloud GmbH. "}]}]}
id, the id attribute that was returned when creating the tracker
Response
200 (OK)
{"id":"4a6922e2-09ad-4724-807c-7b4e572d3c6b","carrier_tracking_no":"723558934169","status":"delivered","created_at":"2015-07-20T09:35:23+02:00","to":{"company":null,"first_name":"Hans","last_name":"Meier","care_of":null,"street":"Semmelweg","street_no":"1","zip_code":"12345","city":"Hamburg","state":null,"country":"DE"},"from":{"company":"webionate GmbH","first_name":null,"last_name":"Fahlbusch","care_of":null,"street":"Lüdmoor","street_no":"35a","zip_code":"22175","city":"Hamburg","state":null,"country":"DE"},"tracking_status_updated_at":"2015-08-01T11:35:23+02:00","last_polling_at":"2015-08-03T10:23:45+02:00","next_polling_at":null,"shipment_id":"6306d78506af51913c89b0af45b1ba7d430e4208","carrier":"ups","tracking_events":[{"id":"0aa3479-8695-4a6a-8326-ed55df65b9a6","timestamp":"2015-07-21T08:57:44+02:00","location":"Hamburg","status":"out_for_delivery","details":"Some details"},{"id":"0aa3479-8695-4a6a-8326-ed55df65b9a6","timestamp":"2015-07-21T10:57:44+02:00","location":"Hamburg","status":"delivered","details":"Some more details"}]}
Webhooks
The following is a section of resources related to webhooks.
id, the id attribute that was returned when creating the webhook
Response
204 (No Content)
{}
Routing Rules
In addition to the traditional Ship journey, our API also supports the Checkout to Ship
journey, providing a seamless solution for allowing customers to select their preferred
carrier and service during the checkout process.
Getting available shipping options for a route
With this call you can find out which shipping options are available for the desired
route and specific shipment.
{"carrier_service_combinations":[{"carrier":"ups","service":"standard","carrier_display_name":"UPS","service_display_name":"","description":"Delivery within 1-2 business days","checkout_shipping_price":"0","pickup_dropoff":"true"},{"carrier":"dhl","service":"standard","carrier_display_name":"DHL","service_display_name":"","description":"Delivery within 1-2 business days","checkout_shipping_price":"6.90","pickup_dropoff":"true"},{"carrier":"dpd","service":"standard","carrier_display_name":"DPD","service_display_name":"","description":"Delivery within 1-2 business days","checkout_shipping_price":"3.90"},{"carrier":"ups","service":"one_day","carrier_display_name":"UPS","service_display_name":"Express","description":"Expected delivery on the next business day","checkout_shipping_price":"8.90","pickup_dropoff":"true"},{"carrier":"ups","service":"one_day_early","carrier_display_name":"UPS","service_display_name":"Express early","description":"Expected delivery on the next business day before noon","checkout_shipping_price":"14.90","pickup_dropoff":"false"}],"rule_tree_version":2}
View the OpenAPI spec