CheapCargo Logo
API docs by Redocly

CheapCargo XML API (2.1)

CheapCargo Support Team: info@cheapcargo.com URL: https://support.cheapcargo.com License: CheapCargo Terms of Service Terms of Service

Download the OpenAPI specification as JSON or YAML.

🚚 CheapCargo Shipping API

Welcome to the CheapCargo API documentation. This comprehensive guide will help you integrate our shipping services into your application for seamless logistics management.

🚀 Quick Start Guide

  1. Get API Access: Contact us to receive your API key
  2. Review Authentication: Understand our security requirements below
  3. Test with Rate Request: Start with a simple rate inquiry
  4. Create Your First Shipment: Book your first shipment
  5. Track & Manage: Monitor and manage your shipments

📋 What You Can Do

  • 💰 Rate Requests: Get competitive shipping rates for your packages
  • 📦 Create Shipments: Book shipments with trusted carriers
  • 📍 Track Shipments: Real-time monitoring and status updates
  • 🏷️ Manage Labels: Download and print shipping labels
  • ⚙️ Cancel Shipments: Modify or cancel bookings when needed

🔐 Authentication

To access our API, each request must include an authentication token and user credentials. The authentication process ensures that only authorized users can interact with the API. Ensure that the hashes in authentication and password are correctly generated and match the expected format to successfully authenticate with the API.

Authentication Format

The authentication information will look as follows in the request body:

<authentication>317ad2da332f65569b172c77b9565bda</authentication>
<user>
  <email>user@example.com</email>
  <password>51f740668efd21ab9ec1d0d382d9746e</password>
</user>

Authentication Components

  • Authentication token (authentication):

    • The authentication token is generated by creating an MD5 hash of the user's API key followed by the current date and hour in the format YYYYMMDDHH.
    • The time part HH is based on a 24-hour format with a 2-hour margin. For example, if the request is made between 13:00 and 17:59 on 15 December 2023, the time portion would be 15, resulting in a date and time format of 2023121515. So if the user's API key is Vlp3RxUvRF9xDzoX, then Vlp3RxUvRF9xDzoX2023121515 would hash to 317ad2da332f65569b172c77b9565bda.

  • User email address (email):

    • This is the email address associated with the user's account, used for logging in.

  • Password hash (password):

    • The password should be hashed using the MD5 algorithm. CheapCargo would hash to 51f740668efd21ab9ec1d0d382d9746e.

📊 API Versioning

To ensure optimal compatibility with our API, each request should include the version number your system is using. This versioning helps prevent issues when we make changes to the message structure or functionality of the API. By specifying the version number, your system can continue to function correctly even if updates are made on our end.

The version number is applied on a per-method basis, meaning different methods in your system may use different version numbers.

If no version number is provided, the API will assume you are using the latest version. However, if CheapCargo introduces changes and a new version becomes available that differs from the previous one, this could lead to errors. Therefore, we strongly recommend always including the version number in your requests to ensure consistent operation.

🔄 Latest API Versions

Endpoint Current Version Status
createShipment 2.1 ✅ Stable
rateRequest 2.0 ✅ Stable
getStatus 1.9 ✅ Stable
getLabel 1.6 ✅ Stable
cancelShipment 2.1 ✅ Stable

📞 Support & Resources

Need help? Our support team is here to assist you:

⚡ Rate Limits & Best Practices

  • Rate Limit: 100 requests per minute per API key
  • Timeout: 30 seconds per request
  • Retry Logic: Implement exponential backoff for failed requests

💰 Rate Requests

Get competitive shipping rates and quotes from multiple carriers

Request rates for the given addresses and parcels

Get competitive shipping rates from multiple carriers for your shipments.

Features:

  • Compare rates from different carriers
  • Multiple sorting options (price, delivery time, etc.)
  • Support for various package types
  • Bulk rate requests
  • Real-time pricing

Perfect for:

  • E-commerce checkout integration
  • Shipping cost estimation
  • Carrier comparison
  • Logistics planning
