shipcloud API v1

Changelog

If you haven't seen it already in the github-repo for this website - we've got a api changelog where you can see the changes we've made to our api.

OpenAPI specification

To make it easier to start a project based on or just talk to our API you can use our OpenAPI spec as JSON or simply view the OpenAPI specification in the browser.

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.

Creating an address

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

OpenAPIView the OpenAPI spec

Request

/v1/addresses

{
  "company": "Muster-Company",
  "first_name": "Max",
  "last_name": "Mustermann",
  "street": "Musterstraße",
  "street_no": "42",
  "zip_code": "54321",
  "city": "Musterstadt",
  "country": "DE",
  "email": "max@mustermann.baz",
  "phone": "+491234567890"
}

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",
  "email": "max@mustermann.baz",
  "phone": "+491234567890"
}

Getting a list of addresses

OpenAPIView the OpenAPI spec

Request

/v1/addresses

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

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",
      "email": "max@mustermann.baz",
      "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",
      "email": "tim.cook@apple.com",
      "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",
      "email": "max@mustermann.baz",
      "phone": null
    }
  ]
}

Show an Address

OpenAPIView the OpenAPI spec

Request

/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",
  "first_name": "Max",
  "last_name": "Mustermann",
  "street": "Musterstraße",
  "street_no": "42",
  "zip_code": "12345",
  "city": "Musterstadt",
  "country": "DE",
  "email": "max@mustermann.baz",
  "phone": "+491234567890"
}

Carriers

Get all carriers available for your account

OpenAPIView the OpenAPI spec

Request

/v1/carriers

no payload

Response

200 (OK)

[
  {
    "name": "dhl",
    "display_name": "Deutsche Post DHL",
    "services": [
      "standard",
      "returns"
    ],
    "package_types": [
      "parcel",
      "bulk"
    ],
    "additional_services": [
      "advance_notice"
    ],
    "label_formats": {
      "standard": ["pdf_a5", "pdf_a6", "pdf_103x199mm", "zpl2_103x199mm_203dpi"],
      "dhl_europaket": ["pdf_a5", "pdf_a6", "pdf_103x199mm", "zpl2_103x199mm_203dpi"],
      "returns": ["pdf_a5"],
      "dhl_prio": ["pdf_a5", "pdf_103x199mm", "zpl2_103x199mm_203dpi"],
      "dhl_warenpost": ["pdf_a5", "pdf_a7", "pdf_100x70mm", "pdf_103x199mm", "zpl2_103x199mm_203dpi", "zpl2_100x70mm_203dpi"]
    }
  },
  {
    "name": "dpag",
    "display_name": "Deutsche Post",
    "services": [
      "standard"
    ],
    "package_types": [
      "letter",
      "parcel_letter",
      "books"
    ],
    "additional_services": [
    ],
    "label_formats": {
      "standard": ["pdf_a5", "pdf_a6", "zpl2_4x6in_203dpi", "zpl2_4x6in_203dpi_td"],
      "dpag_warenpost": ["pdf_a5", "pdf_a6", "zpl2_4x6in_203dpi", "zpl2_4x6in_203dpi_td", "zpl2_a6_203dpi"],
      "dpag_warenpost_untracked": ["pdf_a5", "pdf_a6", "zpl2_4x6in_203dpi", "zpl2_a6_203dpi"],
      "dpag_warenpost_signature ": ["pdf_a5","pdf_a6","zpl2_4x6in_203dpi","zpl2_a6_203dpi"]
    }
  },
  {
    "name": "dpd",
    "display_name": "DPD - Dynamic Parcel Distribution",
    "services": [
      "standard",
      "returns",
      "one_day",
      "one_day_early"
    ],
    "package_types": [
      "parcel",
      "parcel_letter"
    ],
    "additional_services": [
      "advance_notice",
      "drop_authorization",
      "saturday_delivery"
    ],
    "label_formats": {
      "standard": ["pdf_a5", "pdf_a6"],
      "returns": ["pdf_a5", "pdf_a6"],
      "one_day": ["pdf_a5", "pdf_a6"],
      "one_day_early": ["pdf_a5", "pdf_a6"]
    }
  }
]

Default returns address

This is the default address that will be used for returns shipments when no address was specified using the to attribute.

OpenAPIView the OpenAPI spec

