Skip to main content

Shipping Parcels with Codept

When shipping parcels, supporting each individual parcel provider is a challenge: the providers have different APIs that don’t necessarily adhere to a single standard. Some parcel providers only open up API access to select customers.

By using Codept you can use any parcel provider without needing to implement a custom API integration with each of them. Codept provides a standard interface for you to request a package pickup, specify the measurements of a parcel, and print a label.

Codept tracks the status of all packages you ship and notifies you of all changes in the status by using asynchronous messages.

Which shipping providers are supported?#

Codept currently supports the following shipping providers in Germany and abroad:

  • DHL and DHL Express
  • GLS
  • DPD
  • UPS
  • Sieber
  • DHL 2MH (two-man handling)
  • VIR (two-man handling)

If you are interested in using Codept in other regions, please reach out to the Codept support team.

Supported services for each carrier#

DHL#

DHL supports standard and returns services.

DHL Express#

DHL Express supports only one_day service.

GLS#

GLS supports standard and one_day services.

DPD#

DPD supports standard, returns, one_day and one_day_early services.

Additionally, DPD supports advance_notice, drop_authorization and saturday_delivery additional services where:

  • advance_notice has one of these properties:
    • email and language
    • sms

Example of (part of) shipment order for DPD carrier with advance_notice additional service with email:

{
...
"parcels": [
{
"clientReferenceNumber":"reference-number#1",
"weight":1.23,
"length":2.32,
"width":3.12,
"height":1.02,
"carrier":{
"optimize":false,
"carrierName":"DPD",
"service":"standard",
"notificationEmail":"test@test.com",
"createShippingLabel":true
},
"description": "Test",
"additionalServices": [
{
"name": "advance_notice",
"properties": {
"email": "test@example.com",
"language": "en"
}
}
]
}
]
...
}

Example of (part of) shipment order for DPD carrier with advance_notice additional service with sms:

{
...
"parcels": [
{
"clientReferenceNumber":"reference-number#1",
"weight":1.23,
"length":2.32,
"width":3.12,
"height":1.02,
"carrier":{
"optimize":false,
"carrierName":"DPD",
"service":"standard",
"notificationEmail":"test@test.com",
"createShippingLabel":true
},
"description": "Test",
"additionalServices": [
{
"name": "advance_notice",
"properties": {
"sms": "+4917695363136"
}
}
]
}
]
...
}

UPS#

UPS supports only standard service.

Sieber#

Sieber supports:

  • standard service with assembly additional service
  • standard service with delivery additional service
  • standard service with pickup additional service
  • 2MH service with assembly additional service
  • 2MH service with delivery additional service
  • 2MH service with pickup additional service

Example of (part of) shipment order for Sieber carrier with assembly additional service where service is 2MH (two-man handling):

{
...
"parcels":[
{
"clientReferenceNumber":"11734885",
"weight":12.23,
"length":22.5,
"width":3.02,
"height":1.72,
"carrier":{
"optimize":false,
"carrierName":"sieber",
"service":"2MH",
"notificationEmail":"test@test.com",
"createShippingLabel":true
},
"additionalServices":[
{
"name":"assembly",
"assemblyTime":123,
"remark":"please assemble the desk"
}
]
}
]
...
}

DHL 2MH (two-man handling)#

DHL 2MH supports:

  • 2MH service with assembly additional service
  • 2MH service with delivery additional service

Example of (part of) shipment order for DHL 2MH carrier with assembly additional service where service is 2MH (two-man handling):

{
...
"parcels": [
{
"clientReferenceNumber": "I-206318-019-1-bm",
"weight": 56.75,
"length": 180,
"width": 95,
"height": 50,
"carrier": {
"optimize": false,
"carrierName": "DHL_2MH",
"service": "2MH",
"notificationEmail": "test@test.com",
"createShippingLabel": false
},
"additionalServices": [
{
"name": "assembly",
"assemblyTime": 60,
"remark":"please assemble the closet"
}
],
"description": "Furniture"
}
]
...
}

VIR (two-man handling)#

VIR supports:

  • 2MH service with assembly additional service
  • 2MH service with delivery additional service

Example of (part of) shipment order for VIR carrier with assembly additional service where service is 2MH (two-man handling):

{
...
"parcels": [
{
"clientReferenceNumber": "A-206318-020",
"weight": 56.75,
"length": 180,
"width": 95,
"height": 50,
"carrier": {
"optimize": false,
"carrierName": "vir",
"service": "2MH",
"notificationEmail": "test@test.com",
"createShippingLabel": false
},
"additionalServices": [
{
"name": "assembly",
"assemblyTime": 60,
"remark":"please assemble the closet"
}
],
"description": "Furniture"
}
]
...
}

