Examples

To give you a better understanding of how the shipcloud api could be used you can find a few examples on this page. Sometimes there’s also a certain chain of calls you need to perform to achieve a specific goal.

Additional services

Some services can be used on top of a normal shipment. Therefore they don’t fall under the normal definition of a service - and because they mostly are only available for a few carriers. We’re calling them additional services.

Advance notice

Some carriers provide the option to notify the recipient of a shipment of its arrival date and / or time. We currently support advance notices for DHL and DPD. While DHL supports notifications via email DPD also allows the recipient to also be notified via SMS.

Requirements:

Available for the following carriers:

Notification via email

POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "advance_notice",
      "properties": {
        "email": "test@example.com",
        "language": "en"
      }
    }
  ],
  "carrier": "dhl",
  "create_shipping_label": true
}

Notification via SMS

POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "advance_notice",
      "properties": {
        "sms": "+4917012345678"
      }
    }
  ],
  "carrier": "dpd",
  "create_shipping_label": true
}

Cash on delivery

Available for the following carriers:

Saturday delivery

Available for the following carriers:

DHL - Advance notice

DHL currently only supports advance notice via email. You can find an example above in our advance notice section.

DHL - Cash on delivery

Requirements:

  • You’ll have to use your own DHL contract
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "cash_on_delivery",
      "properties": {
        "amount": 123.45,
        "currency": "EUR",
        "bank_account_holder": "Max Mustermann",
        "bank_name": "Musterbank",
        "bank_account_number": "DE12500105170648489890",
        "bank_code": "BENEDEPPYYY",
        "reference1": "reason for transfer"
      }
    }
  ],
  "carrier": "dhl",
  "create_shipping_label": true
}

DHL - Delivery Time (Preferred Time)

With the DHL preferred time service you can choose between several two-hour time frames for the delivery of your item. The following options are available for time_of_day_earliest and time_of_day_latest (Monday - Saturday):

  • Nationwide in Germany for evening deliveries:
    • 18:00 - 20:00
    • 19:00 - 21:00
  • In specific German conurbations for daytime deliveries:
    • 10:00 - 12:00
    • 12:00 - 14:00
    • 14:00 - 16:00
    • 16:00 - 18:00

Requirements:

  • You’ll have to use your own DHL contract
  • Your DHL contract must be setup for DHL “Ship” (DHL “Versenden”)
  • The recipient has to be located in Germany
  • Only available for label size A5
POST https://api.shipcloud.io/v1/shipments
{
  "carrier": "dhl",
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "delivery_time",
      "properties": {
          "time_of_day_earliest": "18:00",
          "time_of_day_latest": "20:00"
      }
    }
  ],
  "carrier": "dhl",
  "create_shipping_label": true
}

DHL - Ident Check

If you want the carrier to only deliver the shipment to a specific person you can use the DHL ident check. DHL will ask the recepient to show them a valid ID. Thus you will be able to minimize fraud, only deliver to persons of a certain age (e.g. when sending alcoholic beverages, adult content or pharmaceuticals that need a prescription).

Caution:

  • Please keep in mind that additional fees will be charged by DHL. Check your DHL contract or ask your DHL Account Manager to get a quote.

Requirements:

  • You’ll have to use your own DHL contract
  • Your DHL contract must be setup for DHL “Ship” (DHL “Versenden”)
  • The recipient has to be located in Germany
  • Only available for label size A5
POST https://api.shipcloud.io/v1/shipments
{
  "carrier": "dhl",
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "dhl_ident_check",
      "properties": {
        "first_name": "Hans",
        "last_name": "Dampf",
        "date_of_birth": "1982-09-30",
        "minimum_age": "16"
      }
    }
  ],
  "carrier": "dhl",
  "create_shipping_label": true
}

DHL - Premium International

Using the additional service DHL premium international you can reduce international shipping transit times.

Requirements:

  • You’ll have to use your own DHL contract
  • Your DHL contract must be setup for DHL “Ship” (DHL “Versenden”)