Authorizations:
ApiKeyAuth
Request Body schema: application/xml
required
authentication
required
string <password> ^[a-f\d]{32}$
Example: "317ad2da332f65569b172c77b9565bda"

Authentication token for verifying the request

version
required
string
Example: "2"

API version being used

required
object (User)

Information about the user making the request

email
required
string <email>
Example: "user@example.com"

Email address of the user

password
required
string <password> ^[a-f\d]{32}$
Example: "51f740668efd21ab9ec1d0d382d9746e"

MD5 hash of the password of the user's account

required
Array of objects non-empty

List of shipments to get rates for

Array (non-empty)
orderBy
string
Enum: "price" "delivery" "pickup" "carrier" "modality"
Example: "price"

Order criterion for the rate results

required
object (RateAddress)

Information about the sender of the shipment

required
object (RateAddress)

Information about the receiver of the shipment

required
object

Content details of the shipment

incoterm
string
Enum: "DAP" "DDP"
Example: "DAP"

International commercial terms defining the responsibilities of the buyer and seller

Responses

Response Schema: application/xml
required
object

Rates information for the shipments

status
required
string
Example: "ok"

Status of the rate request

required
object

Detailed rate information for a shipment

object
environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type
application/xml

Basic rate request to compare shipping options and prices

<?xml version="1.0" encoding="UTF-8"?>
<shipments>
  <authentication>317ad2da332f65569b172c77b9565bda</authentication>
  <version>2.0</version>
  <user>
    <email>user@example.com</email>
    <password>51f740668efd21ab9ec1d0d382d9746e</password>
  </user>
  <shipment orderBy="price">
    <sender>
      <zipcode>1511AN</zipcode>
      <city>Nijmegen</city>
      <country>NL</country>
      <type>business</type>
    </sender>
    <receiver>
      <zipcode>12345</zipcode>
      <city>Amsterdam</city>
      <country>NL</country>
      <type>business</type>
    </receiver>
    <content>
      <colli>
        <description>Test package</description>
        <weight>5</weight>
        <length>120</length>
        <width>100</width>
        <height>50</height>
        <value>100.00</value>
        <package>PACKAGE</package>
        <quantity>1</quantity>
      </colli>
    </content>
    <incoterm>DAP</incoterm>
  </shipment>
</shipments>

Response samples

Content type
application/xml

Example response showing available shipping rates from different carriers

<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <rates>
    <status>ok</status>
    <shipment>
      <rate>
        <id>2b6d503497d9df6ff3c1a355f855e7b2</id>
        <carrierCode>UPF</carrierCode>
        <carrierName>UPS Freight</carrierName>
        <serviceLevelUid>f8246332-5b82-ad1e-1465-436137530c19</serviceLevelUid>
        <serviceLevel>Express FREIGHT</serviceLevel>
        <serviceCode>96</serviceCode>
        <serviceTime>00:00</serviceTime>
        <price>984.77</price>
        <weight>120</weight>
        <modality>express</modality>
        <info>UPS Freight - Express FREIGHT</info>
        <shop>false</shop>
        <dailyPickup>false</dailyPickup>
        <pickup>2024-03-15</pickup>
        <delivery>2024-03-18</delivery>
        <surcharges>
          <surcharge>
            <name>Ophaalkosten</name>
            <percentage>33.5</percentage>
            <price>137.59</price>
          </surcharge>
        </surcharges>
      </rate>
    </shipment>
  </rates>
  <environment>test</environment>
</rates>

📦 Shipping Operations

Create and manage shipments with trusted logistics partners

Create shipment with the given addresses and parcels

Creates one or more new shipments with the given pickup and delivery addresses and the given parcels.

Key Features:

  • Support for multiple shipments in one request
  • Carrier selection based on rate request result
  • Automatic carrier selection based on your account preferences
  • Optional immediate payment and label generation
  • Commercial invoice support for international shipments
  • HS codes for customs declarations

Use Cases:

  • Single domestic shipment
  • International shipping with customs
  • Express shipments with immediate labels
Authorizations:
ApiKeyAuth
Request Body schema: application/xml
required
authentication
required
string <password> ^[a-f\d]{32}$
Example: "317ad2da332f65569b172c77b9565bda"

