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