POST https://api.shipcloud.io/v1/shipments
{
  "carrier": "dhl",
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "premium_international"
    }
  ],
  "carrier": "dhl",
  "create_shipping_label": true
}

DHL - Visual age check

When sending goods that are only legally available for people of a specific age, you can request the carrier to check the receiver’s age visually. Just add the additional service visual_age_check and either 16 or 18 as its minimum_age value.

Requirements:

  • You need to use your own DHL Ship contract
  • The recipient has to be located in Germany
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "visual_age_check",
      "properties": {
        "minimum_age": "16"
      }
    }
  ],
  "carrier": "dhl",
  "create_shipping_label": true
}

DHL Express - Saturday delivery

When sending packages on a Friday you can specify that they should be delivered on Saturday.

Requirements:

  • service has to be ‘one_day’ or ‘one_day_early’
  • you’ll have to use your own contract with the carrier
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "saturday_delivery"
    }
  ],
  "carrier": "dhl_express",
  "service": "one_day",
  "create_shipping_label": true
}

DPD - Drop authorization

When sending packages via DPD the sender can allow the carrier to leave the shipment with someone else in case the receiver isn’t present and has allowed the sender to do so.

POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "drop_authorization",
      "properties": {
        "message": "Description about where the package should be left"
      }
    }
  ],
  "carrier": "dpd",
  "create_shipping_label": true
}

DPD - Saturday delivery

When sending packages on a Friday you can specify that they should be delivered on Saturday (if the carrier supports this).

Requirements:

  • service has to be ‘one_day’ or ‘one_day_early’
  • you’ll have to use your own contract with the carrier
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "saturday_delivery"
    }
  ],
  "carrier": "dpd",
  "service": "one_day",
  "create_shipping_label": true
}

DPD - Predict

DPD allows recipients to be notified of a pending delivery within the next hour. The so called predict service can be used with shipcloud by specifying it as an additional service. You can either specify the email address or phone number of your customer to be notified.

For examples see advance notice

Requirements:

  • service has to be ‘standard’

Label size

Not all carriers use the same size of labels. Have a look at our chart of the carrier specific label sizes we support.

You can configure the standard size we should create labels for each and every carrier from within the shipcloud backoffice, so you won’t have to think about handling different label sizes. You can however define the size of the label on a per shipment basis. So, when you’re creating a shipping label via our api you can send us the size the shipping label should have.

{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "carrier": "dhl",
  "service": "standard",
  "label": {
    "size": "A5"
  },
  "create_shipping_label": true
}

GLS - Cash on delivery

Cash on delivery parcels with GLS: The recipient pays for the goods on delivery in cash. GLS accepts the money and transfers it securely and quickly to the sender’s account – usually within five working days after delivery.

Requirements:

  • Maximum cash on delivery amount and liability limit: € 2,500
  • The Currency has to be EUR
  • The sender has to be located in Germany or Austria
  • The recipient has to be located in Germany or Austria
  • You’ll have to use your own contract with the carrier
  • Only available when using GLS Web API integration
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "cash_on_delivery",
      "properties": {
        "amount": 123.45,
        "currency": "EUR",
        "reference1": "reason for transfer"
      }
    }
  ],
  "carrier": "gls",
  "create_shipping_label": true
}

GLS - FlexDeliveryService

The FlexDeliveryService gives recipients numerous possibilities to customise parcel delivery. […] The recipient gets information via e-mail about the upcoming parcel delivery, including the estimated delivery time frame. If the recipient will not be at home, he can choose from a range of practical delivery options – actively influencing the delivery of the parcel.

Requirements:

  • service has to be standard
  • properties.email is mandatory
  • Can be used for shipments from Austria, Belgium, Denmark and Germany to the following countries: AT, BE, CZ, DE, DK, ES, FR, HR, HU, LU, NL, PL, RO, SI, SK
  • Only available when using GLS Web API integration
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "advance_notice",
      "properties": {
        "email": "test@example.com",
        "sms": "+4917012345678"
      }
    }
  ],
  "service": "standard",
  "carrier": "gls",
  "create_shipping_label": true
}