Authentication token for verifying the request

version
required
string
Example: "2.1"

API version being used

required
object (User)

Information about the user making the request

email
required
string <email>
Example: "user@example.com"

Email address of the user

password
required
string <password> ^[a-f\d]{32}$
Example: "51f740668efd21ab9ec1d0d382d9746e"

MD5 hash of the password of the user's account

required
Array of objects non-empty

List of shipments to be processed

Array (non-empty)
pay
boolean
Example: "false"

xml attribute
Whether you want to pay for the shipment immediately

waitForLabel
boolean
Example: "false"

xml attribute
Whether the server should wait for the label of this shipment to become available before responding to this request. This field only works when the field pay is true. The server waits a few seconds, but does not wait indefinitely.

id
string
Example: "E-1887"

xml attribute
An identifier for this specific shipment, useful for distinguishing multiple shipments, as it is included again in the shipment in the response

orderBy
string
Enum: "price" "delivery" "pickup" "carrier" "modality"
Example: "price"

xml attribute
Order criterion for the rate results

required
object (ShipmentAddress)

Information about the sender of the shipment

required
object (ShipmentAddress)

Information about the receiver of the shipment

required
object

Content details of the shipment

reference
string
Example: "RC-2023-X"

The order reference that appears on the label and the invoice

incoterm
string
Enum: "DAP" "DDP"
Example: "DAP"

International commercial terms defining the responsibilities of the buyer and seller

commercialInvoiceFile
string <byte>
Example: "JVBERi0xLjAKJUVYQU1QTEUgT0YgQSBDT01NRVJDSUFMIElOVk9JQ0UgUERGIEZJTEUKJUVPRg=="

Base64 encoded PDF file of the commercial invoice

object
object

This element should be provided if you want to select a carrier based on results from the rate request endpoint

Responses

Response Schema: application/xml
status
required
string
Example: "ok"

Status of the shipment request

required
object

Detailed information about the shipment

id
string
Example: "E-1887"

An identifier for this specific shipment, useful for distinguishing multiple shipments, as it can be included in the shipment in the request

number
string^B?\d{9}$
Example: "240004885"

Order number of the shipment

paid
boolean
Example: "true"

Whether the shipment is paid, booked and a label is available. This field is true when status is equal to booked, otherwise it is false.

object

Status details

datePickup
string <date>
Example: "2023-12-15"

Pickup date of the shipment

dateDelivery
string <date>
Example: "2023-12-20"

Delivery date of the shipment

carrierCode
string^[A-Z][A-Z\d]{2}$
Example: "DPS"

Code of the carrier handling the shipment

carrierName
string
Example: "DPD Parcelshop"

Name of the carrier handling the shipment

status
string
Enum: "new" "paid" "booked" "cancel"
Example: "booked"

Current status of the shipment. new indicates that the order has been added to the shopping cart, but has not yet been paid. paid indicates that the order has been paid, but not yet booked and does not have a label. booked indicates that the order has been paid, booked and has a label. cancel indicates that the order has been canceled.

awb
string^[A-Z\d-]+$
Example: "5112060086107"

Tracking number, also known as an air waybill number, of the shipment. May be available if the server waited because of the field waitForLabel.

trackAndTrace
string <uri>
Example: "https://www.cheapcargo.com/Data/TrackAndTrace?id=c3412900-ac53-423f-86dd-10eb8de25542&amp;ajax=true"

URL for tracking the shipment

commercialInvoiceUrl
string <uri>
Example: "https://www.cheapcargo.com/Order/CommercialInvoice?orderId=c3412900-ac53-423f-86dd-10eb8de25542"

URL for downloading the commercial invoice as a PDF file

Array of objects (Problem)

Detailed information about any problems encountered

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type
application/xml
Example

A basic example to get you started with a simple domestic shipment within the Netherlands

