---
title: "Data import: importing order data"
description: "A comprehensive guide to importing orders into Qargo."
url: https://help.qargo.com/us/articles/418636-data-import-importing-order-data
locale: us
updated: 2026-07-15
---

# Data import: importing order data

A comprehensive guide to importing order data. This import supports the bulk creation of orders for both sandbox and live tenants, which is useful for data loading, system integration, and testing. This article outlines the specific requirements, best practices, and common issues.

* * *

### 📖 Key terminology {#h_dbe58ea455}

-   **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 {#h_08a69ce9bb}

Before importing order data, consider the following requirements and warnings 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 catalog.
-   **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).

**Validation rules:** Numeric fields must contain only positive values (with exceptions for fields like `absolute_min_temperature_value` and `absolute_max_temperature_value`). Date fields must follow the format `YYYY-MM-DD`. Dropdown fields must match predefined values. In addition, imports are capped at 100 lines per file.

* * *

### 🛠️ Step-by-step order import process {#h_d69f998df1}

Follow these steps to import order data successfully.

### Step 1: Confirm import functionality (or verify activation status) {#h_c875e93445}

Confirm with the **account manager** that the manual data import functionality has been activated.

### Step 2: Download template {#h_9c3e87bf5a}

A specific spreadsheet template is available for uploading order data. **To edit and upload the data, a copy of the template must be downloaded:**