GLS - Guaranteed24Service

When using the additional service Guaranteed24Service the carrier GLS is guaranteeing delivery on the next business day (except Saturdays) for shipments within Germany. If the delivery can’t be made within time, GLS will refund the extra charges for the service.

Requirements:

  • Only applicable for shipments within Germany
  • The sender and recipient have to be located in Germany
  • You’ll have to use your own contract with the carrier
  • Only available when using GLS Web API integration
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "gls_guaranteed24service"
    }
  ],
  "service": "standard",
  "carrier": "gls",
  "create_shipping_label": true
}

UPS - Adult signature

When sending packages via UPS you can specify that the receiver needs to be an adult, and prove the fact with his or her signature.

Requirements:

  • you’ll have to use your own contract with the carrier
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "ups_adult_signature"
    }
  ],
  "carrier": "ups",
  "service": "one_day",
  "create_shipping_label": true
}

UPS - Cash on delivery

Requirements:

  • only collection of cash is available for now, no collection of checks
  • you’ll have to use your own contract with the carrier
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "additional_services": [
    {
      "name": "cash_on_delivery",
      "properties": {
        "amount": 123.45,
        "currency": "EUR"
      }
    }
  ],
  "carrier": "ups",
  "create_shipping_label": true
}

DHL Packstation

When sending to a DHL Packstation the following parameters have to be defined:

  • care_of = customer id number (postnummer)
  • street_no = number of packstation
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    "first_name": "Hans",
    "last_name": "Meier",
    "care_of": "12345678",
    "street": "PACKSTATION",
    "street_no": "109",
    "city": "Hamburg",
    "zip_code": "20148",
    "country": "DE"
  },
  "package": {
    // see [2]
  },
  "carrier": "dhl",
  "create_shipping_label": true
}

DHL Postfiliale

When sending to a DHL post office the following parameters have to be defined:

  • care_of = customer id number (postnummer)
  • street_no = number of the Postfiliale outlet
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    "first_name": "Hans",
    "last_name": "Meier",
    "care_of": "1234567",
    "street": "POSTFILIALE",
    "street_no": "515",
    "city": "Hamburg",
    "zip_code": "20148",
    "country": "DE"
  },
  "package": {
    // see [2]
  },
  "carrier": "dhl",
  "create_shipping_label": true
}

DHL additional insurance

With DHL additional insurance, you can insure your parcel beyond the usual liability limits of EUR 500. To book DHL additional insurance you’ll have to specify the parameter declared_value as part of the package object with the value of the goods you’re shipping.

Caution:

  • Please keep in mind that additional fees will be charged by DHL. Check your DHL contract or ask your DHL Account Manager to get a quote.
  • You shouldn’t specify “declared_value” when creating a shipment up to EUR 500 or lesser value unless you actually want the insurance instead of the liability.

Requirements:

  • You’ll have to use your own DHL contract
{
  "package": {
    // see packages [2]
    "declared_value": {
       "amount": 555.45,
       "currency": "EUR"
     }
  }
}

DHL bulk shipments

Shipments that don’t fall into the normal dimensions can be send by specifying them as bulk items when sending via DHL. When doing this you won’t have to specify the length, width or height of your package.

Requirements:

  • package.type has to be ‘bulk’
  • you’ll have to use your own contract with the carrier
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    "weight": 5.5,
    "length": 25,
    "width": 36,
    "height": 5,
    "type": "bulk"
  },
  "carrier": "dhl",
  "create_shipping_label": true
}

DPD parcel letter

DPD defines parcel letters as “everything which is too small for a parcel but larger and heavier than a classical letter”

Requirements:

  • package.type has to be ‘parcel_letter’
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    "weight": 0.5,
    "length": 25,
    "width": 36,
    "height": 5,
    "type": "parcel_letter"
  },
  "carrier": "dpd",
  "service": "standard",
  "create_shipping_label": true
}

Deutsche Post Büchersendung

