The location import feature is a powerful tool for populating a Qargo tenant with essential location information in bulk. This guide will walk through the process, from filling in the provided template to understanding the different configurable sections.
📖 Key Terminology
Location: A single physical address or business.
Order Import Alias: A unique identifier for a location used to link it to an external system for imports and exports.
Stop Prefill: A section that allows for prefilling specific details for any stops made at a location, such as duration or time windows.
✅ Critical Import Requirements & Limitations
Mandatory Fields: For an import to be successful, all mandatory columns must be filled in. This includes address, city, country, name, and postal_code.
Unique Identifiers:
row_id: This is the primary identifier. If a row_id is provided, the system will use it to match and update an existing location, overriding any other identifier.
order_import_alias__location_identifier: If a row_id is not present, this field will be used to identify the location. This is relevant only when an alias is being added or updated.
address: This is the default unique identifier and the most common use case. If neither a row_id nor an order_import_alias__location_identifier is provided, the system will use the address to identify or create the location.
When using the address as the unique identifier, the system will create a new location if the imported address is not an exact match to an existing one. This can lead to the creation of duplicate locations.
Stop Prefill Configuration: Stop prefill fields are only used if the stop_prefill__type column is filled in.
🛠️ Step-by-Step Data Import Process
Step 1: Download Template
A specific spreadsheet template is available to upload Location data:
📚 Always use a blank template downloaded directly from this article or provided by the Qargo team. Re-using an old template may lead to import errors.
Step 2: 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).
Step 3: Submit for Upload
During Onboarding: Work directly with your onboarding manager to upload your initial business data. They will guide you through the process and ensure a successful import.
After Onboarding: For all future data updates and imports, contact your account manager. They will assist you with the upload process and provide ongoing support.
📝 Details of the Location Import Template
The following table provides a detailed, field-by-field explanation of the Excel template for location import, which is divided into three parts: Location Details, Order Import Aliases, and Stop Prefill Configuration. This explanation includes data formats, required fields, and best practices for populating each column.:
Location Details
Column name | Required/optional | Remarks | Example |
name | Mandatory | The common name of the place or business. | Googleplex |
address | Mandatory | The primary street address of the location. | 1600 Amphitheatre Parkway |
address_second_line |
| An optional second line for additional address details, such as an apartment or suite number. | Suite 201 |
city | Mandatory | The city or town | Mountain View |
postal_code | Mandatory | The postal or zip code | 94043 |
state |
| The state, province, or region. | California |
country | Mandatory | The country where the location is found. | United States |
description |
| Detailed description of the place, its purpose, or its features. | A beautiful park with walking trails and a large playground. |
latitude |
| geographic coordinate (north-south) | 51.21049 |
longitude |
| geographic coordinate (east-west) | 3.808144 |
place_id |
| A unique identifier for the place, from google places | ChIJ2e6n95nFwoAR0pG9C-PTBOM |
display_name |
| The code and display name of the location | ABC-12345 |
row_id |
| Qargo internal Id (to force an update) |
|
selectable_on_customer_portal |
| Indicates which locations are visible in the customer portal. Visibility limited to ALL or NONE customers. | ALL |
Order Import Aliases
Column name | Required/optional | Remarks | Example |
order_import_alias__location_identifier | Mandatory if export or import is true. | Order import alias from external system. This fields will be used to match existing locations when filled in, if the import or export is true it will also create a new order import alias for this location if it is a new one | LOC12345 |
order_import_alias__export |
| Set to TRUE if the alias should be used for exporting orders. | TRUE |
order_import_alias__import |
| Set to TRUE if the alias should be used for importing orders. | TRUE |
order_import_alias__name |
| Use when the identifier is a technical code. | Main Warehouse |
order_import_alias__integration_partner |
| The integration partner for the export. This should be asked to the Professional services team | MORETMS |
Stop Prefill Configuration
Column name | Required/optional | Remarks | Example |
stop_prefill__type |
| Defines the type of the stop prefill, exceptions are not supported through bulk upload Supported values are: PICKUP , DELIVERY , OTHER , or ALL. Only one value is supported for each location | PICKUP |
stop_prefill__duration |
| Overwrite for the duration of the stop. This will override any default duration. | 6000 (seconds) |
stop_prefill__reference_number |
| Reference number to fill in on the stops. | REC-011 |
stop_prefill__notes |
| Additional info | Ring doorbell twice |
stop_prefill__time_start |
| Time window for this location. Format as HH:MM, where MM must be 00 or 30. | 09:00 |
stop_prefill__time_end |
| Time window for this location. Format as HH:MM, where MM must be 00 or 30. | 17:30 |
stop_prefill__time_window |
| Name of the window. This window must exist and the name should have the correct spelling, these need to be provided by the professional services team. | Full day |
stop_prefill__extras |
| ; separated list of extras This extra must exist and the name or code should have the correct spelling, these need to be provided by the professional services team. | Re-delivery ; First-delivery |
stop_prefill__custom_fields__<custom_field> |
| Name of the custom field. This field must exist and the identifier should have the correct spelling, these need to be provided by the professional services team. |
|
Opening Hours (spaces & single digits not allowed)
Column name | Required/optional | Remarks | Example |
opening_hours__monday |
| ; separated list of time intervals | 08:30-9:30;13:00-14:00 |
opening_hours__tuesday |
| ; separated list of time intervals | 08:30-9:30;13:00-14:00 |
opening_hours__wednesday |
| ; separated list of time intervals | 08:30-9:30;13:00-14:00 |
opening_hours__thursday |
| ; separated list of time intervals | 08:30-9:30;13:00-14:00 |
opening_hours__friday |
| ; separated list of time intervals | 08:30-9:30;13:00-14:00 |
opening_hours__saturday |
| ; separated list of time intervals | 08:30-9:30;13:00-14:00 |
opening_hours__sunday |
| ; separated list of time intervals | 08:30-9:30;13:00-14:00 |
🔎 Troubleshooting Common Location Import Errors
Missing Mandatory Fields: The import will fail if any of the mandatory fields (address, city, country, name, or postal_code) are left blank.
Duplicate Locations Created: This error occurs when the address is used as the unique identifier and the imported address does not exactly match an existing record. In such cases, the system will create a new location instead of updating the existing one. Ensure the address is an exact match or use the row_id or order_import_alias__location_identifier to update the record.
Incorrect Data Format: Ensure that data in fields such as country (The Country field requires a two-letter code, e.g., GB, not “UK”. You can see this list for Alpha-2 country code) and time_start (HH:MM) is formatted correctly.
Sheet name: The sheet name in the Excel template file must be named exactly 'Import'. Any other name will cause an error when uploading the file.
Invalid Stop Pre-fill Value: The import will fail if the value in stop_prefill__type is not one of the supported values.
Address Validation Error: An error occurs if the address cannot be validated by the Google Places API and the latitude and longitude coordinates are also missing. To resolve this, ensure the address is correct, or manually enter the latitude and longitude coordinates.
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 Locations
Use a New Template: Always use a blank template downloaded directly from the Qargo platform for each new import.
Clean Your Data: Before attempting an import, ensure that the data in your source file is clean, consistent, and correctly formatted to minimise errors.
Consider File Size: Be aware that importing longer sheets can take a significant amount of time to process.
➡️ What to Do Next
Once locations have been successfully imported, they can be used for order creation. They will appear as available pick-up and delivery points when creating a new job.
📈 Use Cases for Location Import
The location import is an invaluable tool for several key business processes:
Initial Tenant Setup: Populating a new Qargo tenant with a complete list of regular customer, supplier, or warehouse locations.
Adding New Locations: Bulk adding new business locations or pick-up/delivery points after a company expansion.
Integration Setup: Creating or updating a location's order import aliases to link it to an external system.