shipcloud API v1

Changelog

If you haven’t seen it already in the github-repo for this website - we’ve got a api changelog file where you can see the changes we’ve made to our api. There is also an HTML-version of the changelog file for your convenience.

http status codes

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.

Parameters:

  • 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
  • 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)

Creating an address

If you want to create an Address, this is the way to go!

Request

POST /v1/addresses

{
  "company": "Muster-Company",
  "first_name": "Max",
  "last_name": "Mustermann",
  "street": "Musterstraße",
  "street_no": "42",
  "zip_code": "54321",
  "city": "Musterstadt",
  "country": "DE",
  "phone": "555-555"
}

JSON schema: Create addresses request

Response

200 (OK)
{
  "id": "522a7cb1-d6c8-418c-ac26-011127ab5bbe",
  "company": "Muster-Company",
  "first_name": "Max",
  "last_name": "Mustermann",
  "care_of": null,
  "street": "Musterstraße",
  "street_no": "42",
  "zip_code": "54321",
  "city": "Musterstadt",
  "state": null,
  "country": "DE",
  "phone": "555-555"
}

JSON schema: Create addresses response

Getting a list of addresses

Request

GET /v1/addresses

You can filter the shipments list using one or more of the following

GET parameters:

  • first_name, e.g. ‘first_name=Max’
  • last_name, e.g. ‘last_name=Mustermann’
  • company, e.g. ‘company=Example%20Company’
  • care_of, e.g. ‘care_of=Roger%20Receiver’
  • street, e.g. ‘street_no=Musterstraße’
  • street_no, e.g. ‘street_no=42’
  • zip_code, e.g. ‘zip_code=12345’
  • state, e.g. ‘state=CA’
  • city, e.g. ‘city=Musterstadt’
  • country, e.g. ‘country=DE’
  • phone, e.g. ‘phone=555-555’
  • 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’

Response

200 (OK)
{
  "addresses": [
    {
      "id": "1c81efb7-9b95-4dd8-92e3-cac1bca3df6f",
      "company": null,
      "first_name": "Max",
      "last_name": "Mustermann",
      "care_of": null,
      "street": "Musterstraße",
      "street_no": "42",
      "zip_code": "12345",
      "city": "Musterstadt",
      "state": null,
      "country": "DE",
      "phone": null
    },
    {
      "id": "7ea2a290-b456-4ecf-9010-e82b3da298f0",
      "company": "Apple Inc.",
      "first_name": "Tim",
      "last_name": "Cook",
      "care_of": null,
      "street": "Infinite Loop",
      "street_no": "1",
      "zip_code": "95014",
      "city": "Cupertino",
      "state": "CA",
      "country": "US",
      "phone": "408-996-1010"
    },
    {
      "id": "dd2af208-9d0e-4f3a-8ee5-601ecec99d27",
      "company": "shipcloud GmbH",
      "first_name": null,
      "last_name": "Mustermann",
      "care_of": null,
      "street": "Musterstraße",
      "street_no": "42",
      "zip_code": "12345",
      "city": "Musterstadt",
      "state": null,
      "country": "DE",
      "phone": null
    }
  ]
}

Show an Address

Request

GET /v1/addresses/:id

GET parameters:

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

Response

200 (OK)
{
  "id": "1c81efb7-9b95-4dd8-92e3-cac1bca3df6f",
  "company": null,
  "first_name": "Max",
  "last_name": "Mustermann",
  "care_of": null,
  "street": "Musterstraße",
  "street_no": "42",
  "zip_code": "12345",
  "city": "Musterstadt",
  "state": null,
  "country": "DE",
  "phone": null
}

JSON schema: Address response

Shipments

The following is a section of resources related to shipments. Be advised: We will charge you only for shipments that a label was created for.

Please notice the requirements regarding the use of the parameter "description" (either in the root or as part of the "package" attribute).

