API documentation Parcels

Contents

Get parcel information

Provides all available information about a parcel.

Endpoint

[GET] /v4/parcels/{client_ref}

Attributes

Key Description Datatype Constraints/Remarks
ref ViaEurope reference of parcel String Always 'VIA-', followed by a unique combination of 8 letters and numbers
client_ref Client reference of parcel String 5-30 characters, must only contain characters A-Z, 0-9, minus and underscore
order_client_ref Client reference of order String 5-30 characters, must only contain characters A-Z, 0-9, minus and underscore
barcode Barcode of parcel String
state State of parcel String Can be
  • pending
    parcel has not arrived at eHub yet
  • at_ehub
    parcel is at our eHub, but not ready to be handed over
  • handed_over
    parcel is handed over to the courier and has left our eHub
first_ehub_scan_at Timestamp of parcel's first scan at our eHub Timestamp
most_recent_ehub_scan_at Timestamp of parcel's most recent scan at our eHub Timestamp
type Type of parcel String See create attributes for a description of parcel types
packaging_type Packaging Type of parcel String See create attributes for a description of parcel types
ehub_scan_weight Parcel weight, determined by scale in our eHub, in grams Integer
ehub_scan_dimensions Parcel dimensions, determined by measuring device in our eHub, in cm Array of integers

Example

Response

{
  "ref": "VIA-G0000000",
  "client_ref": "CLIENTREF-001",
  "order_client_ref": "ORDER-123",
  "barcode": "1Z97V8800000000000",
  "state": "handed_over",
  "first_ehub_scan_at": "2018-11-04 15:47:37 +0100",
  "most_recent_ehub_scan_at": "2018-11-04 15:56:05 +0100",
  "type": "regular",
  "ehub_scan_weight": 18500,
  "ehub_scan_dimensions": [
    63,
    54,
    39
  ]
}

Create Parcel

Creates a new parcel 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

Attributes

Key Description Datatype Constraints/Remarks Error messages
client_ref Client reference of parcel String 5-30 characters, must only contain characters A-Z, 0-9, minus and underscore
  • Client ref is too short (minimum is 5 characters)
  • Client ref is too long (maximum is 30 characters)
  • Client ref has already been taken
  • Client ref must only contain characters A-Z, 0-9, minus and underscore
barcode Barcode of parcel String 5-50 characters, must be unique, must be provided if no delivery is booked through ViaEurope
  • Barcode can't be blank (for flat parcels, if no declarations submitted)
  • Barcode can't be set (for regular and bulk parcels, if no declarations submitted)
  • Barcode is too short (minimum is 5 characters)
  • Barcode is too long (maximum is 50 characters)
  • Barcode has already been taken
type Type of parcel String Can be regular (normal parcel), bulk (bulk parcel), or flat (flat/small parcel contained in bulk parcel)
  • Type can't be blank
  • Type has an invalid value
packaging_type Packaging Type of parcel (only for bulk type parcels) String Can be bag, box gaylord
  • Packing Type can't be blank
  • Packaging Type has an invalid value
order_client_ref Client reference of order String 5-30 characters, must only contain characters A-Z, 0-9, minus and underscore
  • Order client ref is too short (minimum is 5 characters)
  • Order client ref is too long (maximum is 30 characters)
  • Order client ref must only contain characters A-Z, 0-9, minus and underscore
waybill_client_ref Client reference of waybill String
  • Waybill client ref is unknown
