A comprehensive guide to importing order data. This import facilitates the bulk creation of orders for both sandbox and live tenants, which is useful for data loading, system integration, and testing purposes. This article outlines the specific requirements, best practices, and common issues.
📖 Key Terminology
Order: A request for a transport job or service.
External ID: A unique identifier for an order from an external system.
Stop: A specific location or point in a journey where a task is performed.
Product: A specific item or commodity being transported.
Service: The type of service being provided (e.g., transport).
✅ Critical Import Requirements for Orders
Prior to importing order data, the following requirements and warnings must be considered to ensure data integrity.
User Permission Prerequisite: The manual order data import functionality is restricted. Only users with Superadmin privileges can perform the order import.
Companies Prerequisite: All customers relevant to the order must already exist in the Qargo system.
Products Prerequisite: All products included in the order must already exist in the product catalogue.
Unique Identification: The Order Number or External ID serves as the unique identifier for the order.
Date and Time Format: All date and time fields must be in the correct format as specified in the template to avoid import failure (YY/MM/DD).
🛠️ Step-by-Step Order Import Process
The following steps should be followed to successfully import order data.
Step 1: Confirm Import Functionality (or Verify Activation Status)
Verification that the manual data import functionality has been activated must be confirmed with the Account Manager.
Step 2: Download Template
A specific Excel template is available to upload order data:
📚 Always use a blank template downloaded directly from the Qargo platform or provided by the Qargo team. Re-using an old template may lead to import errors.
Step 3: Fill in the Excel Template
Open the template and populate it with the required data. The template contains column headers that correspond to the fields in Qargo.
Required Fields: Make sure to fill out all the required fields (a comprehensive list of required fields can be found in the next section of this article). An import will fail if these fields are left blank.
Formatting: Close attention should be paid to the specified data format (e.g., dates, numbers, text).
📚 Prefill Functionality: If enabled in the order import configuration (under Customer and Transport service), any order created through the import or external API will process order defaults and prefill any values in the new order.
Step 4: Upload File
The completed file is uploaded by navigating to the Orders module, selecting the Order Imports tab, and clicking Import from file.
The source of the import must be selected. When the source is a manual template upload, select the Manual source integration.
The document can then be uploaded. Should any errors be present, a message detailing the issues will appear, and the system will suggest potential solutions.
Step 5: Review and Finalise
Address any validation errors identified by the system and finalise the import by creating the order(s).
📝 Details of the Order Import Template
This section will provide a detailed, field-by-field explanation of the Excel template for order import, including data formats, required fields, and best practices for populating each column.
Column name | Required/optional | Remarks | Example |
transport_service | Optional | Transport Service configured in Qargo | Transport 2 |
customer_code | Optional | Customer code used in the application. Must be an exact match to the Customer Code of a customer record already imported into Qargo. Used in combination with Display Name to ensure order uniqueness. | 2322 |
customer_name | Optional | Must be an exact match to the Display Name of a customer record already imported into Qargo. Used in combination with Customer Code to ensure order uniqueness. | Qargo |
customer_reference_number | Optional | A reference number for the customer's internal tracking. | CUST-REF-001 |
order_reference_number | Mandatory | A general reference number for the order. |
|
order_requested_price | Optional | The value should be a numeric representation of the price, and the currency will be based on the tenant's configured currency. | 50 |
order_service_level_code | Optional | A unique code identifying the service level. | EXP-01 |
pickup_date | Optional | YY/MM/DD | 2026/01/20 |
pickup_time_start | Optional | HH:MM:SS | 12:00:00 |
pickup_time_end | Optional | HH:MM:SS | 13:00:00 |
pickup_name | Optional |
|
|
pickup_full_address | Optional | The full, primary address of the pickup location. | 123 Transport Way, London, E16 2NZ |
pickup_address_line_1 | Optional |
|
|
pickup_address_line_2 | Optional |
|
|
pickup_postcode | Optional |
|
|
pickup_city | Optional |
| London |
pickup_country | Optional |
| GB |
pickup_notes | Optional |
|
|
pickup_reference_number | Optional |
|
|
delivery_name | Optional |
|
|
delivery_date | Optional | Year/Month/Day | 2016/09/20 |
delivery_time_start | Optional | HH:MM:SS | 13:00:00 |
delivery_time_end | Optional | HH:MM:SS | 13:00:00 |
delivery_full_address | Optional | The full, primary address of the delivery location. | 123 Transport Way, London, E16 2NZ |
delivery_address_line_1 | Optional |
|
|
delivery_address_line_2 | Optional |
|
|
delivery_postcode | Optional |
|
|
delivery_city | Optional |
| Brussels |
delivery_country | Optional |
| BE |
delivery_notes | Optional |
|
|
delivery_reference_number | Optional |
|
|
absolute_min_temperature_value | Optional | Lowest temperature the product can handle. |
|
absolute_max_temperature_value | Optional | Highest temperature the product can handle. |
|
volume_lt | Optional |
|
|
quantity | Optional |
|
|
weight_kg | Optional |
|
|
goods_description | Optional |
|
|
pallet_spaces | Optional | Number of standard pallet spaces the product occupies. |
|
loading_meters | Optional |
|
|
adr_un_number | Optional |
|
|
packaging_type | Optional |
|
|
packaging_size | Optional |
|
|
product_name | Optional | Product name displayed in Qargo | Aardappelen |
🔎 Troubleshooting Common Order Import Errors
This section addresses specific errors that may arise during the import of order data.
Company Not Found: For an order to be uniquely identified and managed within Qargo, the combination of the External ID and the Customer Name must be unique.
Location Not Found: A common error occurs when a stop's location address does not match an existing location in the system.
Product Not Found: If a product’s name in the order does not match a product already in the catalogue, the import will fail.
Incorrect Date/Time Format: A frequent issue with order imports is incorrect date or time formatting, which will cause the import to fail.
Address Fields: The Country field requires a two-letter code (e.g., GB, not “UK”). You can see this list for Alpha-2 code.
Case-Sensitive Column Headers: Column headers must be entered with the correct casing (e.g.,
vat_number, notVAT_number). Using incorrect casing will cause the data in that column to be silently ignored and not imported, as the system will not recognise the header.Leading Apostrophe Errors: Data in a cell cannot begin with an apostrophe ('). If an apostrophe is used, the system will not recognise the value, and an error may occur. This rule is waived only if the article explicitly instructs that an apostrophe should be used for a specific field.
✨ Best Practices for Importing Orders
To ensure a smooth and accurate import, consider the following best practices.
Import Prerequisites First: Before attempting to import orders, it is critical to ensure that all associated companies, locations, and products have already been successfully imported into the system.
Test with a Small Batch: It is recommended to test the import process with a small sample of 5-10 orders first to verify that the data is formatted correctly before a full import.
➡️ What to Do Next
Once orders have been successfully imported, they will be available in the Orders module. They can then be planned, assigned to drivers, and dispatched as part of your transport operations.
📈 Use Cases for Order Import
The order import is a valuable tool for several key business processes.
Sandbox Testing: The primary use case is to quickly create a large amount of test data in a sandbox tenant to facilitate training, test workflows, and demonstrate the platform’s capabilities without affecting a live environment.
System Migration: In some cases, a one-time import can be used to migrate historical or pending orders from a legacy system.