Parameters:

  • carrier* (string), the carrier you want to use. Possible values are “dhl”, “dpag”, “ups”, “dpd”, “hermes”, “gls”, “iloxx”, “tnt”, “fedex”, “go” and “parcel.one”
  • 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.
  • 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. See additional insurance for detailed information about when to supply this.
      • amount (float), value of package contents
      • currency (string), currency as uppercase ISO 4217 code
    • description (string), if you’re using UPS with service returns or DHL with service express 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”. See package types for detailed information.
  • service (string, optional), service that should be used. Available values are “returns”, “standard”, “one_day” , “one_day_early”. See supported services for detailed information.
  • additional_services (array, optional), array of objects where you can define additional services to be used. See additional services for detailed information
  • pickup (object, optional), describes the pickup request. Mandatory for creating shipments with TNT as carrier - see TNT specifics
    • 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.
  • 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), define the DIN size the returned label should have. See label size recipe for detailed information
  • notification_email (string, optional), email address that we should notify once there’s an update for this shipment
  • 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!

Request

POST /v1/shipments

{
  "to": {
      "company": "Receiver Inc.",
      "first_name": "Max",
      "last_name": "Mustermann",
      "street": "Beispielstrasse",
      "street_no": "42",
      "city": "Hamburg",
      "zip_code": "22100",
      "country": "DE"
  },
  "package": {
      "weight": 1.5,
      "length": 20,
      "width": 20,
      "height": 20,
      "type": "parcel"
  },
  "carrier": "dhl",
  "service": "standard",
  "reference_number": "ref123456",
  "notification_email": "person@example.com",
  "create_shipping_label": true
}

JSON schema: Shipments request

Response

200 (OK)
{
  "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
}

JSON schema: Shipments response

Getting a list of shipments

Request

GET /v1/shipments

no payload

You can filter the shipments list using one or more of the following

GET parameters:

  • carrier, e.g. ‘carrier=dhl’
  • service, e.g. ‘service=returns’
  • reference_number, e.g. ‘reference_number=ref123456’
  • carrier_tracking_no, e.g. ‘carrier_tracking_no=43128000105’
  • tracking_status, e.g. ‘tracking_status=out_for_delivery’
  • 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’

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": "http://track.shipcloud.dev/de/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": "http://track.shipcloud.dev/de/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.

Request

GET /v1/shipments/:id

no payload

URL parameters:

  • 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": "http://api.shipcloud.io/shipping_label_3a186c51d4.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": "http://track.shipcloud.io/3a186c51d4"
}

JSON schema: Shipments response

Updating a shipment

Request

PUT /v1/shipments/:id

{
  "to": {
      "company": "Receiver Inc.",
      "first_name": "Max",
      "last_name": "Mustermann",
      "street": "Beispielstrasse",
      "street_no": "42",
      "city": "Hamburg",
      "zip_code": "22100",
      "country": "DE"
  },
  "package": {
      "weight": 1.5,
      "length": 20,
      "width": 20,
      "height": 20,
      "type": "parcel"
  },
  "carrier": "dhl",
  "service": "standard",
  "reference_number": "ref123456",
  "notification_email": "person@example.com",
  "create_shipping_label": true
}

Response

200 (OK)
{
  "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
}

Deleting a shipment

Request

DELETE /v1/shipments/:id