bulk_parcel_client_ref Client reference of bulk parcel containing this parcel. Can only be used with "type"="flat" String
  • Bulk parcel client ref is unknown
  • Bulk parcel must be blank (if type isn't 'flat')
expected_flat_parcels_count Number of flat parcels assigned to this bulk parcel. Integer Only for parcels of type bulk . This field is optional.
  • Expected flat parcels count is not a number
inspected_by_client Indicates whether client performed an inspection before sending off the parcel Boolean
handed_over_by_client_at Time of handover from client to transportation company at origin. ISO8601
declaration Attributes for the declaration of this parcel, see here JSON
  • Declarations must be blank (if type is 'bulk')
delivery Attributes for the delivery of this parcel, see here JSON

Example: Create regular parcel

Request

{
  "type": "regular",
  "client_ref": "CLIENT123",
  "order_client_ref": "ORDER123",
  "inspected_by_client": true,
  "handed_over_by_client_at": "2018-10-08T13:20:55+02:00",
  "waybill_client_ref": "180-12345675",
  "delivery": {
    "address": {
      "name1": "Mr Appleseed",
      "street": "Example Street 1",
      "city": "Example City",
      "zip": "10001",
      "country": "DE",
      "phone": "0049123456"
    },
    "service": "UPS_BE_MULTI",
    "weight": 11000,
    "dimensions": [
      30,
      20,
      45
    ]
  },
  "declaration": {
    "type": "sale_b2c_4",
    "country_of_export": "CN",
    "origin_client_ref": "FOOBAR",
    "declaration_country": "NL",
    "consignee": {
      "name1": "Mr Appleseed",
      "street": "Example Street 1",
      "city": "Example City",
      "zip": "12345",
      "country": "FR",
      "phone": "0044123456"
    },
    "products": [
      {
        "description": "Beard Trimmer",
        "taric": "1234567890",
        "base_value": 17990,
        "quantity": 10,
        "weight": 10000,
        "country_of_origin": "CN",
        "marketplace_url": "https://www.amazon.co.uk/dp/B07BHXZLZR"
      },
      {
        "description": "Ballpoint Pen",
        "taric": "1234567890",
        "base_value": 1400,
        "quantity": 150,
        "weight": 1000,
        "country_of_origin": "CN",
        "marketplace_url": "https://www.amazon.co.uk/dp/B000I5ZK2U"
      }
    ]
  }
}

Example: Create bulk parcel

Request

{
  "type": "bulk",
  "packaging_type": "gaylord",
  "client_ref": "BULK123",
  "waybill_client_ref": "180-12345675",
  "expected_flat_parcels_count": 69,
  "delivery": {
    "address": {
      "name1": "Mr Appleseed",
      "shortcode": "DE44145",
      "phone": "0044123456"
    },
    "service": "BEX",
    "weight": 10000,
    "dimensions": [
      10,
      20,
      30
    ]
  }
}

Example: Create flat parcel with declaration

Request

{
  "type": "flat",
  "barcode": "123456",
  "client_ref": "CLIENT123",
  "bulk_parcel_client_ref": "BULK123",
  "declaration": {
    "consignee": {
      "name1": "ViaEurope BV",
      "street": "Pudongweg 21",
      "zip": "1437EM",
      "country": "NL",
      "city": "Rozenburg"
    },
    "type": "sale_b2c_4",
    "origin_client_ref": "FOOBAR",
    "country_of_export": "CN",
    "declaration_country": "NL",
    "ioss_number": "VIAIOSS-11AA22BB",
    "products": [
      {
        "description": "Carpenter Hammer",
        "taric": "1234567890",
        "base_value": 1199,
        "quantity": 10,
        "weight": 1500,
        "country_of_origin": "CN",
        "marketplace_url": "http://www.amazon.de",
        "client_ref": "XIYAR123"
      }
    ]
  }
}

Example: Create flat parcel with declaration and delivery

Request

{
  "type": "flat",
  "client_ref": "CLIENT123",
  "bulk_parcel_client_ref": "BULK123",
  "delivery": {
    "address": {
      "name1": "Mr Appleseed",
      "street": "Example Street 1",
      "city": "Example City",
      "zip": "1066 VH",
      "country": "NL",
      "phone": "0044123456"
    },
    "service": "PEDDLER",
    "weight": 500,
    "dimensions": [
      16,
      11,
      2
    ]
  },
  "declaration": {
    "consignee": {
      "name1": "ViaEurope BV",
      "street": "Pudongweg 21",
      "zip": "1437EM",
      "country": "NL",
      "city": "Rozenburg"
    },
    "type": "sale_b2c_4",
    "origin_client_ref": "FOOBAR",
    "country_of_export": "CN",
    "ioss_number": "VIAIOSS-11AA22BB",
    "declaration_country": "NL",
    "products": [
      {
        "description": "Carpenter Hammer",
        "taric": "1234567890",
        "base_value": 1199,
        "quantity": 10,
        "weight": 1500,
        "country_of_origin": "CN",
        "marketplace_url": "http://www.amazon.de"
      }
    ]
  }
}

Update Parcel

Updates a parcel, identified by its client_ref. You must only send attributes along that you wish to update. Only a subset of the create attributes is allowed here. This endpoint has no response, other than a HTTP status code to indicate success or failure, along with possible errors.

Endpoint

[PATCH] /v4/parcels/{client_ref}

Attributes

Key Description Datatype Constraints/Remarks
waybill_client_ref Client reference of waybill String
bulk_parcel_client_ref Client reference of bulk parcel containing this parcel. String Can only be used for flat parcels.
order_client_ref Client reference of order String 5-30 characters, must only contain characters A-Z, 0-9, minus and underscore
  • Order client ref is too short (minimum is 5 characters)
  • Order client ref is too long (maximum is 30 characters)
  • Order client ref must only contain characters A-Z, 0-9, minus and underscore
inspected_by_client Indicates whether client performed an inspection before sending off the parcel Boolean
handed_over_by_client_at Time of handover from client to transportation company at origin. ISO8601

Example: assign parcel to waybill

Request

{
  "waybill_client_ref": "HKG-180415-01"
}

Example: unassign parcel from waybill

Request

{
  "waybill_client_ref": null
}

Add attachments

Endpoint

[POST] /v4/parcels/{client_ref}/attachments

Attributes

Key Description Datatype Constraints Errors
type The type of attachment to be uploaded. String Required, can be
  • atr
  • Type can't be blank
  • Type is not valid
filename Name under which the document will be saved. String Required,
/[a-z0-9\. -_]+\.(pdf|xls|xlsx)/i
must include file extension,
lower and upper case characters are allowed
  • Filename can't be blank
  • Filename is not acceptable
attachment_base64 Base64-encoded (compatible with RFC 4648) content of the attachment. String See below
  • Attachment can't be blank
  • Attachment size must be between 1KB and 1MB

Attachment file

In order to include your attachment file in JSON, follow these steps:

Example (add attachment to parcel)

{
  "type": "atr",
  "filename": "atr.pdf",
  "attachment_base64": "JVBERi0xLjQKJeTjz9IKMSAwIG9iag…"
}