<?xml version="1.0" encoding="UTF-8"?>
<shipments>
  <authentication>317ad2da332f65569b172c77b9565bda</authentication>
  <version>2.1</version>
  <user>
    <email>user@example.com</email>
    <password>51f740668efd21ab9ec1d0d382d9746e</password>
  </user>
  <shipment pay="false" waitForLabel="false" id="E-1887" orderBy="price">
    <sender>
      <companyName>My Company</companyName>
      <contactPerson>John Sender</contactPerson>
      <street>Hoofdstraat</street>
      <number>123</number>
      <zipcode>1000AA</zipcode>
      <city>Amsterdam</city>
      <country>NL</country>
      <phone>+31612345678</phone>
      <email>sender@example.com</email>
      <type>business</type>
    </sender>
    <receiver>
      <companyName>Customer Corp</companyName>
      <contactPerson>Jane Receiver</contactPerson>
      <street>Kerkstraat</street>
      <number>456</number>
      <zipcode>2000BB</zipcode>
      <city>Rotterdam</city>
      <country>NL</country>
      <phone>+31687654321</phone>
      <email>receiver@example.com</email>
      <type>business</type>
    </receiver>
    <content>
      <colli>
        <description>Electronics package</description>
        <weight>2.5</weight>
        <length>30</length>
        <width>20</width>
        <height>15</height>
        <value>150.00</value>
        <package>PACKAGE</package>
        <quantity>1</quantity>
      </colli>
    </content>
    <reference>ORDER-2024-001</reference>
  </shipment>
</shipments>

Response samples

Content type
application/xml

Example response when a shipment is successfully created and booked

<?xml version="1.0" encoding="UTF-8"?>
<shipment>
  <status>ok</status>
  <order id="E-1887">
    <number>240004885</number>
    <paid>true</paid>
    <details>
      <datePickup>2023-12-15</datePickup>
      <dateDelivery>2023-12-20</dateDelivery>
      <carrierCode>DPS</carrierCode>
      <carrierName>DPD Parcelshop</carrierName>
      <status>booked</status>
      <awb>5112060086107</awb>
      <trackAndTrace>https://www.cheapcargo.com/Data/TrackAndTrace?id=c3412900-ac53-423f-86dd-10eb8de25542&amp;ajax=true</trackAndTrace>
      <commercialInvoiceUrl>https://www.cheapcargo.com/Order/CommercialInvoice?orderId=c3412900-ac53-423f-86dd-10eb8de25542</commercialInvoiceUrl>
    </details>
  </order>
  <environment>test</environment>
</shipment>

📍 Tracking & Status

Monitor shipment status and track packages in real-time

Get status information of a shipment

Retrieve comprehensive status information and tracking details for your shipments.

Information Provided:

  • Current shipment status
  • Tracking numbers (AWB)
  • Pickup and delivery dates
  • Carrier information
  • Track & trace history
  • Problem notifications

Status Types:

  • new - Added to cart, not paid
  • paid - Paid but not booked
  • booked - Paid, booked, and labeled
  • cancel - Canceled shipment
Authorizations:
ApiKeyAuth
Request Body schema: application/xml
required
authentication
required
string <password> ^[a-f\d]{32}$
Example: "317ad2da332f65569b172c77b9565bda"

Authentication token for verifying the request

version
required
string
Example: "1.9"

API version being used

required
object (User)

Information about the user making the request

email
required
string <email>
Example: "user@example.com"

Email address of the user

password
required
string <password> ^[a-f\d]{32}$
Example: "51f740668efd21ab9ec1d0d382d9746e"

MD5 hash of the password of the user's account

required
Array of objects non-empty

List of status requests

Array (non-empty)
orderNumber
string^B?\d{9}$
Example: "240004885"

Order number of the shipment

Responses

Response Schema: application/xml
status
required
string
Example: "ok"

Status of the request

required
object

Information about the shipment label

orderNumber
string^B?\d{9}$
Example: "240004885"

Order number of the shipment

paid
boolean
Example: "true"

Whether the shipment is paid, booked and a label is available. This field is true when status is equal to booked, otherwise it is false.

object

Status details

datePickup
required
string <date>
Example: "2024-05-15"

Pickup date of the shipment

