Table of Contents

    API

    Transparent Proxy

    Please sign in and we'll assign you a private URL to trace your traffic and help you implement the API.

shipcloud API v1

Introduction

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.

For developers to test their code before shipping it, we're supplying every account with test and live API keys.

Authentication

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.

Aside from sending you're API key all API requests must be made using HTTPS. Don't bother trying to use HTTP. It will fail!

Versioning

From time to time we will be releasing new versions of our API. In order to not break (your) implementations of our API, we will adjust the path to reflect each new major version. So consecutive releases will be called using /v2/, /v3/ and so on after the base url.

Address handling

When sending to or from parameters you have to specify a contact for the shipment. This can either be a company or a person identified by first_name and last_name. So although the entries are marked as being optional, one of them has to be specified in the request.

Carrier specific address handling

DHL

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.

Returns

We're currently only supporting returns for DHL, HERMES and UPS.

Shipment Resources

The following is a section of resources related to shippings

POST

/v1/shipments

Create a new shipment

Request parameters:

  • carrier* (string), the carrier you want to use. Possible values are "dpd", "dhl", "gls", "hermes", "iloxx", "ups"
  • to*, object describing the receivers address
    • company (string), the receivers company name
    • 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
    • city (string), city
    • zip_code (string), zip code
    • state (string, optional), state
    • country (string), country as Uppercase ISO 3166-1 alpha-2 code
  • from*, object describing the senders address. Address definition: see "to". If missing, the default sender address (if defined in your shipcloud account) will be used
  • 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
    • description (string), if you're using UPS returns or DHL express this is mandatory otherwise it's optional
  • service (string, optional), additional service. Available values are "returns", "standard", "one_day" (Express),"one_day_early" (Express until 10 o'clock). default: standard
  • 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
  • create_shipping_label (boolean), determines if a shipping label should be created at the carrier (this means you will be charged)

* = if create_shipping_label is set to false, all of these parameters become optional

Response

200 (OK)
Content-Type: application/json
{ 
  "id":"3a186c51d4281acbecf5ed38805b1db92a9d668b",
  "carrier_tracking_no":"84168117830018",
  "tracking_url":"http://track.shipcloud.io/3a186c51d4",
  "label_url":"http://api.shipcloud.io/shipping_label_3a186c51d4.pdf",
  "price":3.4
}

GET

/v1/shipments/{id}

Get information about a shipment.

Info

Only shipments marked as complete contain prices and may contain tracking_events

URL parameters:

  • id, the id attribute that was returned when creating the shipment

Response

200 (OK)
Content-Type: application/json
{ 
  "id":"3a186c51d4281acbecf5ed38805b1db92a9d668b",
  "carrier_tracking_no":"84168117830018",
  "carrier":"dhl",
  "created_at":"2013-04-16T10:43:04Z",
  "tracking_url":"http://track.shipcloud.io/3a186c51d4",
  "label_url":"http://api.shipcloud.io/shipping_label_3a186c51d4.pdf",
  "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"
  },
  "to":{
    "company":"Receiver Inc.",
    "first_name":"Max",
    "last_name":"Mustermann",
    "street":"Beispielstrasse",
    "street_no":"42",
    "city":"Hamburg",
    "zip_code":"22100",
    "state":null,
    "country":"DE"
  },
    "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"
}

PUT

/v1/shipments/{id}

Update a shipment

URL parameters:

  • id, the id attribute that was returned when creating the shipment

Request parameters:

  • carrier (string, optional), the carrier you want to use. Possible values are "dpd", "dhl", "gls", "hermes", "iloxx", "ups"
  • to (optional), object describing the receivers address
    • company (string, optional), the receivers company name
    • first_name (string, optional), the receivers first name
    • last_name (string, optional), the receivers last name
    • care_of (string, optional), name of the person that should be able to receive the package
    • street (string, optional), street name
    • street_no (string, optional), house number
    • city (string, optional), city
    • zip_code (string, optional), zip code
    • state (string, optional), state
    • country (string, optional), country as Uppercase ISO 3166-1 alpha-2 code
  • from (optional), object describing the senders address. Address definition: see "to". If missing, the default sender address (if defined in your shipcloud account) will be used
  • package (optional), object describing the package dimensions
    • number (string), used to identify the package
    • width (float, optional), width of the package in cm
    • length (float, optional), length of the package in cm
    • height (float, optional), height of the package in cm
    • weight (float, optional), weight in kg
  • service (string), additional service. Available value is "returns"
  • 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
  • create_shipping_label (boolean), determines if a shipping label should be created at the carrier (this means you will be charged)

Response

200 (OK)
Content-Type: application/json
{ 
  "id":"3a186c51d4281acbecf5ed38805b1db92a9d668b",
  "carrier_tracking_no":"84168117830018",
  "tracking_url":"http://track.shipcloud.io/3a186c51d4",
  "label_url":"http://api.shipcloud.io/shipping_label_3a186c51d4.pdf",
  "price":3.4
}

DELETE

/v1/shipments/{id}

Delete a Shipment

Info

Only shipments marked as not being complete can be deleted, because no transaction with a carrier has been done until this point.

Response

204 (No Content)
Content-Type: application/json
{
}

Carrier Resources

GET

/v1/carriers

Get all carriers available for a customer (as identified by the API key)

Response

200 (OK)
[
    {
        "name":"dhl",
        "display_name":"Deutsche Post DHL"
    },
    {
        "name":"hermes",
        "display_name":"Hermes Europe"
    }
]

Rates Resources

POST

/v1/rates

Get the rate for a specific package being delivered via a carrier

Request parameters:

  • carrier (string, optional), the carrier you want to use. Possible values are "dpd", "dhl", "gls", "hermes", "iloxx", "ups".
  • 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

Response

200 (OK)
Content-Type: application/json
{
  "rate":3.80
}

Pickup Resources

POST

/v1/pickup_requests

Request a pickup

Request parameters:

  • carrier (string), the carrier you want to use. Possible values are "dhl", "gls", "hermes", "ups".
  • pickup_date (string), pickup date (e.g. 2014/02/12)

Response

200 (OK)
Content-Type: application/json
{
  "id":"123456",
  "carrier":"dhl",  
  "pickup_date":"2014/02/12"
}