CheapCargo
API docs by Redocly

CheapCargo 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

📄 Data Formats

The API supports both XML and JSON. Set the Content-Type header to application/xml or application/json accordingly. The JSON format is a direct translation of the XML structure, where the XML root element becomes the top-level key in the JSON object.

XML attributes are represented as @attributeName fields in JSON. For example:

<shipment pay="false" id="E-1887">
  <reference>ORDER-001</reference>
</shipment>

{
  "shipment": {
    "@pay": false,
    "@id": "E-1887",
    "reference": "ORDER-001"
  }
}

Array elements such as shipment and colli are always represented as JSON arrays, even when there is only one item.

📋 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
  • 👤 Manage Accounts: Create and manage user accounts

🔐 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 typically look as follows in the request body:

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

Or in JSON:

{
  "authentication": "317ad2da332f65569b172c77b9565bda",
  "user": {
    "email": "user@example.com",
    "password": "51f740668efd21ab9ec1d0d382d9746e"
  }
}

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.

  • User account number (accountNumber):

    • Instead of providing the user email address, the user account number can also be provided.

On Behalf of Another User

The API also supports performing requests on behalf of another user. This allows authorized partners or administrators to execute operations for other accounts without requiring their direct credentials. To do this, include an onBehalfOf element in the request body after the user element, specifying either the user's email address or account number. For example:

<onBehalfOf>
  <email>different_user@example.com</email>
</onBehalfOf>

or

<onBehalfOf>
  <accountNumber>260001337</accountNumber>
</onBehalfOf>

In JSON:

{
  "onBehalfOf": {
    "email": "different_user@example.com"
  }
}

or

{
  "onBehalfOf": {
    "accountNumber": "260001337"
  }
}

This functionality only works if the target user has explicitly authorized you to act on their behalf. Without this authorization, the API will reject the request with an authentication error.

It is recommended to use the account number instead of the email address whenever possible, because account numbers are permanent identifiers, while users can change their email addresses at any time.

📊 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
createAccount 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
Request Body schema:
required
required
object

Shipments for which rates are requested

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

Authentication token for verifying the request

version
required
string
Example: "2.0"

API version being used

required
object (User)

Information about the user making the request

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

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260000042"

Account number of the user. This field or the email address needs to be provided.

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

MD5 hash of the password of the user's account

object (OnBehalfOf)

Whether you want to make a request on behalf of another user. This only works if this user has authorized you to make requests on their behalf.

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

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260001337"

Account number of the user. This field or the email address needs to be provided.

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:
required
object

Rates information for the shipments

status
required
string
Example: "ok"

Status of the rate request

required
Array of objects

List of shipment rate results

Array
Array of objects

List of available rates for this shipment

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type

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

Example response showing available shipping rates from different carriers

<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <status>ok</status>
  <shipment>
    <rate>
      <id>2b6d503497d9df6ff3c1a355f855e7b2</id>
      <carrierCode>UPF</carrierCode>
      <carrierName>UPS Freight</carrierName>
      <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>2026-01-15</pickup>
      <delivery>2026-01-18</delivery>
      <surcharges>
        <surcharge>
          <name>Ophaalkosten</name>
          <percentage>33.5</percentage>
          <price>137.59</price>
        </surcharge>
      </surcharges>
    </rate>
  </shipment>
  <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
Request Body schema:
required
required
object

Shipments to be created

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
string <email>
Example: "user@example.com"

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260000042"

Account number of the user. This field or the email address needs to be provided.

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

MD5 hash of the password of the user's account

object (OnBehalfOf)

Whether you want to make a request on behalf of another user. This only works if this user has authorized you to make requests on their behalf.

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

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260001337"

Account number of the user. This field or the email address needs to be provided.

required
Array of objects non-empty

List of shipments to be processed

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

attribute — XML attribute, in JSON use @pay
Whether you want to pay for the shipment immediately

waitForLabel
boolean
Example: "false"

attribute — XML attribute, in JSON use @waitForLabel
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"

attribute — XML attribute, in JSON use @id
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"