Request

/v1/default_returns_address

Response

200 (OK)

{
  "id": "1c81efb7-9b95-4dd8-92e3-cac1bca3df6f",
  "first_name": "Max",
  "last_name": "Mustermann",
  "street": "Musterstraße",
  "street_no": "42",
  "zip_code": "12345",
  "city": "Musterstadt",
  "country": "DE",
  "email": "max@mustermann.baz",
  "phone": "+491234567890"
}

Default shipping address

This is the default address that will be used for shipments when no address was specified using the to attribute.

OpenAPIView the OpenAPI spec

Request

/v1/default_shipping_address

Response

200 (OK)

{
  "id": "1c81efb7-9b95-4dd8-92e3-cac1bca3df6f",
  "first_name": "Max",
  "last_name": "Mustermann",
  "street": "Musterstraße",
  "street_no": "42",
  "zip_code": "12345",
  "city": "Musterstadt",
  "country": "DE",
  "email": "max@mustermann.baz",
  "phone": "+491234567890"
}

Invoice address

This is the address that a user has specified as being their invoice address.

OpenAPIView the OpenAPI spec

Request

/v1/invoice_address

Response

200 (OK)

{
  "first_name": "Max",
  "last_name": "Mustermann",
  "street": "Musterstraße",
  "street_no": "42",
  "zip_code": "12345",
  "city": "Musterstadt",
  "country": "DE"
}

me

If you need more details about the current user that is making a request, you can get it by querying the /me endpoint.

OpenAPIView the OpenAPI spec

Request

/v1/me

Response

200 (OK)

{
  "id": "usr-adaa123f",
  "email": "user@shipcloud.io",
  "customer_no": "123af01f",
  "environment":"production",
  "subscription": {
    "plan_name": "developer",
    "plan_display_name": "Developer",
    "chargeable": false
  }
}

Orders

By creating orders you can send shipcloud your order data with details about what your customer has ordered. After creating an order, you can create an association between shipments and orders by providing the order_id upon creating a shipment.

This is especially useful if you want to use our Return Portal Plus where the customer can tell you, which items they are going to return.

Create an order

OpenAPIView the OpenAPI spec

Request

/v1/orders

{
  "placed_at": "2022-01-12T13:39:03+01:00",
  "refundable_until": "2022-05-18T12:30:15+01:00",
  "external_order_id": "8709500.00.01",
  "external_customer_id": "27597435",
  "total_price": 186.85,
  "total_vat": 0,
  "currency": "EUR",
  "total_weight": 0.9,
  "weight_unit": "kg",
  "delivery_address": {
    "company": "Company",
    "first_name": "Firstname",
    "last_name": "Lastname",
    "street": "Street",
    "street_no": "Streetno",
    "zip_code": "54321",
    "city": "City",
    "country": "DE"
  },
  "order_line_items": [
    {
      "sku": "656006",
      "title": {
        "de": "Item Name",
        "en": "Item Name",
        "fallback": "Item Name"
      },
      "quantity": 1,
      "price": 89.95,
      "vat": 14.36,
      "currency": "EUR",
      "weight": 0.45,
      "weight_unit": "kg",
      "item_info": [
        {
          "name": {
            "de": "Farbe",
            "en": "Color",
            "fallback": "Farbe"
          },
          "value": {
            "de": "blue-used",
            "en": "blue-used",
            "fallback": "blue-used"
          }
        },
        {
          "name": {
            "de": "Größe",
            "en": "Size",
            "fallback": "Größe"
          },
          "value": {
            "fallback": "40"
          }
        }
      ]
    },
    {
      "sku": "655999",
      "title": {
        "de": "Item Name",
        "en": "Item Name",
        "fallback": "Item Name"
      },
      "quantity": 1,
      "price": 89.95,
      "vat": 14.36,
      "currency": "EUR",
      "weight": 0.45,
      "weight_unit": "kg",
      "item_info": [
        {
          "name": {
            "de": "Farbe",
            "en": "Color",
            "fallback": "Farbe"
          },
          "value": {
            "de": "dark-denim",
            "en": "dark-denim",
            "fallback": "dark-denim"
          }
        },
        {
          "name": {
            "de": "Größe",
            "en": "Size",
            "fallback": "Größe"
          },
          "value": {
            "fallback": "40"
          }
        }
      ]
    }
  ]
}