You can send books, brochures, sheets of music and maps using the service Büchersendung by Deutsche Post AG.

Requirements:

  • package.type has to be ‘books’
  • carrier has to be ‘dpag’
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    "weight": 0.5,
    "length": 25,
    "width": 18,
    "height": 5,
    "type": "books"
  },
  "carrier": "dpag",
  "service": "standard",
  "create_shipping_label": true
}

Deutsche Post Brief

If you want to send a simple letter using the Deutsche Post AG services you can do that as well.

Requirements:

  • package.type has to be ‘letter’
  • carrier has to be ‘dpag’
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    "weight": 0.5,
    "length": 14,
    "width": 10,
    "height": 0.3,
    "type": "letter"
  },
  "carrier": "dpag",
  "service": "standard",
  "create_shipping_label": true
}

Deutsche Post Warensendung

You can send a variety of merchandise related things to your customers using the service Warensendung by Deutsche Post AG.

Requirements:

  • package.type has to be ‘parcel_letter’
  • carrier has to be ‘dpag’
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    "weight": 0.8,
    "length": 20,
    "width": 20,
    "height": 5,
    "type": "parcel_letter"
  },
  "carrier": "dpag",
  "service": "standard",
  "create_shipping_label": true
}

GLS - ShopDeliveryService

GLS delivers parcels (except tyres) directly to a ParcelShop. Recipients select in advance the ParcelShop to which the parcel should be sent. Once parcels have arrived, GLS informs recipients by e-mail or text message. They can collect their parcels from the GLS ParcelShop within the next eight working days after the day of delivery.

Requirements:

  • to.first_name is mandatory
  • to.last_name is mandatory
  • to.email is mandatory
  • drop_off_point.drop_off_point_id is mandatory (can be determined through the GLS parcelshop search)
  • drop_off_point.type has to be parcel_shop
  • The sender has to be located in Austria, Belgium or Germany
  • The recipient has to be located in one of the following countries: AT, DE, BE, DK, PL
  • Only available when using GLS Web API integration
POST https://api.shipcloud.io/v1/shipments
{
  "to": {
    "first_name": "Karl",
    "last_name": "Müller",
    "street": "Musterstraße",
    "street_no": "14a",
    "city": "Paderborn",
    "zip_code": "33089",
    "country": "DE",
    "email": "receiver@mail.com",
    "phone": "0151-12345678",
    "drop_off_point": {
      "drop_off_point_id": "2760095246",
      "type": "parcel_shop"
    }
  },
  "package": {
    "weight": 1.5,
    "length": 20,
    "width": 20,
    "height": 20
  },
  "service": "standard",
  "carrier": "gls",
  "label": {
    "size": "A5"
  },
  "create_shipping_label": true
}

Returns

Return shipments are created the same way you’d create a normal shipment. The only thing that’s different is the service parameter and that you can’t use (additional) services like express shipping.

Requirements:

  • service has to be ‘returns’
  • carrier can be ‘dhl’, ‘ups’, ‘hermes’ or ‘dpd’
POST https://api.shipcloud.io/v1/shipments
{
  "from": {
    // see [1]
  },
  "to": {
    // see [1]
  },
  "package": {
    // see [2]
  },
  "carrier": "dhl",
  "service": "returns",
  "create_shipping_label": true
}

Working with addresses

You can create a new address object by POSTing to our ADDRESS endpoint

POST /addresses
{
  "first_name": "Maxi",
  "last_name": "Mustermann",
  "street": "Mittelweg",
  "street_no": "158a",
  "zip_code": "20148",
  "city": "Hamburg",
  "country": "DE"
}

The response will look like this:

{
  "company": null,
  "first_name": "Maxi",
  "last_name": "Mustermann",
  "care_of": null,
  "street": "Mittelweg",
  "street_no": "158a",
  "zip_code": "20148",
  "city": "Hamburg",
  "state": null,
  "country": "DE",
  "phone": null,
  "id": "10b10652-570b-4bc3-9e14-dab0b51b075f"
}

As you can see, the response contains a unique id for this address, which you can use to create shipments