attribute — XML attribute, in JSON use @orderBy
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-2026-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:
required
object

Information about the created shipment

status
required
string
Example: "ok"

Status of the shipment request

required
Array of objects

List of shipment results

Array
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: "260004885"

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

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type
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-2026-001</reference>
  </shipment>
</shipments>

Response samples

Content type

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>260004885</number>
    <paid>true</paid>
    <details>
      <datePickup>2025-12-15</datePickup>
      <dateDelivery>2025-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>
      <problems>
        <problem>
          <code>Unprocessable Entity</code>
          <message>The reference should not be empty.</message>
        </problem>
      </problems>
    </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
Request Body schema:
required
required
object

Shipments for which status is requested

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
string <email>
Example: "user@example.com"

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260000042"

Account number of the user. This field or the email address needs to be provided.

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

MD5 hash of the password of the user's account

object (OnBehalfOf)

Whether you want to make a request on behalf of another user. This only works if this user has authorized you to make requests on their behalf.

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

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260001337"

Account number of the user. This field or the email address needs to be provided.

required
Array of objects non-empty

List of status requests

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

Order number of the shipment

Responses

Response Schema:
required
object

Status information for the shipment

status
required
string
Example: "ok"

Status of the request

required
Array of objects

List of shipment status results

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

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

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type

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>260004885</orderNumber>
  </status>
</shipments>

Response samples

Content type

Comprehensive status response including tracking history and shipment details

<?xml version="1.0" encoding="UTF-8"?>
<status>
  <status>ok</status>
  <label>
    <orderNumber>260004885</orderNumber>
    <paid>true</paid>
    <details>
      <datePickup>2026-01-15</datePickup>
      <dateDelivery>2026-01-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>2026-01-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>2025-12-15 13:37:00</occurred>
          </status>
        </statuses>
      </trackAndTrace>
      <problems>
        <problem>
          <code>Unprocessable Entity</code>
          <message>The reference should not be empty.</message>
        </problem>
      </problems>
    </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
  • zpl - ZPL file for label printers

Features:

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

Requirements:

  • Shipment must be in booked status
  • Valid order number required
Request Body schema:
required
required
object

Labels for which the URL is requested

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
string <email>
Example: "user@example.com"

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260000042"

Account number of the user. This field or the email address needs to be provided.

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

MD5 hash of the password of the user's account

object (OnBehalfOf)

Whether you want to make a request on behalf of another user. This only works if this user has authorized you to make requests on their behalf.

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

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260001337"

Account number of the user. This field or the email address needs to be provided.

required
Array of objects non-empty

List of labels to be requested

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

Order number of the shipment

type
string
Enum: "pdf" "pdfa4" "zpl"

Type of label to be requested

Responses

Response Schema:
required
object

Status information for the labels

status
required
string
Example: "ok"

Status of the label creation request

required
Array of objects

List of label results

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

Order number of the shipment

type
required
string
Enum: "pdf" "pdfa4" "zpl"

Type of the created label

status
required
string
Enum: "pending" "available" "unavailable"

Current status of the label. pending indicates that the label is being downloaded and will soon be available at the indicated URL. available indicates that the label file is available at the indicated URL. unavailable indicates that the label will not be available, because the chosen label format is not enabled for this carrier or your account.

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

URL where the label is or will be available for download

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type
Example

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>
  <label>
    <orderNumber>260004885</orderNumber>
    <type>pdf</type>
  </label>
</labels>

Response samples

Content type
Example

Response containing the download URL for the requested shipping label

<?xml version="1.0" encoding="UTF-8"?>
<labels>
  <status>ok</status>
  <label>
    <number>260004885</number>
    <type>pdf</type>
    <status>available</status>
    <url>https://labels.cheapcargo.com/2026/01/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 with the status paid and booked 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
Request Body schema:
required
required
object

Shipments to be canceled

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
string <email>
Example: "user@example.com"

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260000042"

Account number of the user. This field or the email address needs to be provided.

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

MD5 hash of the password of the user's account

object (OnBehalfOf)