Response

200 (OK)

{
  "id": "feeb6d6a-dd57-4ade-9ef1-8123bed333f8",
  "placed_at": "2022-01-12T13:39:03+01:00",
  "refundable_until": "2022-05-18T12:30:15+01:00",
  "external_order_id": "8709500.00.01",
  "external_customer_id": "27597435",
  "total_price": 186.85,
  "total_vat": 0,
  "currency": "EUR",
  "total_weight": 0.9,
  "weight_unit": "kg",
  "delivery_address": {
    "id": "868b5b0b-a236-4a67-a531-b1b1d10e3361",
    "company": "Company",
    "first_name": "Firstname",
    "last_name": "Lastname",
    "care_of": null,
    "street": "Street",
    "street_no": "Streetno",
    "state": null,
    "zip_code": "54321",
    "city": "City",
    "country": "DE"
  },
  "order_line_items": [
    {
      "id": "ceec056e-5320-485f-8786-fb2ad3ed6005",
      "sku": "656006",
      "title": {
        "de": "Item Name",
        "en": "Item Name",
        "fallback": "Item Name"
      },
      "quantity": 1,
      "price": 89.95,
      "vat": 14.36,
      "currency": "EUR",
      "weight": 0.45,
      "weight_unit": "kg",
      "item_info": [
        {
          "name": {
            "de": "Farbe",
            "en": "Color",
            "fallback": "Farbe"
          },
          "value": {
            "de": "blue-used",
            "en": "blue-used",
            "fallback": "blue-used"
          }
        },
        {
          "name": {
            "de": "Größe",
            "en": "Size",
            "fallback": "Größe"
          },
          "value": {
            "fallback": "40"
          }
        }
      ]
    },
    {
      "id": "8123c919-f294-4253-ae26-e2ac812a82e4",
      "sku": "655999",
      "title": {
        "de": "Item Name",
        "en": "Item Name",
        "fallback": "Item Name"
      },
      "quantity": 1,
      "price": 89.95,
      "vat": 14.36,
      "currency": "EUR",
      "weight": 0.45,
      "weight_unit": "kg",
      "item_info": [
        {
          "name": {
            "de": "Farbe",
            "en": "Color",
            "fallback": "Farbe"
          },
          "value": {
            "de": "dark-denim",
            "en": "dark-denim",
            "fallback": "dark-denim"
          }
        },
        {
          "name": {
            "de": "Größe",
            "en": "Size",
            "fallback": "Größe"
          },
          "value": {
            "fallback": "40"
          }
        }
      ]
    }
  ]
}

Getting a list of previously created orders

OpenAPIView the OpenAPI spec

Request

/v1/orders

no payload

Response

200 (OK)

