Hermes @ shipcloud

Services

Standard

The most basic service. Normal ground shipping without any modifier to speed up the shipping time.

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "package": {
    "weight": 0.5,
    "length": 20,
    "width": 15,
    "height": 5,
    "type": "parcel"
  },
  "carrier": "hermes",
  "service": "standard",
  "create_shipping_label": true
}

Returns

A shipment that the customer sends back to the store / sender

Notice:

We're also providing the option to create a QR code returns voucher. See QR code returns for all the details.

Show example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "to": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "package": {
    "weight": 0.5,
    "length": 20,
    "width": 15,
    "height": 5,
    "type": "parcel"
  },
  "carrier": "hermes",
  "service": "returns",
  "create_shipping_label": true
}

Package types

Bulk

Shipments that don't fall into the normal dimensions can be send by specifying them as bulk items when sending via hermes.

Requirements:

package.type has to be bulk
you'll have to use your own contract with the carrier

Show example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "package": {
    "weight": 5,
    "length": 180,
    "width": 15,
    "height": 5,
    "type": "bulk"
  },
  "carrier": "hermes",
  "service": "standard",
  "create_shipping_label": true
}

Parcel

The most basic package type for shipping parcels there is.

Show example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "package": {
    "weight": 0.5,
    "length": 20,
    "width": 15,
    "height": 5,
    "type": "parcel"
  },
  "carrier": "hermes",
  "service": "standard",
  "create_shipping_label": true
}

Additional services

Cash on delivery

Requirements:

you'll have to use your own contract with the carrier
Sender and recipient have to be located in Germany.
The currency has to be EUR

Show example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "company": "Receiver AG",
    "care_of": "3. Liftstock",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "package": {
    "weight": "2.5",
    "length": "40",
    "width": "20",
    "height": "10",
    "type": "parcel"
  },
  "service": "standard",
  "carrier": "hermes",
  "additional_services": [
    {
      "name": "cash_on_delivery",
      "properties": {
        "amount": 123.45,
        "currency": "EUR"
      }
    }
  ],
  "create_shipping_label": true
}

Customer alert

When using the additional service Hermes customer alert you are requesting Hermes to notify your customers of a pending delivery by contacting them directly either via email or SMS.

Requirements:

you'll have to use your own contract with the carrier

Show notification via email example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "company": "Receiver AG",
    "care_of": "3. Liftstock",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "package": {
    "weight": "2.5",
    "length": "40",
    "width": "20",
    "height": "10",
    "type": "parcel"
  },
  "service": "standard",
  "carrier": "hermes",
  "additional_services": [
    {
      "name": "advance_notice",
      "properties": {
        "email": "receiver@mail.com"
      }
    }
  ],
  "create_shipping_label": true
}

Show notification via sms example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "company": "Receiver AG",
    "care_of": "3. Liftstock",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "package": {
    "weight": "2.5",
    "length": "40",
    "width": "20",
    "height": "10",
    "type": "parcel"
  },
  "service": "standard",
  "carrier": "hermes",
  "additional_services": [
    {
      "name": "advance_notice",
      "properties": {
        "sms": "+4917012345678"
      }
    }
  ],
  "create_shipping_label": true
}

EilService

To make sure that a shipment will be transported in the priority lane of the carrier, Hermes is providing its customers the additional service EilService. The carrier will try to make the delivery on the next business day (except Saturdays).

Requirements:

You have to use your own carrier contract
Applicable only for domestic shipments whithin Germany

Show example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "company": "Receiver AG",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "package": {
    "weight": "2.5",
    "length": "40",
    "width": "20",
    "height": "10",
    "type": "parcel"
  },
  "service": "standard",
  "carrier": "hermes",
  "additional_services": [
    {
      "name": "hermes_next_day"
    }
  ],
  "create_shipping_label": true
}

IdentService

You can have the carrier Hermes check the identity of a recipient by specifying this additional service (more details about the IdentService at the Hermes website). The shipment will be handed over to the recipient only if the data on the shipping label matches 100% to the shown ID.

Requirements:

You have to use your own carrier contract
id_type is mandatory and can be one of the following values: german_identity_card, german_passport, international_passport
id_number is mandatory
Applicable only for domestic shipments whithin Germany