1.  Click the link: [Order data import template](https://docs.google.com/spreadsheets/d/1o8Uh96ckVH2n5kzeI1a6OkdQl6HNglxhpjWAT1CNWlA/edit?usp=sharing)
2.  Once the template opens, go to **File** and select **Download**
3.  Save the template **(in .xlsx or .csv format)** to a computer and begin entering the company data.

![](https://help.qargo.com/media/1c7401d4e9fb-image.png)

:::callout{tone="info"}
📚 Always use a **blank template** downloaded directly from this article or provided by the Qargo team. Reusing an old template may lead to import errors.
:::

### Step 3: Fill in the Excel template {#h_6b4b08c13a}

Open the template and populate it with the required data. The template contains column headers that correspond to the fields in Qargo.

-   **Required fields:** To create a basic order, make sure the following fields are included: `transport_service`, `customer_code`, `order_reference_number` (unique for each line), `pickup_date`, `delivery_date`, `pickup address` (complete address or components) with `pickup_name`, and `delivery address` (complete address or components) with `delivery_name`.
-   **Formatting:** Pay close attention to the specified data format (e.g., dates, numbers, text).

-   **Custom field naming:** When using custom fields, make sure the column headers follow the naming convention with double underscores (e.g., `order_custom_field__FIELD_ID`).

:::callout{tone="info"}
📚 **Prefill** **functionality:** If enabled in the order import configuration (under **Customer** and **Transportation service**), any order created through the import or external API will process order defaults and prefill any values in the new order.
:::

## Template customization with custom fields {#h_207c319e21}

Custom field mappings make it possible to import data into fields tailored to specific customer requirements. These fields must be created and named appropriately before the mapping is configured. The naming convention for custom fields in import files uses two underscores in the column name (e.g., `custom_fields__example`).

1.  **Create the custom field in Qargo:** Navigate to `Configuration > Additional fields` to create a new custom field. Note the assigned `field ID`.
2.  **Add the custom field to the template:** Add a column named in the format `order_custom_field__FIELD_ID` (e.g., `order_custom_field__invoicegroup`).
3.  **Formatting tips:** Make sure column headers match exactly, avoid apostrophe-prefixed data, and include the "Import" sheet naming convention.
4.  **Test the configuration**: Import a test file for the designated customer to verify that the data populates the custom field correctly.

## Limitations and considerations {#h_b0b7f5ba97}

-   **Customer-specific configuration**: Custom field mappings are configured for specific customers. If data is imported for a different customer, the custom field will not be populated.
-   **Mapping changes**: If the same custom field mapping is needed for additional customers, a mapping update must be requested, or the mapping must be configured separately for each customer.

### Step 4: Upload file {#h_c161d41d1c}

To upload the completed file, navigate to the **Orders** module, select the **Order imports** tab, and click **Import from file**.

![](https://help.qargo.com/media/af5502f9ff12-image.png)

The source of the import must be selected. When the source is a manual template upload, select the **Manual** source integration.

![](https://help.qargo.com/media/bd3420653f1f-image.png)

The document can then be uploaded. If there are any errors, a message describing the issues will appear, and the system will suggest possible solutions.

![](https://help.qargo.com/media/059f54767e23-image.png)

### Step 5: **Review and finalize** {#h_2d5dea7b74}

Resolve any validation errors identified by the system and finalize the import by creating the order(s).

![](https://help.qargo.com/media/082702ebcd4a-image.png)

* * *

### 📝 Details of the order import template {#h_19f6df64d9}

This section provides 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 | Transportation service configured in Qargo | Transport 2 |
| customer\_code | Optional | Customer code used in the application. Must exactly match 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 exactly match 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; the currency is 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 {#h_0ac6ccfc06}

This section covers specific errors that may occur during the import of order data.

-   **Company not found:** For an order to be uniquely identified and managed in 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 catalog, the import will fail.
-   **Incorrect date/time format:** A frequent issue with order imports is incorrect date or time formatting, which causes the import to fail.
-   **Address fields:** The **Country** field requires a two-letter code (e.g., **GB**, not "UK"). The Alpha-2 codes are available in this [list](https://www.iban.com/country-codes).
-   **Case-sensitive column headers:** Column headers must be entered with the correct casing (e.g., `vat_number`, not `VAT_number`). Incorrect casing causes the data in that column to be silently ignored and not imported, because the system does not recognize the header.
-   **Leading apostrophe errors:** Data in a cell cannot begin with an apostrophe ('). If an apostrophe is used, the system will not recognize the value, and an error may occur. **This rule is waived only if the article explicitly states that an apostrophe should be used for a specific field.**\- **Custom fields not populating:** Verify that the field's mapping is correct for its entity level (e.g., stop level, order level, shipment level). For instance, shipment-level fields need the header format `consignment_custom_field__[FIELD_ID]`. Similarly, make sure column headers are formatted according to the specification (e.g., `order_custom_field__[FIELD_ID]` with double underscores).
-   **File format alignment:** A mismatch between the selected import type and the uploaded file format (e.g., uploading an XLSX file when the system is set to CSV) can cause import failures without specific error messages. Make sure the file format matches the system's configuration settings to avoid issues.

-   **Imported value not populating:** If the custom field is not populated during import, make sure that:

    -   The import file uses the correct naming convention for the custom field.
    -   The import is being performed for the customer the mapping was configured for.
-   **Testing with the wrong customer:** If testing or importing for a different customer, the mapping will not apply. Verify that the test file corresponds to the correct customer.

-   **Unique order identifiers:** Each line must have a unique value in the `order_reference_number` column to avoid import errors.
-   **Transportation service required:** Each line must specify the type of transportation service; a missing value will result in errors or stalled imports.

* * *

### ✨ Best practices for importing orders {#h_0a5739f98e}

To ensure a smooth and accurate import, consider the following best practices.

-   **Import prerequisites first:** Before importing orders, make sure that all associated companies, locations, and products have already been successfully imported into the system.
-   **Test with a small batch:** 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 {#h_8d8f5ceb04}

Once orders have been successfully imported, they are available in the Orders module. They can then be planned, assigned to drivers, and dispatched as part of transport operations.

* * *

### 📈 Use cases for order import {#h_a78f7b03c9}

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 support 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.


## Related articles

- [Data import - Importing product data](https://help.qargo.com/us/articles/410133-data-import-importing-product-data.md)
- [Data import: importing container data](https://help.qargo.com/us/articles/410131-data-import-importing-container-data.md)
- [Data import: Importing contact data](https://help.qargo.com/us/articles/410121-data-import-importing-contact-data.md)
- [Data import – importing company data](https://help.qargo.com/us/articles/410118-data-import-importing-company-data.md)
- [Data import: Importing driver data](https://help.qargo.com/us/articles/410123-data-import-importing-driver-data.md)
