Summary
Kuehne+Nagel shipment tracking information can be transferred into iPaaS.com through a scheduled polling event or an on-demand Manual Sync. Each transfer attaches a Transaction Tracking Number record to an existing iPaaS.com Transaction, carrying the shipment's Bill of Lading number, the carrier's shipper code, and the status Kuehne+Nagel currently reports for it. The result is that delivery status is readable on the order it belongs to, inside iPaaS.com, without looking the shipment up in Kuehne+Nagel.
ID Format
Manual Sync ID Format
Enter the Kuehne+Nagel Bill of Lading number and the carrier SCAC code, joined by a pipe character:
{BlNumber}|{Scac}
For example: KN123456789|KUEH, where KN123456789 is the Bill of Lading number and KUEH is the Kuehne+Nagel SCAC code.
Both parts are required and the pipe separator must be present. A value in any other shape is rejected and the transfer does not run.
External ID Format
After a successful transfer, iPaaS.com records the combined Bill of Lading number and SCAC code as the external-id link on a dedicated external-id record. Subsequent transfers of the same shipment follow that link and update the existing tracking record instead of creating a second one.
Deleted Record Support
Outbound delete is not supported. Deleting a shipment in Kuehne+Nagel does not remove the corresponding tracking record from iPaaS.com, delete mappings are not included in the default templates, and deletions do not propagate in either direction.
Mapping Collection Status
Status: Enabled. The mapping collection has no filter applied, so every shipment returned by Kuehne+Nagel is processed.
Trigger Events: the shipment/poll event. Kuehne+Nagel does not notify iPaaS.com when a shipment changes, so transfers run on the schedule set for that event, or on demand through Manual Sync.
Duplicate or Conflicting Mappings
This is the only mapping collection in the Kuehne+Nagel integration, so nothing else within this integration writes to the same records.
If another integration in the same iPaaS.com company also writes Transaction Tracking Number records, both can attach tracking to the same Transaction. Review the filters and the Add/Update settings on those collections and decide which system is the source of truth for shipment status before enabling this collection.
Configurable collision handling is not offered for this collection. Records are matched by their external-id link, and a shipment that has transferred before updates its existing tracking record rather than creating a duplicate.
Supported Child Collections
None. This is a standalone collection with no child collections; the whole tracking record is written in a single step.
System Caveats
Kuehne+Nagel Caveats
API access must be granted before setup: access to the Kuehne+Nagel API is not open by default. It must be requested and approved, and the credentials it returns are required for every call. See Setup Requirements below.
Shipments are read, never written: this collection only reads shipment information from Kuehne+Nagel. Nothing is created, changed, or deleted in Kuehne+Nagel by this integration.
Status values follow Kuehne+Nagel's vocabulary: the status message, appointment text, and reason text are stored exactly as Kuehne+Nagel supplies them. iPaaS.com does not translate them into a standard status list, so reporting built on these values should expect Kuehne+Nagel's own wording.
Status time is informational: Kuehne+Nagel supplies the status date and the status time separately, and does not publish a fixed format for the time value. It is stored as text and is not parsed, validated, or converted to the subscription's time zone. Treat it as a display value rather than a value to calculate with.
Appointment detail is often absent: appointment fields are populated only for shipments that have a delivery appointment recorded.
Rate limits are not published: Kuehne+Nagel does not publish call limits for this API. Control how hard the integration calls it using the throttle and concurrency settings on the subscription, and stagger large catch-up polling runs rather than running them alongside other heavy jobs.
iPaaS.com Caveats
The Transaction must already exist: a shipment can only be attached to an iPaaS.com Transaction that is already present. This collection never creates the Transaction, and no Transaction is transferred automatically as a prerequisite.
Reference Number must match Transaction Number exactly: the match is exact, including case and any leading zeros. A shipment whose Reference Number differs from the Transaction Number in any way does not transfer.
The Shipping Method must already exist: the value mapped to ShippingMethod is validated against the Shipping Methods configured in the subscription. See Integration-Specific Caveats below.
The custom fields must be available on the collection: the eight status and billing values are written to iPaaS.com custom fields. Subscribers or their MiSP can add these from the mapping editor using + Add Custom Field if they are not already present.
Integration-Specific Caveats
ShippingMethod ships with a placeholder value: Placeholder value — replace during implementation: the collection ships with ShippingMethod set to the fixed value Flat Rate, which is a starter value rather than a real Kuehne+Nagel service. Pre-install prerequisite — the transfer fails without it. Before enabling this collection, subscribers or their MiSP MUST do EITHER of the following: create a Shipping Method named exactly Flat Rate in iPaaS.com, OR change the ShippingMethod mapping's static value to the name of a Shipping Method that already exists in iPaaS.com. Without one of these, every transfer through this collection fails and the error appears in Dashboard / Integration Monitoring / Error Logs.
Kuehne+Nagel shipping method names are not created automatically: If you want the real carrier service recorded on each shipment rather than one fixed value, create the corresponding Shipping Methods in iPaaS.com first, then replace the static mapping with a field or formula mapping that resolves to one of those names.
Only the first matching Transaction is used: Where more than one iPaaS.com Transaction shares a Transaction Number, the shipment attaches to the first match found.
The polling look-back filter must be a whole number: The polling event accepts an optional filter value that widens each run's search window. Any value that is not a whole number causes the polling run to fail.
Setup Requirements
Kuehne+Nagel Configuration
Complete these steps in Kuehne+Nagel before configuring the subscription in iPaaS.com.
Email the Kuehne+Nagel Helpdesk at helpdesk@ec.kuehne-nagel.com to request API access. Include your Company Name, Contact Name, Phone Number, Email Address, and the Purpose of API Usage — for this integration, shipment tracking.
The Helpdesk returns an Authentication ID and a Client Code. Both are required for every call the integration makes.
Access may be subject to approval or to regional limitations depending on your service agreement.
iPaaS.com Configuration
Enter the credentials returned by the Helpdesk, your Kuehne+Nagel website user ID, and the Kuehne+Nagel API address in the subscription settings. The full walkthrough is in the Kuehne+Nagel Installation Instructions.
Create the Shipping Method that ShippingMethod maps to, or repoint the mapping at one that already exists.
Confirm the iPaaS.com Transactions the shipments will attach to are present, and that their Transaction Numbers match the Reference Numbers Kuehne+Nagel carries.
Enable the shipment/poll event in the subscription configuration's Inbound Data Flows section and set the schedule it should run on. No automatic transfers occur until this is enabled.
Integration Flow
A transfer is triggered, either by the scheduled shipment/poll event or by a Manual Sync.
For a polling run, the integration asks Kuehne+Nagel for shipments updated since the previous successful run and processes each one it finds. For a Manual Sync, it processes the single shipment identified by the ID entered on the Manual Sync page.
The integration retrieves the current details for the shipment from Kuehne+Nagel, identified by its Bill of Lading number and carrier SCAC code.
It reads the Reference Number from the returned shipment. If the Reference Number is missing, the shipment does not transfer and an error is recorded.
It searches iPaaS.com for a Transaction whose Transaction Number matches that Reference Number exactly. If no match is found, the shipment does not transfer and an error is recorded.
The field mappings are applied and the tracking record is written against the matched Transaction — creating it on first transfer, or updating the existing record on subsequent transfers via the external-id link.
The outcome is recorded so that successes are visible in the activity log and failures appear in Dashboard / Integration Monitoring / Error Logs.
Mappings
Add/Update Kuehne+Nagel Transaction Tracking Number TO iPaaS.com
iPaaS.com data type: Transaction Tracking Number
Description. Captures the current status of a Kuehne+Nagel shipment onto an existing iPaaS.com Transaction. Four values are written to standard tracking fields and eight to custom fields. This mapping collection has no mapping filter applied, so every shipment returned by Kuehne+Nagel is processed.
Mapping Type | Source Field (Kuehne+Nagel) | Destination Field (iPaaS.com) | Description |
Field | TransactionId | ParentId | Required. Links the tracking record to the iPaaS.com Transaction it belongs to. Not a field Kuehne+Nagel returns — the integration resolves it by matching the shipment's Reference Number to an iPaaS.com Transaction Number. Leave this mapping as delivered; remapping it breaks the link between the shipment and its Transaction. |
Static |
| ShippingMethod | Required. Validated against the Shipping Methods configured in the subscription; it must match an existing Shipping Method name exactly. Placeholder value — replace during implementation: either create a Shipping Method named Flat Rate or repoint this mapping at one that already exists, before enabling the collection. |
Field | BlNumber | TrackingNumber | Recommended. The Kuehne+Nagel Bill of Lading number, stored as the tracking number a user reads off the Transaction. The transfer succeeds without it, but the tracking record has little value. |
Field | ShipperCode | ShippingMethodDescription | Recommended. The Kuehne+Nagel shipper code, stored as free text alongside the shipping method. Not validated against any iPaaS.com record. |
Field | StatusMessage | Status Message (custom field) | Recommended. The shipment's current status text, exactly as Kuehne+Nagel reports it. The most useful of the status values. |
Field | StatusDate | Status Date (custom field) | Recommended. The date on which the current status was recorded. Kuehne+Nagel supplies date and time separately, so read it with Status Time. |
Field | StatusTime | Status Time (custom field) | Recommended. The time of day the current status was recorded. Stored as text and informational only — not parsed, validated, or time-zone converted. |
Field | StatusTimeCode | Status Time Code (custom field) | Recommended. The time code returned alongside the status time; provides the context needed to read Status Time. Map it wherever Status Time is mapped. |
Field | ReasonMessage | Reason Message (custom field) | Recommended. Explains the current status where Kuehne+Nagel supplies a reason. Empty on shipments moving normally. |
Dynamic Formula |
| Appointment Message (custom field) | Recommended. Captures the delivery appointment message. Kuehne+Nagel returns it only for shipments with an appointment recorded, so rather than storing an empty value the formula substitutes the fixed text Appointment Message is empty. Subscribers or their MiSP can edit the formula to return the source value unchanged. |
Field | AppointmentReasonMessage | Appointment Reason Message (custom field) | Recommended. Explains why an appointment was set, moved, or missed. Stored exactly as received, with no substitute value. |
Field | BillToCode | Bill To Code (custom field) | Recommended. The Kuehne+Nagel bill-to party code. Stored as text and not validated against any iPaaS.com record. |
Error Handling
"Could not transfer because the Shipment Id was not provided in the correct format. Expected format: {BlNumber}|{Scac}": the shipment identifier entered for a Manual Sync is not in the required form. Resolution: re-enter it as the Bill of Lading number and SCAC code joined by a pipe character, for example
KN123456789|KUEH."Could not transfer because the Kuehne+Nagel shipment has no Reference Number. Shipment Id: {ShipmentId}": the shipment record returned by Kuehne+Nagel has no Reference Number, so there is nothing to match an iPaaS.com Transaction on. Resolution: add the Reference Number to the shipment in Kuehne+Nagel, then retry the transfer.
"Could not transfer because no iPaaS.com Transaction has Transaction Number {ReferenceNumber}. Kuehne+Nagel Shipment Id: {ShipmentId}": no iPaaS.com Transaction has a Transaction Number matching the shipment's Reference Number. Resolution: confirm the Transaction exists in iPaaS.com and that its Transaction Number matches the Reference Number exactly, including case and leading zeros, then retry.
A shipping method error when the tracking record is written: the value mapped to ShippingMethod does not match a Shipping Method configured in the subscription. Resolution: create the Shipping Method with that exact name, or change the mapping to a Shipping Method that already exists.
Errors appear in Dashboard / Integration Monitoring / Error Logs. For anything not resolved by the steps above, contact iPaaS.com Support at support@ipaas.com.
Testing & Validation
Test Scenarios
Successful tracking sync: Create a Transaction in iPaaS.com whose Transaction Number matches the Reference Number on a Kuehne+Nagel shipment. Trigger a Manual Sync for that shipment and confirm the tracking record is created with the tracking number, shipping method, and status values populated.
Update of an existing tracking record: Change the status on a shipment already synced, then transfer it again. Confirm the same tracking record is updated — that Status Date, Status Time, and Status Message change and no second record appears.
Scheduled polling: Enable the shipment/poll event, then confirm that shipments updated since the previous run transfer automatically on the next scheduled run.
Look-back window: Set the polling event's optional filter to a whole number of days and confirm the next run picks up a shipment revised after its status date.
Missing Reference Number: Attempt to transfer a shipment with no Reference Number and confirm the transfer stops with an error rather than creating a partial record.
No matching Transaction: Attempt to transfer a shipment whose Reference Number has no matching iPaaS.com Transaction and confirm the transfer stops with an error naming the Reference Number.
Invalid Manual Sync ID: Enter a shipment identifier without the pipe separator and confirm the transfer is rejected with a format error.
Unconfigured shipping method: With ShippingMethod pointing at a name that does not exist in iPaaS.com, attempt a transfer and confirm it fails; then create the Shipping Method and confirm the same transfer succeeds.
Validation Checklist
The Kuehne+Nagel API credentials are entered in the subscription settings and the subscription connects.
A Shipping Method matching the ShippingMethod mapping exists in iPaaS.com.
The iPaaS.com Transactions the shipments will attach to exist, with Transaction Numbers matching the shipments' Reference Numbers.
The eight custom fields are available on the mapping collection.
The shipment/poll event is enabled and its schedule is set.
A Manual Sync using the
{BlNumber}|{Scac}format completes and the tracking record appears on the expected Transaction.Status values on the transferred record match what Kuehne+Nagel reports for the shipment.
Additional Notes
Out of Scope
Writing to Kuehne+Nagel: this collection transfers data in one direction only, into iPaaS.com. Booking, updating, or cancelling shipments in Kuehne+Nagel is not supported.
Deletions: not propagated in either direction.
Creating the Transaction: this collection attaches tracking to an existing Transaction only.
Creating Shipping Methods: Kuehne+Nagel service names are not created in iPaaS.com automatically.
Configurable collision handling: not offered for this collection.
Operational Notes
Tracking information is only as current as the last polling run, because Kuehne+Nagel does not notify iPaaS.com when a shipment changes. Shortening the schedule makes status more current at the cost of more calls to Kuehne+Nagel.
Kuehne+Nagel sometimes revises a shipment after the status date it carries. If polling searches only since the last run, such a revision can fall outside the window — set the look-back filter to cover the delay your shipments typically show.
Bulk historical loading is not supported, so an existing backlog of shipments is not loaded on first connection. To bring a large set in at once, use bulk sync using Postman.