Show example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "company": "Receiver AG",
    "care_of": "3. Liftstock",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "package": {
    "weight": "2.5",
    "length": "40",
    "width": "20",
    "height": "10",
    "type": "parcel"
  },
  "service": "standard",
  "carrier": "hermes",
  "additional_services": [
    {
      "name": "hermes_ident_check",
      "properties": {
        "id_type": "german_identity_card",
        "id_number": "ID123ABC"
      }
    }
  ],
  "create_shipping_label": true
}

Other attributes

Cover address

When sending parcels from a different location than what is specified by your contract, you can specify a so called "cover address" that will be printed on the label as the sender. This is especially useful for customers who are using a fulfillment provider for their shipments.

Requirements:

You have to use your own (Hermes HSI) carrier contract
The feature needs to be activated by Hermes
cover_address needs to be specified at the root level

Show example

POST https://api.shipcloud.io/v1/shipments

{
  "cover_address": {
    "company": "CoverCompany",
    "first_name": "CoverFirstName",
    "last_name": "CoverLastName",
    "care_of": "CoverCareOf",
    "street": "CoverStreet",
    "street_no": "99",
    "city": "CoverCity",
    "zip_code": "20148",
    "state": "CoverState",
    "country": "DE",
    "phone": "+4915112345678",
    "email": "cover@mail.com"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "company": "Receiver Ltd.",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "package": {
    "weight": "2.5",
    "length": "40",
    "width": "20",
    "height": "10",
    "type": "parcel"
  },
  "service": "standard",
  "carrier": "hermes",
  "create_shipping_label": true
}

ParcelShopDeliveryService

Requirements:

You have to use your own (Hermes HSI) carrier contract
drop_off_point.drop_off_point_id is mandatory (can be determined through the Hermes Website)
drop_off_point.type has to be parcel_shop

Options:

Hermes can notify the receiver via sms or email if you provide the additional service advance notice

Show example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "to": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "company": "Hermes Paketshop Schmidt",
    "care_of": "3. Liftstock",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE",
    "drop_off_point": {
      "drop_off_point_id": "660328",
      "type": "parcel_shop"
    }
  },
  "package": {
    "weight": "2.5",
    "length": "40",
    "width": "20",
    "height": "10",
    "type": "parcel"
  },
  "service": "standard",
  "carrier": "hermes",
  "create_shipping_label": true
}

QR code returns

If you want to enable your customers to reduce their carbon footprint or they do not own a printer, you can provide them with a QR code they can then show at their DHL station to get a returns label.

Notice:

In contrast to QR code returns from DHL and GLS where you always receive a QR code and a PDF returns label, the carrier Hermes only returns one or the other.

Requirements:

You'll have to use your own contract with the carrier
Only applicable for domestic returns within Germany

Show example

POST https://api.shipcloud.io/v1/shipments

{
  "from": {
    "first_name": "Roger",
    "last_name": "Receiver",
    "street": "Receiver Str.",
    "street_no": "1",
    "city": "Hamburg",
    "zip_code": "20535",
    "country": "DE"
  },
  "to": {
    "first_name": "Serge",
    "last_name": "Sender",
    "company": "Sender Corp.",
    "street": "Sender Str.",
    "street_no": "99",
    "zip_code": "20148",
    "city": "Hamburg",
    "country": "DE"
  },
  "package": {
    "weight": 0.5,
    "length": 20,
    "width": 15,
    "height": 5,
    "type": "parcel"
  },
  "label_voucher": {
    "type": "qr_code",
    "format": "png",
  },
  "carrier": "hermes",
  "service": "returns",
  "create_shipping_label": true
}

Label formats

PDF

DIN A5: pdf_a5
DIN A6: pdf_a6

Misc

Cutoff times

If the volume is below 2m³, you can request a pickup for the next day until 9pm the day before. If the volume exceeds this limit you'll have to request the pickup until 2pm the previous day.

Field lengths

shipments
- first_name: 0 - 20 characters
- last_name: 1 - 30 characters
- company: 0 - 20 characters
- care_of: 0 - 20 characters
- street: 1 - 27 characters
- street_no: 1 - 5 characters
- zip_code: 1 - 8 characters
- city: 1 - 30 characters

Hermes Shipping Interface

Services

Standard

Returns

Package types

Bulk

Parcel

Additional services

Cash on delivery

Customer alert

EilService

IdentService

Other attributes

Cover address

ParcelShopDeliveryService

QR code returns

Label formats

PDF

Misc

Cutoff times

Field lengths

shipments