POST /shipments
{
  "carrier":"DHL",
  "to": {
    "id": "10b10652-570b-4bc3-9e14-dab0b51b075f"
  },
  "package": {
    // see [2]
  },
  "carrier": "dhl",
  "create_shipping_label": true
}

pakadoo

pakadoo is a service that lets you receive personal packages at work. For this a so called pakadoo point is being installed in your companies office rooms. For more information visit http://www.pakadoo.de

There are 2 ways you can create a shipment that’s going to be send to a pakadoo point:

  • create an address and use the id that’s returned for the address to create a shipment
  • create a shipment by specifying the pakadoo ID in the to address object of the shipments call.

In both cases you can either specify the pakadoo ID as pakadoo_id or you simply use the care_of attribute with “PAK” as a prefix to the pakadoo ID (e.g “PAK 5KQTPH5”).

Create a pakadoo address and shipment using the pakadoo_id

If the pakadoo user has been identified, shipcloud will return an address object, containing the currently selected delivery address for said pakadoo user.

Create Address Request

POST /addresses
{
  "pakadoo_id": "5KQTPH5"
}

Create Address Response

{
  "id": "71f2522f-be6f-4606-8eda-67997edfe2ac",
  "pakadoo_id": "5KQTPH5",
  "company": "LGI GmbH",
  "street": "Hewlett-Packard-Str.",
  "street_no": "1/1",
  "zip_code": "71083",
  "city": "Herrenberg",
  "country": "DE"
}

Like with every other address you can then use its unique address id to create a new shipment with it.

Create Shipment Request

POST /shipments
{
  "from": {
    // see [1]
  }
  "to": {
    "id": "71f2522f-be6f-4606-8eda-67997edfe2ac"
  },
  "package": {
    // see [2]
  },
  "carrier": "dhl",
  "create_shipping_label": true,
  "metadata": {
    "pakadoo": {
      "shop_name": "The shopname",
      "order_number": "123456",
      "order_date": "2015-06-01",
      "e_mail_shop": "user@example.com",
      "order_total": {
        "amount": 42.12,
        "currency": "EUR"
      }
    }
  }
}

Create a shipment using the pakadoo ID in the care_of attribute

You can use this if e.g. you don’t want to amend your checkout process. Your customers can use your existing address form to specify the pakadoo point address by entering their pakadoo ID in the care_of field (e.g. “PAK 5KQTPH5”).

We’re checking the care_of attribue for the “PAK” prefix. If it’s found, we then check if a valid pakadoo userid is present, validate it using the pakadoo system and return the users’ selected pakadoo point address, if available.

Notice: Any additional “to” address information given in the request will be replaced by what is returned from the pakadoo system.

Create Shipment Request

POST /shipments
{
  "from": {
    // see [1]
  }
  "to": {
    "care_of": "PAK 5KQTPH5",
    "company": "LGI GmbH",
    "street": "Hewlett-Packard-Str.",
    "street_no": "1/1",
    "zip_code": "71083",
    "city": "Herrenberg",
    "country": "DE",
  },
  "package": {
    // see [2]
  },
  "carrier": "dhl",
  "create_shipping_label": true,
  "metadata": {
    "pakadoo": {
      "shop_name": "The shopname",
      "order_number": "123456",
      "order_date": "2015-06-01",
      "e_mail_shop": "user@example.com",
      "order_total": {
        "amount": 42.12,
        "currency": "EUR"
      }
    }
  }
}

Footnotes

[1] Addresses

{
  "company": "Gewuerze Paderborn",
  "first_name": "Karl",
  "last_name": "Müller",
  "street": "Musterstraße",
  "street_no": "14a",
  "city": "Paderborn",
  "zip_code": "33089",
  "country": "DE"
}

[2] Packages

{
  "weight": 1.5,
  "length": 10,
  "width": 6,
  "height": 8
}

Notice: At the moment we’re only supporting sending a single package with one shipment. Our api responses however return an array to be able to switch to sending multiple packages with a single shipment in the future