[
  {
    "id": "67aeb18a-f4ef-4d68-abb4-3aa309c71fa5",
    "placed_at": "2022-04-01T14:39:03+02:00",
    "refundable_until": "2022-05-18T12:30:15+01:00",
    "external_order_id": "Rechnung-1234",
    "external_customer_id": "Kunde-1234",
    "total_price": 186.85,
    "total_vat": 0.0,
    "currency": "EUR",
    "total_weight": 0.9,
    "weight_unit": "kg",
    "delivery_address": {
      "id": "4e56e24f-59f9-4c12-b373-0798279fa91f",
      "company": "Company",
      "first_name": "Firstname",
      "last_name": "Lastname",
      "street": "Street",
      "street_no": "42",
      "zip_code": "54321",
      "city": "City",
      "country": "DE"
    },
    "order_line_items": [
      {
        "id": "81d28907-ffc5-4868-80e3-24a247fc7798",
        "sku": "11223344",
        "title": {
          "de": "Toto - Africa",
          "en": "Toto - Africa",
          "default": "Toto - Africa"
        },
        "quantity": 1,
        "price": 10.95,
        "vat": 1.36,
        "currency": "EUR",
        "weight": 0.1,
        "weight_unit": "kg"
      },
      {
        "id": "e68f47d7-49e3-461d-aa80-fd04af70e4d5",
        "sku": "234567",
        "title": {
          "de": "Fast \u0026 Furious",
          "en": "Fast \u0026 Furious",
          "default": "Fast \u0026 Furious"
        },
        "quantity": 1,
        "price": 6.5,
        "vat": 0.36,
        "currency": "EUR",
        "weight": 0.2,
        "weight_unit": "kg"
      }
    ]
  },
  {
    "id": "c537be77-7ed1-431a-a69d-93407cb7db8e",
    "placed_at": "2022-01-12T13:39:03+01:00",
    "external_order_id": "Rechnung-5678",
    "external_customer_id": "Kunde-1234",
    "total_price": 186.85,
    "total_vat": 0.0,
    "currency": "EUR",
    "total_weight": 0.9,
    "weight_unit": "kg",
    "delivery_address": {
      "id": "6b2fbc32-4523-4a7a-9506-80ddfc448c49",
      "company": "Company",
      "first_name": "Firstname",
      "last_name": "Lastname",
      "street": "Street",
      "street_no": "42",
      "zip_code": "54321",
      "city": "City",
      "country": "DE"
    },
    "order_line_items": [
      {
        "id": "e880a792-baed-48f4-b079-2477eb17f068",
        "sku": "345678",
        "title": {
          "de": "Jeans",
          "en": "Jeans",
          "default": "Jeans"
        },
        "quantity": 1,
        "price": 89.95,
        "vat": 14.36,
        "currency": "EUR",
        "weight": 0.45,
        "weight_unit": "kg"
      },
      {
        "id": "2b3f9da9-8d0b-46f8-be27-76f9203a9836",
        "sku": "234567",
        "title": {
          "de": "Jacke",
          "en": "Jacket",
          "default": "Jacke"
        },
        "quantity": 1,
        "price": 89.95,
        "vat": 14.36,
        "currency": "EUR",
        "weight": 0.45,
        "weight_unit": "kg"
      }
    ]
  }
]

Getting information about an order

OpenAPIView the OpenAPI spec

Request

/v1/orders/:id

no payload

Response

200 (OK)

{
  "id": "feeb6d6a-dd57-4ade-9ef1-8123bed333f8",
  "placed_at": "2022-01-12T13:39:03+01:00",
  "refundable_until": "2022-05-18T12:30:15+01:00",
  "external_order_id": "8709500.00.01",
  "external_customer_id": "27597435",
  "total_price": 186.85,
  "total_vat": 0,
  "currency": "EUR",
  "total_weight": 0.9,
  "weight_unit": "kg",
  "delivery_address": {
    "id": "868b5b0b-a236-4a67-a531-b1b1d10e3361",
    "company": "Company",
    "first_name": "Firstname",
    "last_name": "Lastname",
    "care_of": null,
    "street": "Street",
    "street_no": "Streetno",
    "state": null,
    "zip_code": "54321",
    "city": "City",
    "country": "DE"
  },
  "order_line_items": [
    {
      "id": "ceec056e-5320-485f-8786-fb2ad3ed6005",
      "sku": "656006",
      "title": {
        "de": "Item Name",
        "en": "Item Name",
        "fallback": "Item Name"
      },
      "quantity": 1,
      "price": 89.95,
      "vat": 14.36,
      "currency": "EUR",
      "weight": 0.45,
      "weight_unit": "kg",
      "item_info": [
        {
          "name": {
            "de": "Farbe",
            "en": "Color",
            "fallback": "Farbe"
          },
          "value": {
            "de": "blue-used",
            "en": "blue-used",
            "fallback": "blue-used"
          }
        },
        {
          "name": {
            "de": "Größe",
            "en": "Size",
            "fallback": "Größe"
          },
          "value": {
            "fallback": "40"
          }
        }
      ]
    },
    {
      "id": "8123c919-f294-4253-ae26-e2ac812a82e4",
      "sku": "655999",
      "title": {
        "de": "Item Name",
        "en": "Item Name",
        "fallback": "Item Name"
      },
      "quantity": 1,
      "price": 89.95,
      "vat": 14.36,
      "currency": "EUR",
      "weight": 0.45,
      "weight_unit": "kg",
      "item_info": [
        {
          "name": {
            "de": "Farbe",
            "en": "Color",
            "fallback": "Farbe"
          },
          "value": {
            "de": "dark-denim",
            "en": "dark-denim",
            "fallback": "dark-denim"
          }
        },
        {
          "name": {
            "de": "Größe",
            "en": "Size",
            "fallback": "Größe"
          },
          "value": {
            "fallback": "40"
          }
        }
      ]
    }
  ]
}

