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.
📖 Glossary of Key Terms
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.
Order Import Aliases: The order_import_alias__location_identifier field will be used to match existing 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 Excel template is available to upload Location 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 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 |
row_id |
| This is a unique identifier in qargo to match existing locations. ONLY use existing qargo location IDs, filling this in will force an update. | 5955c91c-5e37-4ea5-8029-d80d3d3a5fbc |
address |
| Must be a valid street address. | 1600 Amphitheatre Parkway |
address_second_line |
| Use for apartment or suite numbers. | Suite 201 |
city |
| This is a unique name that identifies the location in the system. | Mountain View |
display_name |
| This is a unique name that identifies the location in the system. | ABC-12345 |
country |
| The country where the location is found. Use Alpha-2 country codes. | US |
name |
| This is the primary name that will be displayed. | Googleplex |
description |
| Can be used to add more context. | A beautiful park... |
latitude |
| A number representing the north-south coordinate. | 51.2104 |
longitude |
| A number representing the east-west coordinate. | 3.808144 |
place_id |
| Used to match locations from Google Places. | ChIJ2e6n... |
postal_code |
| The postal code of the location. | 94043 |
state |
| The name of the state. | California |
Order Import Aliases
Column name | Required/optional | Remarks | Example |
order_import_alias__location_identifier | Mandatory if export or import is true. | This is the order import alias. | LOC12345 |
order_import_alias__export |
|
| 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 |
| Must be an ENUM from the list provided by Professional Services. | MORETMS |
Stop Prefill Configuration
Column name | Required/optional | Remarks | Example |
stop_prefill__type |
| Supported values are: PICKUP , DELIVERY , OTHER , or ALL. Only one value is supported for each location | PICKUP |
stop_prefill__duration |
| 1800 | This will override any default duration. Must be |
stop_prefill__reference_number |
| REF-12345 | Used for tracking purposes. |
stop_prefill__notes |
| Ring doorbell twice | Provides instructions for drivers. |
stop_prefill__time_start |
| Format as HH:MM, where MM must be 00 or 30. | 09:00 |
stop_prefill__time_end |
| Format as HH:MM, where MM must be 00 or 30. | 17:30 |
stop_prefill__time_window |
| Standard Business Hours | This window must already exist in the system, and the name must be spelled correctly. These names need to be provided by the Professional Services team. |
stop_prefill__extras |
| Re-delivery ; First-delivery | ; separated list of extras Each extra must exist and the name should have the correct spelling, these need to be provided by the professional services team. |
🔎 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.
✨ 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.