Summary
What — A new template-matching layer for Order import that automatically links an incoming EDI or API order to an Order template, inheriting the template's full planning structure (multi-stop route, intermodal legs, splits, subcontractor assignments, pricing).
Why — EDI/API orders previously arrived as flat pickup-to-delivery records. Dispatchers had to rebuild the planning structure manually for every imported order, even when the same route ran daily. Template-based import eliminates that repetitive work.
How — An Order import master is configured to require template matching (Qargo Admin only). When an order arrives, Qargo matches it to a template based on customer, transport service, and stop locations. The matched template's structure is applied to the new order. If no match is found, the import fails with an error and a dispatcher can manually assign the correct template.
Prerequisites
At least one Order template must exist and be correctly configured with the expected route structure.
Location aliases must be set up on the template's stops so incoming location references can be matched.
The Order import feature must be enabled for the tenant.
Template matching configuration is only available to Qargo admins (or super admins if the Create transformation mapping feature flag is enabled).
Use Cases
An intermodal operator receives daily EDI orders for the same ferry routes. Template matching automatically applies the correct departure, transfer, and delivery stops — removing the need for dispatchers to rebuild the route each time.
A transport company imports API orders for recurring customer lanes. The import master is configured to match on both collect and delivery locations, ensuring the right template (including subcontractor assignments) is selected.
An import order arrives with an unknown location alias. The import fails, and a dispatcher uses the Select template action to assign the correct template and complete the import manually.
Terminology
Term | Definition |
Order import master | A configured import source in Configuration → Order import that defines how incoming orders are processed. |
Order template | A pre-configured order in Qargo containing a full route structure — stops, transport service, subcontractor assignments, and pricing. |
Template matching | The process of automatically pairing an incoming import order with an Order template based on customer, transport service, and stop locations. |
Location alias | An alternative name for a location used to match incoming location references to Qargo locations in the template. |
Select template | A manual action on a failed import row that lets a dispatcher assign a template and retry the import. |
Configuring Template Matching on an Order Import Master
NAVIGATE to CONFIGURATION → Order imports
OPEN the relevant Order import master or create a new one.
ENABLE the 'Template matching' toggle. When enabled, all orders arriving through this import source must be matched to a template — there is no per-order opt-out.
SELECT the Match on setting:
Collect and delivery — the template is matched on both pickup and delivery locations (strictest matching).
Collect only — matched on pickup location only.
Delivery only — matched on delivery location only.
SAVE the configuration.
🧰 Template matching is only configurable by Qargo admins (or super admins with the Create transformation mapping feature flag). Contact Qargo Account Manager if more help is needed.
How Template Matching Works on Import
When an order arrives through a template-enabled import master:
Qargo checks the incoming order's customer, transport service, and stop location(s) against all available Order templates.
The number of consignments in the template must match the incoming order exactly.
Stop locations are matched using location aliases — the incoming location reference must correspond to an alias on the template's stops.
Setup and teardown stops are excluded from matching — only pickup and delivery locations are used.
If a matching template is found, the order is created using the template's structure, with the import data (dates, quantities, references) applied on top.
If no matching template is found, the import fails.
Handling Failed Template Imports
Failed imports appear in the Order import list with an error status.
OPEN ORDERS → Order imports to view the list.
IDENTIFY the failed row — it will show an error status indicating no template was found.
SELECT the Select template action on the row.
CHOOSE the correct template from the picker.
CONFIRM — the order is created from the selected template with the import data applied on top.
‼️ If the failure was caused by an unknown location alias, the alias must first be added manually to the relevant location on the template before the template can be matched.
Resolving Incorrect Address Selection
Incorrect address selection during imports or AI/OCR matching can disrupt operations. The sections below explain the common causes, steps to resolve them, and measures to prevent recurrence.
Common Causes
Import alias configuration. An incorrect import alias set on a location may cause Qargo to substitute one address for another when a specific name or alias appears in the import file. For example, if a location has an alias such as "Karlsgarde," Qargo may map this name to the wrong address.
AI/OCR matching errors. When importing data from documents such as PDFs, the AI/OCR system may suggest the wrong location if the location data in Qargo does not closely match the wording on the document. Misalignment in key fields such as location name, address, or display name can lead to incorrect matches.
Fixing Alias-Related Issues
To resolve problems caused by an incorrect import alias:
1. NAVIGATE to the location's settings.
2. OPEN the location record in Qargo that is being incorrectly selected.
3. LOCATE the Import/export Aliases section in the location profile.
4. EDIT the alias using the pencil icon to correct it, or remove the alias entirely if it is causing incorrect matches.
📚 Removing or correcting an incorrect alias ensures that future imports assign addresses based on the data provided, without substitution.
Improving AI/OCR Matching Accuracy
To help the AI/OCR system select the correct location:
1. Ensure that location data in Qargo matches the wording on the source document as closely as possible.
2. Align key fields - location name, address, and display name - with the document's terminology.
3. Use consistent and precise naming conventions across similar locations to give the AI clearer context for distinguishing between options.
Preventative Measures
Regularly review and update location aliases to ensure they accurately reflect the intended mappings.
Standardise naming conventions for locations and addresses in Qargo to minimise discrepancies between import data and Qargo records.
Test imports with sample data to verify that the correct addresses are being selected before rolling out a new import configuration.
Limitations
Always-on matching. Once template matching is enabled for an import master, all incoming orders through that source must map to a template. There is no way to create an order without a template through that source.
No retroactive re-application. Templates cannot be applied to orders that were already imported without one.
Strict consignment count. The template must have exactly the same number of consignments as the incoming import order.
Manual location aliasing. Location aliases must be created manually on the template's stops — there is no automatic alias generation.
No rule-based optimisation. If a route requires conditional extra stops or dynamic splits (e.g. emballage stops, location-based splits), these must already exist in the template. Template matching does not add or modify stops dynamically.
Customer portal imports. Portal users cannot select a template — portal orders go through the same automatic matching as EDI/API orders.
Troubleshooting
Issue | Likely Cause | Resolution |
Import fails with "no template found" error | No template matches the incoming customer, transport service, or stop locations | Check that a template exists for this route and that location aliases are correctly configured on the template's stops |
Import fails despite a matching template | Consignment count mismatch between template and incoming order | Ensure the template has the same number of consignments as the import order |
Select template action is not available | The import master does not have template matching enabled | Enable Use template matching in the import master configuration |
Template is found but wrong route is applied | Incorrect alias on a stop | Review and correct the location aliases on the matching template |
Incorrect address is selected during import | An incorrect import alias is configured on the location | Review and correct the alias in the location's Aliases section - see Resolving Incorrect Address Selection above |
AI/OCR suggests the wrong location from a document | Location data in Qargo does not closely match the wording on the source document | Align the location name, address, or display name in Qargo with the document's terminology |