Pickup requests

Requesting a 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.

OpenAPIView the OpenAPI spec

Request

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

/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:

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

Response

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

Getting a list of pickup requests

OpenAPIView the OpenAPI spec

Request

/v1/pickup_requests

no payload

Response

200 (OK)

{
  "pickup_requests": [
    {
      "id": "123467a6-8e15-4a59-e145-0953f31c1196",
      "carrier": "ups",
      "carrier_pickup_number": "299A80MA91P",
      "shipments": [
        {
          "id": "199f803bf82fab79e17654213b61993fa78b0524"
        }, {
          "id": "3a186c51d4281acbecf5ed38805b1db92a9d668b"
        }
      ],
      "pickup_date": "2018/10/26",
      "pickup_address": {
        "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",
        "email": null,
        "id": "7ea2a290-b456-4ecf-9010-e82b3da298f0"
      }
    }, {
      "id": "7342d2cc-416c-434f-a999-f7a845c64f1a",
      "carrier": "dpd",
      "carrier_pickup_number": "117639",
      "shipments": [
        {
          "id": "86afb143f9c9c0cfd4eb7a7c26a5c616585a6271"
        }, {
          "id": "be81573799958587ae891b983aabf9c4089fc462"
        }, {
          "id": "be598a2fd27304cf2d82669b197517623629d94e"
        }
      ],
      "pickup_date": "2018/10/23",
      "pickup_address": {
        "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",
        "email": null,
        "id": "522a7cb1-d6c8-418c-ac26-011127ab5bbe"
      }
    }
  ]
}

Getting information about a pickup request

OpenAPIView the OpenAPI spec

Request

/v1/pickup_requests/:id

no payload

Response

200 (OK)

{
    "id": "c28a4ec0-e1ae-47a6-acae-1349ff0da52a",
    "carrier": "dpd",
    "carrier_pickup_number": "9380",
    "shipments": [
        {
            "id": "604681675415e96052cf8fbaba78153a2e6d6bee"
        },
        {
            "id": "11acaa0c4f251aaac4889d5f10329eb1aed80ff2"
        },
        {
            "id": "9a5b91d766a523447c16897f8e20f4d7d06c25ca"
        }
    ],
    "pickup_time": {
        "earliest": "2018-07-30T09:00:00+02:00",
        "latest": "2018-07-30T18:00:00+02:00"
    },
    "pickup_address": {
        "company": "Muster-Company",
        "first_name": "Max",
        "last_name": "Mustermann",
        "care_of": null,
        "street": "Musterstraße",
        "street_no": "42",
        "zip_code": "22457",
        "city": "Hamburg",
        "state": null,
        "country": "DE",
        "phone": "555-555",
        "email": null,
        "id": "286daf26-c845-4dba-ae49-75582fbced00"
    }
}

Rates

Getting the rate for a package

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

Request

/v1/rates

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

Response

200 (OK)

{
  "rate": 3.80
}

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.

Creating a shipment

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

OpenAPIView the OpenAPI spec

Request

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

Response

200 (OK)

{
  "id": "3a186c51d4281acbecf5ed38805b1db92a9d668b",
  "carrier_tracking_no": "84168117830018",
  "tracking_url": "https://track.shipcloud.io/3a186c51d4",
  "label_url": "https://shipping-labels.shipcloud.io/shipments/01370b4d/199f803bf8/label/shipping_label_199f803bf8.pdf",
  "price": 3.4
}

Getting a list of shipments

OpenAPIView the OpenAPI spec

Request

/v1/shipments

no payload

You can filter the shipments list by using one or more of the following GET parameters.

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": "https://track.shipcloud.io/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": "https://track.shipcloud.io/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

OpenAPIView the OpenAPI spec

Request

/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": "https://shipping-labels.shipcloud.io/shipments/01370b4d/199f803bf8/label/shipping_label_199f803bf8.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": "https://track.shipcloud.io/3a186c51d4"
}

Updating a shipment

OpenAPIView the OpenAPI spec

Request

