Recipes

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

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
}

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": {
    "company": "shipcloud GmbH",
    "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": {
    "company": "shipcloud GmbH",
    "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 higher insurance

If you want your DHL shipment to have a so called higher 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. All shipments up to 500 Euros are automatically insured. You shouldn’t specify declared_value when creating a shipment of lesser value.

{
  "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,
    "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
}

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

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:

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
}

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

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
}

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


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