Whether you want to make a request on behalf of another user. This only works if this user has authorized you to make requests on their behalf.

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

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260001337"

Account number of the user. This field or the email address needs to be provided.

required
Array of objects non-empty

List of cancel requests

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

attribute — XML attribute, in JSON use @id
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: "260004885"

Order number of the shipment that should be canceled

Responses

Response Schema:
required
object

Information about the canceled shipment

status
required
string
Example: "ok"

Status of the shipment request

required
object

Information about the canceled shipment

id
string
Example: "E-1887"

attribute — XML attribute, in JSON use @id
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: "260004885"

Order number of the canceled shipment

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type

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>260004885</orderNumber>
  </order>
</shipments>

Response samples

Content type

Confirmation response when a shipment is successfully canceled

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

👤 Account Management

Create and manage user accounts (restricted access)

⚠️ RESTRICTED ENDPOINTS ⚠️

  • These endpoints can only be used after receiving specific authorization from CheapCargo
  • The onBehalfOf element is not allowed and will result in an error

Create a new user account

This endpoint allows you to create new user accounts in the CheapCargo system.

Account Creation Process:

  • Validates company number and retrieves company data
  • Generates a new account number

Required Information:

  • Valid email address (must not already exist in the system)
  • European Unique Identifier (EUID) or Chamber of Commerce (COC) number (validated against official registry)
  • Contact person name
  • Valid phone number (international format)
  • Optional invoice email address (defaults to account email address if not provided)

Use Cases:

  • Partner integrations creating sub-accounts
  • Automated account provisioning for enterprise customers
Request Body schema:
required
required
object

Account to be created

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 authenticated user creating the account

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

Email address of the user. This field or the account number needs to be provided.

accountNumber
string^B?\d{9}$
Example: "260000042"

Account number of the user. This field or the email address needs to be provided.

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

MD5 hash of the password of the user's account

required
object

Information about the account to be created

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

Email address for the new account. Must be unique and not already exist in the system.

invoiceEmail
string <email>
Example: "invoices@example.com"

Optional email address for invoices. If not provided, defaults to the account email address.

euid
string
Example: "NLNHR.12345678"

European Unique Identifier (EUID) of the company. Must be valid and registered in the official business registry. This field or the COC number needs to be provided.

cocNumber
string
Example: "12345678"

Chamber of Commerce (COC) number. Must be valid and registered in the official business registry. This field or the EUID needs to be provided.

contactPerson
required
string
Example: "John Doe"

Name of the contact person for the account

phone
required
string
Example: "+31612345678"

Phone number in international format (E.164). Will be converted to international format automatically.

vatNumber
string
Example: "12345678"

VAT number of the company. If it is provided, it will be strictly validated.

Responses

Response Schema:
required
object

Information about the created account

required
object

Information about the created account

status
required
string
Example: "ok"

Status of the account creation request

required
object

Information about the created account

environment
string
Example: "test"

Environment in which the request was processed, omitted in production

Request samples

Content type

Example request to create a new user account. Note: This endpoint requires special permission from CheapCargo.

<?xml version="1.0" encoding="UTF-8"?>
<accounts>
  <authentication>317ad2da332f65569b172c77b9565bda</authentication>
  <version>2.1</version>
  <user>
    <email>user@example.com</email>
    <password>51f740668efd21ab9ec1d0d382d9746e</password>
  </user>
  <account>
    <email>newuser@example.com</email>
    <invoiceEmail>invoices@example.com</invoiceEmail>
    <euid>NLNHR.12345678</euid>
    <cocNumber>12345678</cocNumber>
    <contactPerson>John Doe</contactPerson>
    <phone>+31612345678</phone>
    <vatNumber>NL123456789B01</vatNumber>
  </account>
</accounts>

Response samples

Content type

Example response when an account is successfully created

<?xml version="1.0" encoding="UTF-8"?>
<accounts>
  <status>ok</status>
  <account>
    <accountNumber>260004886</accountNumber>
  </account>
  <environment>test</environment>
</accounts>