dateDelivery
required
string <date>
Example: "2024-05-17"

Delivery date of the shipment

carrierCode
required
string^[A-Z][A-Z\d]{2}$
Example: "DPS"

Code of the carrier handling the shipment

carrierName
required
string
Example: "DPD Parcelshop"

Name of the carrier handling the shipment

totalNet
required
number decimal places <= 2 >= 0.01
Example: "9.8"

Total net price of the shipment in euros

insurance
number decimal places <= 2 >= 0.01
Example: "0.01"

Insurance value for the shipment in euros

weight
required
number
Example: "2"

Weight of the shipment in kilograms

status
required
string
Enum: "new" "paid" "booked" "cancel"
Example: "booked"

Current status of the shipment. new indicates that the order has been added to the shopping cart, but has not yet been paid. paid indicates that the order has been paid, but not yet booked and does not have a label. booked indicates that the order has been paid, booked and has a label. cancel indicates that the order has been canceled.

awb
required
string^[A-Z\d-]+$
Example: "5112060086107"

Tracking number, also known as an air waybill number, of the shipment

required
object

Pickup details

required
object

Track and trace information for the shipment

Array of objects (Problem)

Detailed information about any problems encountered

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type
application/xml

Check the status of a specific shipment using its order number

<?xml version="1.0" encoding="UTF-8"?>
<shipments>
  <authentication>317ad2da332f65569b172c77b9565bda</authentication>
  <version>1.9</version>
  <user>
    <email>user@example.com</email>
    <password>51f740668efd21ab9ec1d0d382d9746e</password>
  </user>
  <status>
    <orderNumber>240004885</orderNumber>
  </status>
</shipments>

Response samples

Content type
application/xml

Comprehensive status response including tracking history and shipment details

<?xml version="1.0" encoding="UTF-8"?>
<status>
  <status>ok</status>
  <label>
    <orderNumber>240004885</orderNumber>
    <paid>true</paid>
    <details>
      <datePickup>2024-05-15</datePickup>
      <dateDelivery>2024-05-17</dateDelivery>
      <carrierCode>DPS</carrierCode>
      <carrierName>DPD Parcelshop</carrierName>
      <totalNet>9.8</totalNet>
      <insurance>0.01</insurance>
      <weight>2</weight>
      <status>booked</status>
      <awb>5112060086107</awb>
      <pickup>
        <plannedDate>2024-05-15</plannedDate>
        <code>CFX-97</code>
      </pickup>
      <trackAndTrace>
        <url>https://www.cheapcargo.com/Data/TrackAndTrace?id=45cf567a-d29c-c362-4d29-90c3ca3f6a82&amp;ajax=true</url>
        <statuses>
          <status>
            <status>inTransit</status>
            <message>Departed from Facility</message>
            <occurred>2023-12-15 13:37:00</occurred>
          </status>
        </statuses>
      </trackAndTrace>
    </details>
  </label>
  <environment>test</environment>
</status>

🏷️ Labels & Documents

Download and manage shipping labels and documentation

Get label URL of a shipment

Download shipping labels for your booked shipments.

Label Options:

  • pdf - Standard label format
  • pdfa4 - A4 format for easy printing

Features:

  • High-quality PDF labels
  • Multiple labels per request
  • Direct download URLs
  • Print-ready formats

Requirements:

  • Shipment must be in booked status
  • Valid order number required
Authorizations:
ApiKeyAuth
Request Body schema: application/xml
required
authentication
required
string <password> ^[a-f\d]{32}$
Example: "317ad2da332f65569b172c77b9565bda"

Authentication token for verifying the request

version
required
string
Example: "1.6"

API version being used

required
object (User)

Information about the user making the request

email
required
string <email>
Example: "user@example.com"

Email address of the user

password
required
string <password> ^[a-f\d]{32}$
Example: "51f740668efd21ab9ec1d0d382d9746e"

MD5 hash of the password of the user's account

required
Array of objects non-empty

List of labels to be requested

Array (non-empty)
orderNumber
string^B?\d{9}$
Example: "240004885"

Order number of the shipment