Getting started with parcel shipping in Codept#

To ship a parcel with Codept you must use the Shipment Order API endpoint:

POST /api/v1/shipment/orders

Example payload for this endpoint.

Note: clientReferenceNumber should be unique.

See the Merchant API doc for more details on how to access Codept Merchant API endpoints and for a full list of available endpoints.

Any validation errors will be surfaced at the time of the API call.

The result of the Shipment Order API call will then be delivered to you using the messages mechanism of the Merchant API. The following is an example of a Shipment Order message:

{
"orderId":"orderId#60000",
"customerId":"customerId",
"merchantCodeptId":"MT_DE_2",
"senderAddress":{
"name":"Merchant",
"lastName":"Merchant Inc",
"additionalName":"merchantAdditionalName",
"companyName":"Merchant Inc",
"street":"Kollwitzstraße",
"street2":"Frankfurter Allee",
"houseNumber":"64",
"zip":"10115",
"city":"Berlin",
"state":"BE",
"country":"DE",
"postbox":"merchantPostbox",
"gpsLocation":"merchantGpsLocation",
"telephoneNumber":"+123456789"
},
"recipientAddress":{
"name":"John",
"lastName":"Doe",
"additionalName":"additionalName",
"companyName":"Codept",
"street":"Kollwitzstraße",
"houseNumber":"64",
"zip":"10435",
"city":"Berlin",
"state":"BE",
"country":"DE",
"postbox":"postbox",
"gpsLocation":"gpsLocation",
"telephoneNumber":"+4917695363136",
"addressRemark":"red door in the back yard"
},
"deliverySlipNumber":"LIEF14568973",
"parcels":[
{
"clientReferenceNumber":"reference-number#1",
"weight":1.23,
"length":2.32,
"width":3.12,
"height":1.02,
"carrier":{
"optimize":false,
"carrierName":"UPS",
"service":"standard",
"notificationEmail":"test@test.com",
"createShippingLabel":true
},
"description": "Test"
}
],
"labelSpecification":{
"labelFormat":"zpl"
}
}

Units#

The following units are used for the Shipment Orders endpoint:

  • weight of a parcel: kilograms;
  • dimensions of a parcel (length, width, height): centimeters.

Label specification#

Codept offers a way to specify in which format it will return labels. It is done using order labelSpecification field. Supported formats are:

  • zpl (base64 encoded zpl label)
  • standard ( base64 encoded PNG image)

Label data is returned in base64LabelImage field of parcel in shipment order response message.

For now, we only support labelSpecification for UPS carrier.

Common error messages and validations for shipping parcels#

Codept validates each call to the Shipment Orders endpoint through a series of conditions. If a condition is not met, an error is returned. Below is the list of all the validations Codept applies with their respective error messages:

Top-level validations#

These validations are applied to all calls.

  • Validate the carrier
    • validate that carrier is one of "DHL", "DHL_EXPRESS", "GLS", "DPD" or "UPS"
    • error if not met: "X carrier is not supported."

Carrier-specific validations#

These validations only apply if you are using a specific carrier.

DHL validations#

  1. Recipient address validation
    • Validate that companyName text length is in range 2-50 (inclusive)
    • Validate that lastName text length is in range 1-35 (inclusive)
    • Validate that name and lastName combined text length is in range 0-35 (inclusive)
    • Validate that street text length is in range 1-35 (inclusive)
    • Validate that street2 text length is in range 1-35 (inclusive)
    • Validate that houseNumber text length is in range 1-5 (inclusive)
    • Validate that zip text length is in range 1-10 (inclusive)
    • Validate that city text length is in range 1-35 (inclusive)
    • Validate that state text length is in range 0-30 (inclusive)
    • Validate that telephoneNumber text length is in range 0-20 (inclusive)
  2. Carrier validation
    1. Carrier service
      • validate that carrier service is "standard" or "returns"
        • error if not met: "DHL supports only standard and returns services"
    2. Notification email validation
      • Validate that notificationEmail text length is in range 0-70 (inclusive)