/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": "https://track.shipcloud.io/3a186c51d4",
  "label_url": "https://shipping-labels.shipcloud.io/shipments/01370b4d/199f803bf8/label/shipping_label_199f803bf8.pdf",
  "price": 3.4
}

Deleting a shipment

OpenAPIView the OpenAPI spec

Request

/v1/shipments/:id

no payload

URL parameters:

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

Response

204 (No Content)

{}

Shipment Quotes

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

Creating a shipment quote

OpenAPIView the OpenAPI spec

Request

/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.

Response

200 (OK)

{
  "shipment_quote": {
    "price": 42.12
  }
}

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.

Notice: Since we're always tracking shipments created using shipcloud contracts, trackers can only be used with your own carrier contracts.

Creating a tracker

This is the way to create a tracker based on a tracking number provided by one of our supported carriers. Not all carriers are providing the option to just track shipments. For a list of carriers please look at our Open API specification.

OpenAPIView the OpenAPI spec

Request

/v1/trackers

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

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": []
}

Getting a list of trackers

OpenAPIView the OpenAPI spec

Request

/v1/trackers

no payload

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

Request

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

Webhooks

The following is a section of resources related to webhooks.

Creating a webhook

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

OpenAPIView the OpenAPI spec

Request

/v1/webhooks

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

Response

200 (OK)

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

Getting a list of webhooks

OpenAPIView the OpenAPI spec

Request

/v1/webhooks

no payload

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

Request

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

Deleting a webhook

OpenAPIView the OpenAPI spec

Request

/v1/webhooks/:id

no payload

URL parameters:

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

Response

204 (No Content)

{}

Routing Rules

In addition to the traditional Ship journey, our API also supports the Checkout to Ship journey, providing a seamless solution for allowing customers to select their preferred carrier and service during the checkout process.

Getting available shipping options for a route

With this call you can find out which shipping options are available for the desired route and specific shipment.

Request

/v1/shipping_rule_tree_resolutions

{
  "version": "12345",
  "shipment_data": {
    "direction": "outbound",
    "from": {
      "company": "FromCompany",
      "care_of": "FromCareOf",
      "first_name": "FromFirstName",
      "last_name": "FromLastName",
      "street": "FromStreet",
      "street_no": "6",
      "zip_code": "54321",
      "city": "FromCity",
      "state": "FromState",
      "country": "DE",
      "phone": "123456789",
      "email": "from@example.com"
    },
    "to": {
      "company": "ToCompany",
      "care_of": "ToCareOf",
      "first_name": "ToFirstName",
      "last_name": "ToLastName",
      "street": "ToStreet",
      "street_no": "20",
      "city": "ToCity",
      "zip_code": "12345",
      "state": "ToState",
      "country": "DE",
      "phone": "123456789",
      "email": "to@example.com"
    },
    "package": {
      "height": "10",
      "length": "20",
      "width": "30",
      "weight": "5",
      "type": "parcel"
    }
  }
}

Response

200 (OK)

{
  "carrier_service_combinations": [
    {
      "carrier": "ups",
      "service": "standard",
      "carrier_display_name": "UPS",
      "service_display_name": "",
      "description": "Delivery within 1-2 business days",
      "checkout_shipping_price": "0",
      "pickup_dropoff": "true"
    },
    {
      "carrier": "dhl",
      "service": "standard",
      "carrier_display_name": "DHL",
      "service_display_name": "",
      "description": "Delivery within 1-2 business days",
      "checkout_shipping_price": "6.90",
      "pickup_dropoff": "true"
    },
    {
      "carrier": "dpd",
      "service": "standard",
      "carrier_display_name": "DPD",
      "service_display_name": "",
      "description": "Delivery within 1-2 business days",
      "checkout_shipping_price": "3.90"
    },
    {
      "carrier": "ups",
      "service": "one_day",
      "carrier_display_name": "UPS",
      "service_display_name": "Express",
      "description": "Expected delivery on the next business day",
      "checkout_shipping_price": "8.90",
      "pickup_dropoff": "true"
    },
    {
      "carrier": "ups",
      "service": "one_day_early",
      "carrier_display_name": "UPS",
      "service_display_name": "Express early",
      "description": "Expected delivery on the next business day before noon",
      "checkout_shipping_price": "14.90",
      "pickup_dropoff": "false"
    }
  ],
  "rule_tree_version": 2
}