type
string
Enum: "pdf" "pdfa4"

Type of label to be requested

Responses

Response Schema: application/xml
status
required
string
Example: "ok"

Status of the label creation request

required
object

Information about the created label

number
string^B?\d{9}$
Example: "240004885"

Order number of the shipment

type
string
Enum: "pdf" "pdfa4"

Type of the created label

url
string <uri>
Example: "https://labels.cheapcargo.com/2024/05/14/45cf567a-d29c-c362-4d29-90c3ca3f6a82/label10x21.pdf"

URL where the label can be downloaded

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type
application/xml

Download a shipping label for a booked shipment

<?xml version="1.0" encoding="UTF-8"?>
<labels>
  <authentication>317ad2da332f65569b172c77b9565bda</authentication>
  <version>1.6</version>
  <user>
    <email>user@example.com</email>
    <password>51f740668efd21ab9ec1d0d382d9746e</password>
  </user>
  <labels>
    <orderNumber>240004885</orderNumber>
    <type>pdf</type>
  </labels>
</labels>

Response samples

Content type
application/xml

Response containing the download URL for the requested shipping label

<?xml version="1.0" encoding="UTF-8"?>
<labels>
  <status>ok</status>
  <label>
    <number>240004885</number>
    <type>pdf</type>
    <url>https://labels.cheapcargo.com/2024/05/14/45cf567a-d29c-c362-4d29-90c3ca3f6a82/label10x21.pdf</url>
  </label>
  <environment>test</environment>
</labels>

⚙️ Shipment Management

Cancel, modify, and manage your shipments

Cancel a shipment

Cancel one or more shipments using their order numbers.

Cancellation Rules:

  • Only shipments in new, paid, or booked status can be canceled
  • Cancellation may incur fees depending on carrier and timing
  • Refunds processed according to our terms of service

What Happens:

  • Shipment status changes to cancel
  • Carrier booking is canceled (if applicable)
  • Refund process initiated (if eligible)

Best Practices:

  • Cancel as early as possible to avoid fees
  • Check cancellation policies per carrier
Authorizations:
ApiKeyAuth
Request Body schema: application/xml
required
authentication
required
string <password> ^[a-f\d]{32}$
Example: "317ad2da332f65569b172c77b9565bda"

Authentication token for verifying the request

version
required
string
Example: "2.1"

API version being used

required
object (User)

Information about the user making the request

email
required
string <email>
Example: "user@example.com"

Email address of the user

password
required
string <password> ^[a-f\d]{32}$
Example: "51f740668efd21ab9ec1d0d382d9746e"

MD5 hash of the password of the user's account

required
Array of objects non-empty

List of cancel requests

Array (non-empty)
id
string
Example: "E-1887"

xml attribute
An identifier for this specific shipment, useful for distinguishing multiple shipments, as it is included again in the shipment in the response

orderNumber
required
string^B?\d{9}$
Example: "240004885"

Order number of the shipment that should be canceled

Responses

Response Schema: application/xml
status
required
string
Example: "ok"

Status of the shipment request

required
object

Information about the canceled shipment

id
string
Example: "E-1887"

xml attribute
An identifier for this specific shipment, useful for distinguishing multiple shipments, as it can be included in the shipment in the request

number
required
string^B?\d{9}$
Example: "240004885"

Order number of the canceled shipment

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type
application/xml

Cancel a specific shipment using its order number

<?xml version="1.0" encoding="UTF-8"?>
<shipments>
  <authentication>317ad2da332f65569b172c77b9565bda</authentication>
  <version>2.1</version>
  <user>
    <email>user@example.com</email>
    <password>51f740668efd21ab9ec1d0d382d9746e</password>
  </user>
  <order id="E-1887">
    <orderNumber>240004885</orderNumber>
  </order>
</shipments>

Response samples

Content type
application/xml

Confirmation response when a shipment is successfully canceled

<?xml version="1.0" encoding="UTF-8"?>
<shipment>
  <status>ok</status>
  <order id="E-1887">
    <number>240004885</number>
  </order>
  <environment>test</environment>
</shipment>