API documentation Deliveries

Contents

Get delivery information

Provides all available information about a parcel's most recent delivery, such as the tracking code, the state, and a URL to download the label. Note that labels are generated asynchronously and may take up to one minute to be available. Generally, labels are generated between 1 and 5 seconds after the delivery is created.

We recommend implementing a retry strategy with exponential backoff in case the label is not available yet. For example, if the label is not available yet, retry after 1 second, then 2 seconds, then 4 seconds, etc. until the label is available.

Endpoint

[GET] /v4/parcels/{client_ref}/delivery

Attributes

Key Description Datatype Constraints
courier Name of courier String
first_ehub_scan_at Timestamp of delivery's first scan at our eHub Timestamp
delivered_at Timestamp of parcel's delivery at the consignee String
label_url URL where the PDF version of the label can be downloaded String
rejection_reason Reason for courier rejecting delivery data String
state State of delivery String Can be
  • generating_label
    delivery data has not been transmitted to the courier yet, and a label is not available yet
  • rejected_by_courier
    delivery data has been rejected by the courier. You must resolve the issues mentioned in rejection_reason and create a new delivery to proceed
  • pending
    delivery has not been scanned at our eHub yet
  • at_courier
    parcel was scanned by the courier, and is currently underway
  • delivered
    parcel is delivered at consignee or parcel shop
  • returned
    parcel has returned to our eHub
  • canceled
    delivery has been canceled. You must create a new delivery to proceed
tracking_code Parcel tracking code, as assigned by the courier String
label_text The label text is a simplified indicator of the destination of the parcels used internally by ViaEurope String

Example

Response

{
  "courier": "UPS",
  "delivered_at": null,
  "first_ehub_scan_at": "2018-11-04T15:47:37.000+01:00",
  "label_download_url": "https://…",
  "rejection_reason": null,
  "state": "at_courier",
  "tracking_code": "1Z30RF786800000000",
  "label_text": null,
  "shipment_reference": "VIALH-828A9FE2"
}

Create new delivery

Creates a new delivery in the ViaEurope system. This endpoint has no response, other than a HTTP status code to indicate success or failure, along with possible errors.

Endpoint

[POST] /v4/parcels/{client-ref}/delivery

Attributes

Key Description Datatype Constraints Errors
service Courier & service to use String Must be a valid service for the given address shortcode and parcel type. Valid address shortcodes per parcel type and service are available via our app and Address Shortcode API, e.g. DPD_NL (for regular parcels only) or COLLISSIMO (for flat parcels only)
  • Service is not included in the list
additional_label_text Additional reference to print on label String Optional. Maximum 30 characters, must only contain characters A-Z, 0-9, minus and underscore
  • Additional label text must only contain characters A-Z, 0-9, minus and underscore
  • Additional label text is too long (maximum is 30 characters)
weight Weight of parcel Integer Must be greater than 0. Must be in grams, e.g. 21500 for 21.5 kg. Please note that different couriers and services impose different weight limits on parcels. Exceeding these limits may cause surcharges to be levied by the courier, and by ViaEurope.
  • Weight can't be blank
  • Weight is not a number
  • Weight must be an integer
  • Weight must be greater than 0
  • Weight must be less than or equal to 30000
dimensions Dimensions of parcel Array of integers Must be in centimeters. Must have three sides, e.g. [21, 15, 10] Please note that different couriers and services impose different dimension limits on parcels. Exceeding these limits may cause surcharges to be levied by the courier, and by ViaEurope.
  • Dimensions can't be blank
tracking_code Tracking code String Only for services * BEX and UPS_PREBOOKED. For the UPS_PREBOOKED service, it has to be a unique value across the last 90 days. * Only allowed clients can set tracking code on BEX
  • Tracking code can't be blank
  • Tracking code has already been taken
address Attributes for the delivery address JSON
  • Address must exist
  • Country is not supported for this service
  • Address is outside EU VAT area
  • Address zip and country combination not supported for this service
shortcode Name String Optional. An alternative to passing full address parameters. When submitting address data, it's possible to send only shortcode and name1, and the rest of the attributes (name2, street, city, zip, country) will be selected and assigned by matching the shortcode.
  • Shortcode and address data do not match. You can leave out name2, street, city, zip, country when using a shortcode
  • Shortcode is not included in the list
name1 Name String Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name1 can't be blank
  • Name1 is too long (maximum is 35 characters)
  • Name1 must only contain latin or printable ASCII characters
  • Name1 must not contain multiple lines
name2 Name (continued) String Optional. Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name2 must only contain latin or printable ASCII characters
  • Name2 is too long (maximum is 35 characters)
  • Name2 must not contain multiple lines
street Street String Maximum 70 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks. Must not contain zip code. Must not contain city.
  • Street can't be blank
  • Street is too long (maximum is 70 characters)
  • Street must not contain city, building, or company name
  • Street must only contain latin or printable ASCII characters
  • Street must not contain multiple lines
city City String 2-35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • City can't be blank
  • City is too short (minimum is 2 characters)
  • City is too long (maximum is 35 characters)
  • City must only contain latin or printable ASCII characters
  • City must not contain multiple lines
country Country String 2 character ISO 3166-Alpha 2 country code. See Countries list for more information.
  • Country can't be blank
  • Country is unknown or not supported
  • Country is invalid
zip Zip String Zipcode associated with the address
  • ZIP can't be blank
  • ZIP has invalid format (country-specific)
email Email of recipient String Optional. Maximum 50 characters
  • Email can't be blank
  • Email is not a valid email address
  • Email is too long (maximum is 50 characters)
phone Phone number String Optional. Maximum 15 characters. Must only contain characters 0-9, plus and minus.
  • Phone can't be blank
  • Phone must only contain characters 0-9, plus and minus
  • Phone is too long (maximum is 25 characters)

Example

Request

{
  "additional_label_text": null,
  "address": {
    "name1": "Mr Appleseed",
    "name2": "The Fruit Company, Building A",
    "street": "Example Street 1",
    "city": "Example City",
    "zip": "12345",
    "country": "DE",
    "phone": "0044123456"
  },
  "service": "DPD_BE_B2B",
  "weight": 10000,
  "dimensions": [
    12,
    24,
    36
  ]
}

Cancel delivery

Will cancel the parcel's most recent delivery. This cannot be undone! This endpoint has no response, other than a HTTP status code to indicate success or failure, along with possible errors.

Endpoint

[DELETE] /v4/parcels/{client_ref}/delivery