Introduction
Qargo supports multiple ways to bring orders into the platform at scale. This article explains the key concepts and the main import paths used by most customers: integration partners and Qargo’s public API. You will also find links to resources for manual imports and pallet network workflows, plus a troubleshooting guide with common errors and how to resolve them.
Terminology
Term | Description |
Order | A shipment or consignment record in Qargo. Orders can include one or more stops and associated documents. |
Import | The process of creating or updating orders in Qargo by sending structured data from an external system. |
Source system | The system that originates the data, for example your TMS, ERP, WMS, or marketplace. |
Mapping | The transformation of fields from the source system to Qargo’s order schema. |
DTO (Data Transfer Object) | The structured payload used to carry order data into Qargo via integrations, EDI, or API. |
Validation | Qargo’s checks to ensure incoming data is complete, correctly formatted, and consistent with business rules. |
Acknowledgement | The response returned to the sender indicating success, partial success with warnings, or failure with errors. |
Idempotency key | A unique identifier generated by client & included with a request, typically in HTTP header; whose purpose is to ensure a request can be safely retried without unintended side effects, ie: duplication. |
Import paths overview
Qargo supports several import methods. This article focuses on the three most common automated paths.
Integration partners (pre-built connectors)
EDI partners (industry-standard document flows)
Qargo API (direct programmatic integration)
For manual file uploads and pallet network–specific flows, see:
Import via integration partners
Best for organisations using popular ERPs, WMSs, or logistics platforms that already have a Qargo-certified connector.
How it works
Your partner connector exports order data on a schedule or event.
The connector maps the partner’s schema to Qargo’s order DTO.
Data is transmitted to Qargo via a secure channel defined by the connector.
Qargo validates, ingests, and returns acknowledgements and error details.
Typical capabilities
Field mapping presets maintained by the partner
Incremental updates for order changes
Attachments support when the partner shares documents
Automatic retries and dead-letter handling
What you configure
Credentials or API keys provided by Qargo or the partner
Optional field overrides and value normalisation rules
Default behaviours for missing optional fields
Notification preferences for import failures
When to choose this
You want the fastest path to go-live with the least custom code
Your partner already supports Qargo or a very similar schema
Import via Qargo API
Best for teams that want full control and immediate feedback, or when a partner connector is not available.
Endpoint model
Create order
Update order
Attach documents and references
Retrieve and search orders for confirmation
Payload guidance
Use ISO 8601 for date-times with timezone offsets
Provide consistent units for weights, volumes, and counts
Include stable external IDs for idempotency and de-duplication
Send complete address blocks where possible, including country codes
Reliability patterns
Use idempotency keys to safely retry on network failures
Implement exponential backoff for 429 and transient 5xx responses
Log and surface validation errors to operations teams
Security
Use scoped API keys or OAuth as provided
Rotate credentials regularly and avoid hard-coding secrets
When to choose this
You control the source system and can build quickly
You need fine-grained control over payload shape, timing, and retries
🧰 Qargo API technical documentation available HERE.
Data mapping checklist
Before go-live, confirm the following are aligned between your source and Qargo:
Parties | Customer, shipper, consignee, payer, and contact roles consistently mapped. |
Locations | Names, addresses, country codes, and optional geo; avoid ambiguous free text. |
Dates and times | Pickup, delivery, and ready-by windows in ISO 8601 with explicit timezones. |
Goods details | Item lines, packages, pallets, dimensions, dangerous goods flags. |
Accessorials and addons | Surcharges and service-level options mapped to Qargo’s addon model. |
References | Customer order numbers, purchase orders, and trading-partner references. |
Documents | Attachments for CMR, POD, labels, and customs docs if available. |
Operational controls
De-duplication | Provide a stable external ID. Qargo can reject duplicates or upsert as configured. |
Partial updates | Decide whether updates replace full objects or patch specific fields. |
Status handling | Agree which events can be set by import vs. those driven by operations. |
Cutover strategy | Define a window when both old and new systems may run, and how to avoid double-booking. |
Best practices to prevent issues
Validate before send
Run a pre-check in your source system for required fields, date-time formats, and units.
Standardise codes
Maintain a lookup for services, equipment types, and accessorials that maps to Qargo codes.
Use idempotency
Always send idempotency keys for creates. Log the key-to-order ID mapping.
Monitor and alert
Set up notifications for failed imports and integrate error logs with your observability tools.
Document your mapping
Keep a living mapping document so future changes do not break imports.
Troubleshooting
Below are common errors seen during order imports, their likely causes, and how to resolve them. Error text may vary slightly depending on the import path.
Missing required field: customer_id
Symptom
Error: Missing required field: customer_id
Cause
The source did not provide a mapped customer or provided an unknown value.
Fix
Ensure the customer master exists in Qargo and the mapping uses the correct external key.
For partners, update the connector mapping.
For API, include customer_id or a resolvable external_customer_ref.
Invalid date-time format for pickup_window.start
Symptom
Error: Invalid date-time. Expected ISO 8601 with timezone
Cause
Datetime sent without timezone or in a non-ISO format.
Fix
Send ISO 8601 strings, for example 2025-03-12T08:00:00+01:00.
Validate formats in your source before sending.
Unknown location: consignee_address
Symptom
Error: Location validation failed for consignee
Cause
Incomplete or ambiguous address, or a reference to a non-existent saved location.
Fix
Provide full address including country code.
If using location references, synchronise master data first.
Unsupported addon code: LIFTGATE_PREMIUM
Symptom
Error: Addon code not recognised
Cause
Source uses a service code that is not configured in Qargo.
Fix
Add or map the code to a supported addon in Qargo.
Normalise codes in your connector before transmission.
Duplicate order detected with external_id=ABC-123
Symptom
Error: Duplicate order
Cause
Idempotency or de-duplication flagged a repeated create.
Fix
If intentional retry, reuse the same idempotency key and check the previous result.
If a true duplicate, change the external_id or convert to update.
Document attachment rejected: file type not allowed
Symptom
Error: File type not supported
Cause
Attachment type not on the allowed list.
Fix
Convert to a supported format, typically PDF or image types configured for your workspace.
Ensure your integration sends MIME types correctly.
API 429 Too Many Requests
Symptom
HTTP 429 responses and throttling headers.
Cause
Burst traffic exceeds rate limits.
Fix
Implement exponential backoff and respect retry-after headers.
Smooth batch sizes and schedule imports to off-peak windows.
“Fix errors?” prompt on the Order Import screen
Symptom
User sees a banner or inline prompts during review.
Cause
One or more imported orders have validation issues requiring operator input.
Fix
Open the order, review highlighted fields, and correct the values.
If the same issue reoccurs, update your mapping rules at the source.
Order Pre-fills (configured by Qargo Admin)
If pre-filled order data appears incorrect or not as expected, it could be related to Order Import mapping.
Fields included in the order import mapping will take priority over any other default values elsewhere in the platform; pre-fills from the customer profile for instance.
Where other options are defined, that include multiple options to select (ie: extras), the values from the order import are included, along with any options that are already selected.
FAQ - Pre-fills
Q. How to give precedence to certain pre-fills if it can come from different sources for the same target field.
Example: Start / End time windows - pre-fills can be defined:
Transport service
Customer
Location
Time Window
A. The most specific pre-fill will be applied. In the example above, the logic follows how granular the selections are: First, select transport service, then customer and locations, followed by time window for the stop. So in this instance, the pre-fill is taken for the last selection (Time window) as this would be considered the most specific option
Q. Is there a way to pre-fill with the opening hours of the location, or does this have to be manually entered for each imported order? Is there a quick way to pull in times when the locations are available for collection / delivery?
A. Yes, it's possible to pre-fill opening hours for locations when importing orders, and including that in the stop time window settings. This ensures there is clear visibility of when the stop action can be completed, if no specific appointment or time window is required. There is a feature flag that can be enabled, which will automatically use the opening hours defined on the location for order imports.
💬 Contact Qargo Support, or your Account Manager if you would like to enable this feature.
Best practices to prevent issues
Validate before send
Run a pre-check in your source system for required fields, date-time formats, and units.
Standardise codes
Maintain a lookup for services, equipment types, and accessorials that maps to Qargo codes.
Use idempotency
Always send idempotency keys for creates. Log the key-to-order ID mapping.
Monitor and alert
Set up notifications for failed imports and integrate error logs with your observability tools.
Document your mapping
Keep a living mapping document so future changes do not break imports.