Prepared shipments (where 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.

no payload

URL parameters:

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

Response

204 (No Content)
{}

Carriers

Get all carriers available for your account

Request

GET /v1/carriers

no payload

Response

200 (OK)
[
  {
    "name": "dhl",
    "display_name": "Deutsche Post DHL",
    "services": [
      "standard",
      "returns",
      "one_day",
      "one_day_early"
    ],
    "package_types": [
      "parcel",
      "bulk"
    ]
  },
  {
    "name": "dpag",
    "display_name": "Deutsche Post",
    "services": [
      "standard"
    ],
    "package_types": [
      "letter",
      "parcel_letter",
      "books"
    ]
  },
  {
    "name": "dpd",
    "display_name": "DPD - Dynamic Parcel Distribution",
    "services": [
      "standard",
      "returns",
      "one_day",
      "one_day_early"
    ],
    "package_types": [
      "parcel",
      "parcel_letter"
    ]
  }
]

JSON schema: carriers response

Shipment Quotes

With this call you can find out how much we will charge you for a specific shipment.

Parameters:

  • carrier* (string), the carrier you want to use. Possible values are “dhl”, “dpag”, “ups”, “dpd”, “hermes”, “gls”, “iloxx”, “tnt”, “fedex”, “go” and “parcel.one”
  • service (string), service that should be used. Available values are “returns”, “standard”, “one_day” , “one_day_early”, “same_day”. See supported services for detailed information
  • 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
    • 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

Creating a shipment quote

Request

POST /v1/shipment_quotes

{
  "carrier": "dhl",
  "service": "standard",
  "to": {
    "street": "Beispielstrasse",
    "street_no": "42",
    "zip_code": "22100",
    "city": "Hamburg",
    "country": "DE"
  },
  "from": {
    "street": "Musterstrasse",
    "street_no": "23",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "package": {
    "weight": 1.5,
    "length": 20,
    "width": 20,
    "height": 20
  }
}

In case you’ve previously added an adress and know its id, you can use it instead of providing a complete set of address data.

{
  "carrier": "dhl",
  "service": "standard",
  "to": {
    "id": "522a7cb1-d6c8-418c-ac26-011127ab5bbe"
  },
  "from": {
    "street": "Musterstrasse",
    "street_no": "23",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "package": {
    "weight": 1.5,
    "length": 20,
    "width": 20,
    "height": 20
  }
}

You can also omit the from parameter if the users has configured a standard ship from address in her/his shipcloud profile.

JSON schema: Shipment Quotes request

Response

200 (OK)
{
  "shipment_quote": {
    "price": 42.12
  }
}

JSON schema: Shipment Quotes response

Rates

Getting the rate for a package

The rates call is deprecated. Please use Shipment Quotes.

With this call you can find out how much a specific package will cost you.

You'll have to use your live api key to get the correct prices.

Request

POST /v1/rates

{
  "carrier": "dhl",
  "weight": 1.5,
  "length": 20,
  "width": 20,
  "height": 20
}

Parameters:

  • carrier (string, optional), the carrier you want to use. Possible values are “dhl”, “dpag”, “ups”, “dpd”, “hermes”, “gls”, “iloxx”, “tnt”, “fedex”, “go” and “parcel.one”.
  • 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)
{
  "rate": 3.80
}

Pickup requests

Requesting pickup

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 for that.

Request

Here’s an example for having all shipments being picked up by a specific carrier:

Parameters:

  • carrier (string), the carrier you want to use. Possible values are “dpd”, “fedex”, “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.

POST /v1/pickup_requests

{
  "carrier": "dpd",
  "pickup_time": {
    "earliest": "2015-09-15T09:00:00+02:00",
    "latest": "2015-09-15T18:00:00+02:00"
  },
  "pickup_address": {
    "company": "Muster-Company",
    "first_name": "Max",
    "last_name": "Mustermann",
    "street": "Musterstraße",
    "street_no": "42",
    "zip_code": "54321",
    "city": "Musterstadt",
    "country": "DE",
    "phone": "555-555"
  }
}

If you want to only have specific shipments be picked up you add the shipment ids to the call:

POST /v1/pickup_requests

{
  "carrier": "dpd",
  "pickup_time": {
    "earliest": "2015-09-15T09:00:00+02:00",
    "latest": "2015-09-15T18:00:00+02:00"
  },
  "pickup_address": {
    "company": "Muster-Company",
    "first_name": "Max",
    "last_name": "Mustermann",
    "street": "Musterstraße",
    "street_no": "42",
    "zip_code": "54321",
    "city": "Musterstadt",
    "country": "DE",
    "phone": "555-555"
  },
  "shipments": [
    {
      "id": "3a186c51d4281acbecf5ed38805b1db92a9d668b"
    }
  ]
}

JSON schema: Pickup Requests request

Response

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.

200 (OK)
{
  "id": "123456",
  "carrier": "dpd",
  "pickup_time": {
    "earliest": "2015-09-15T09:00:00+02:00",
    "latest": "2015-09-15T18:00:00+02:00"
  },
  "pickup_address": {
    "id": "522a7cb1-d6c8-418c-ac26-011127ab5bbe",
    "company": "Muster-Company",
    "first_name": "Max",
    "last_name": "Mustermann",
    "street": "Musterstraße",
    "street_no": "42",
    "zip_code": "54321",
    "city": "Musterstadt",
    "country": "DE",
    "phone": "555-555"
  }
}

JSON schema: Pickup Requests response

Webhooks

The following is a section of resources related to webhooks.

Parameters:

  • url (string), the webhooks url
  • event_types (array), subscripted events

Creating a webhook

If you want to create a webhook, this is the way to go!

Request

POST /v1/webhooks

{
  "url": "https://example.com/webhook",
  "event_types": ["shipment.tracking.delayed", "shipment.tracking.delivered"]
}

JSON schema: Create webhook request

Response

200 (OK)
{
  "id": "e0ff4250-6c8e-494d-a069-afd9d566e372",
  "url": "https://example.com/webhook",
  "event_types": ["shipment.tracking.delayed", "shipment.tracking.delivered"],
  "deactivated": false
}

JSON schema: Create webhooks response

Getting a list of webhooks

Request

GET /v1/webhooks

Response

200 (OK)
{
  "webhooks": [
    {
      "id": "583cfd8b-77c7-4447-a3a0-1568bb9cc553",
      "url": "https://example.com/webhook",
      "event_types": ["shipment.tracking.picked_up", "shipment.tracking.delivered"],
      "deactivated": false
    },
    {
      "id": "e0ff4250-6c8e-494d-a069-afd9d566e372",
      "url": "https://example.com/webhook",
      "event_types": ["shipment.tracking.delayed", "shipment.tracking.delivered"],
      "deactivated": false
    }
  ]
}

Show a webhook

Request

GET /v1/webhooks/:id

GET parameters:

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

Response

200 (OK)
{
  "id": "e0ff4250-6c8e-494d-a069-afd9d566e372",
  "url": "https://example.com/webhook",
  "event_types": ["shipment.tracking.delayed", "shipment.tracking.delivered"],
  "deactivated": false
}

JSON schema: Webhook response

Deleting a webhook

Request

DELETE /v1/webhooks/:id

no payload

URL parameters:

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

Response

204 (No Content)
{}

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.

Parameters:

  • 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”, “dpag”, “ups”, “dpd”, “hermes”, “gls”, “iloxx”, “tnt”, “fedex”, “go” and “parcel.one”
  • 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.

Creating a tracker

This is the way to create a tracker based on a tracking number provided by one of our supported carriers (DHL, Deutsche Post, UPS, DPD, Hermes, GLS, MyDPD Business (iloxx), TNT, FedEx, GO! and PARCEL.ONE)

Request

POST /v1/trackers

{
  "carrier_tracking_no": "723558934169",
  "carrier": "UPS"
}

JSON schema: Create tracker request

Response

200 (OK)
{
  "id": "4a6922e2-09ad-4724-807c-7b4e572d3c6b",
  "carrier_tracking_no": "723558934169",
  "status": "registered",
  "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"
  },
  "tracking_status_updated_at": null,
  "last_polling_at": null,
  "next_polling_at": "2015-07-20T09:35:23+02:00",
  "shipment_id": "12345abcdef",
  "carrier": "ups",
  "tracking_events": []
}

JSON schema: Create tracker response

Getting a list of trackers

Request

GET /v1/trackers

Response

200 (OK)
{
  "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. "
        }
      ]
    }
  ]
}

Show a tracker

Request

GET /v1/trackers/:id

GET parameters:

  • 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"
    }
  ]
}

JSON schema: Tracker response