DHL Express Validations#

  1. Recipient address validation
    • Validate that companyName text length is in range 2-35 (inclusive)
    • Validate that name and lastName combined text length is in range 1-45 (inclusive)
    • Validate that street text length is in range 1-35 (inclusive)
    • Validate that street2 text length is in range 1-35 (inclusive)
    • Validate that houseNumber text length is in range 0-15 (inclusive)
    • Validate that street and houseNumber combined text length is in range 0-35 (inclusive)
    • Validate that zip text length is in range 1-12 (inclusive)
    • Validate that city text length is in range 1-35 (inclusive)
    • Validate that state text length is 2 characters long
    • Validate that country text length is 2 characters long
    • Validate that telephoneNumber text length is in range 1-25 (inclusive)
  2. Carrier validation
    1. Carrier service
      • validate that carrier service is "one_day"
        • error if not met: "DHL Express supports only one_day service"

GLS Validations#

  1. Recipient address validation
  • Validate that companyName text length is in range 2-40 (inclusive)
  • Validate that lastName text length is in range 2-40 (inclusive)
  • Validate that name and lastName combined text length is in range 0-40 (inclusive)
  • Validate that street text length is in range 3-40 (inclusive)
  • Validate that street2 text length is in range 3-40 (inclusive)
  • Validate that houseNumber text length is in range 1-10 (inclusive)
  • Validate that zip text length is in range 1-10 (inclusive)
  • Validate that city text length is in range 2-40 (inclusive)
  • Validate that telephoneNumber text length is in range 0-40 (inclusive)
  1. Carrier validation
    1. Carrier service
      • validate that carrier service is "standard" or "one_day"
        • error if not met: "GLS supports only standard and one_day services"

DPD Validations#

  1. Recipient address validation
  • Validate that companyName text length is in range 1-35 (inclusive)
  • Validate that lastName text length is in range 1-35 (inclusive)
  • Validate that name and lastName combined text length is in range 0-35 (inclusive)
  • Validate that street text length is in range 1-35 (inclusive)
  • Validate that street2 text length is in range 1-35 (inclusive)
  • Validate that houseNumber text length is in range 1-8 (inclusive)
  • Validate that zip text length is in range 1-9 (inclusive)
  • Validate that city text length is in range 1-35 (inclusive)
  • Validate that telephoneNumber text length is in range 0-30 (inclusive)
  1. Carrier validation
    1. Carrier service
      • validate that carrier service is "standard", "returns", "one_day" or "one_day_early"
        • error if not met: "DPD supports only standard, returns, one_day and one_day_early services"
    2. Carrier additional services
      • validate that DPD's additional service is "advance_notice", "drop_authorization" or "saturday_delivery"
        • error if not met: "unknown_service additional service is not allowed for DPD carrier"
      • if "advance_notice" is chosen, validate that service is standard
        • error if not met: "advance_notice expects service to be standard"
      • if "advance_notice" is chosen, validate that email is valid email or sms is valid telephone number
        • error if not met: "e2mail is not a valid email address" or "123 is not a valid telephone number"
      • if "saturday_delivery" is chosen, validate that service is either "one_day" or "one_day_early"
        • error if not met: "saturday_delivery expects service to be either one_day or one_day_early"

UPS Validations#

  1. Recipient address validation
  • Validate that companyName text length is in range 1-35 (inclusive)
  • Validate that lastName text length is in range 1-35 (inclusive)
  • Validate that name and lastName combined text length is in range 0-35 (inclusive)
  • If street2 is not defined:
    • Validate that street and houseNumber combined text length is in range 1-34 (inclusive)
  • If street2 is defined:
    • Validate that street text length is in range 1-35 (inclusive)
    • Validate that street2 and houseNumber combined text length is in range 1-34 (inclusive)
  • Validate that zip text length is in range 1-9 (inclusive)
  • Validate that city text length is in range 1-30 (inclusive)
  • Validate that state text length is 2 characters long
  • Validate that telephoneNumber text length is in range 0-15 (inclusive)
  1. Carrier validation
    1. Carrier service
      • validate that carrier service is "standard"
        • error if not met: "Only standard service is supported"
  2. Parcel validation
    1. Validate that clientReferenceNumber is in range 0-35 (inclusive)
    2. Validate that description field is mandatory if:
      • sender and recipient country are in EU

Note: all text range validation errors are of form:

"A.B is out of range. Valid range is x - y"

where A.B is the path to the field that produced the validation error and where x and y are the expected range bounds for that field.

For example:

"recipientAddress.companyName is out of range. Range 2 to 40"

This error message means that the "companyName" field of the "recipientAddress" object is out of range, and to pass the validation it needs to be between 2 and 40 characters long.

Note on parcel optimization#

Codept offers parcel optimization which is a mechanism for picking the optimal parcel provider for each shipment based on the location of the warehouse and the regional specifics. See the Parcel optimization document for more details.

Edit this page