TMS Integration For Freight Forwarders: Data Mapping And Go-Live Checklist

Start with the workflow you want to connect

Define one complete business workflow before mapping every available field.

For a freight forwarder, an initial scope might be:

Approved customer → accepted quote → TMS booking record → shipment updates → customer-facing status

Write down what starts the process, what each system must do and how the team will confirm completion.

For example, “send accepted quotes to the TMS” is incomplete. A usable requirement explains:

• Which quote version is transferred.
• Whether acceptance automatically creates a booking request or requires review.
• Which customer and branch records are used.
• Which costs, selling charges and service terms are included.
• How the destination record is identified.
• What happens when the transfer fails.

VelocityOS describes connections for rates, bookings, tracking and documents on its TMS integration page. The implementation plan should confirm the specific fields, directions and workflows required for your existing TMS.

TMS Integration Data Mapping Checklist

Data mapping defines how a field in one system becomes a meaningful value in another. Identifiers, units, time zones, ownership and failure rules must agree as well as field names.

The following are business concepts, not literal API field identifiers.

Define ownership and direction

Specify the authoritative system for each object. A two-way connection needs conflict rules: latest received is not always latest correct.

Distinguish omitted fields from intentional empty values or deletion so partial updates do not erase useful information.

Test repeats and failures

Use stable identifiers to prevent duplicates. Retain enough evidence to investigate and safely replay failed updates. Check that out-of-order events cannot incorrectly move a shipment to an earlier state.

Approve the mapping

Document source field, destination field, transformation, owner and example. Business users should approve meaning; technical teams should verify exchange behavior.

See what VelocityOS can sync for the broader object groups.

Practical TMS integration mapping table

Use the following structure as a starting point. Replace the example systems and owners with your actual setup.

The error owner should be a named team with a clear escalation route. Technical support may repair a connection, but pricing or operations must resolve incorrect business data.

Which fields need mapping?

Field mapping needs to explain meaning as well as names. Two fields labelled “status” may describe entirely different stages.

For each field, record its source, destination, format, required status, transformation and owner.

Customer and organization fields

Map customer identifiers, legal entities, branches, addresses and contact details. Confirm whether billing and operational contacts are separate.

Do not match customers by company name alone. Similar names, spelling variations and multiple branches can create incorrect links.

Quote and booking fields

Include:

• Quote reference and accepted version.
• Customer and branch identifiers.
• Transport mode and movement scope.
• Origin and destination.
• Cargo description, package count, weight and volume.
• Equipment type and quantity, where applicable.
• Buy and sell charges with currencies and charging bases.
• Validity, exclusions and required dates.

Specify whether a blank field means “unknown,” “not applicable” or “remove the existing value.” These meanings should not be treated as interchangeable.

Shipment events and documents

Map shipment references, event codes, event timestamps and time zones. Keep estimated and actual dates separate.

For documents, include the document identifier, type, version, linked shipment and access classification. A draft bill of lading should not automatically replace an approved document without the agreed review process.

What should trigger an update?

Choose triggers based on business events.

Agree on expected update timing for each object. A booking request may need prompt processing, while a periodic reference-data update may have a different requirement.

Keep the time the business event occurred separate from the time the integration processed it.

How do you prevent duplicate records?

Duplicate prevention should be designed before enabling automatic creation.

Use stable identifiers that include enough context to distinguish the source system, organization and record. Maintain a mapping between the source identifier and the destination identifier.

For example:

Commercial booking request BR-2087 → TMS record TMS-64102

If the same request is delivered again, the integration should recognize the existing relationship instead of creating another booking.

Important controls include:

• A unique reference for each creation request.
• A duplicate check that remains effective when two requests arrive together.
• Safe repeat processing, often called idempotency.
• A record of successfully processed events.
• Version checks for older updates arriving late.
• Rules preventing an update from bouncing endlessly between systems.

The duplicate key must reflect the business action. A customer identifier alone cannot distinguish several legitimate bookings for the same customer.

What happens when a sync fails?

A failed transfer should become visible work with an owner, rather than disappearing into a log.

Retries are appropriate for some temporary failures, but not every error. They also need to avoid repeating an action that already succeeded. Microsoft’s retry-pattern guidance explains these distinctions.

Give operators a practical error view showing the affected record, failure reason, last attempt, owner and next action. Keep sensitive data and credentials out of diagnostic messages.

Illustrative example: the booking was created, but the response was lost

This is a hypothetical implementation example, not a description of a specific deployed connector.

1. A customer accepts quote Q-1042, version 2.
2. The commercial platform creates booking request BR-2087.
3. The integration sends the request to the TMS with a stable request identifier.
4. The TMS creates record TMS-64102, but the response times out.
5. The integration marks the result as unconfirmed and checks the request identifier.
6. It finds the existing record and stores the relationship.
7. The commercial platform displays the TMS reference without creating a duplicate.

The team must also distinguish record creation from carrier confirmation. A booking record in the TMS does not, by itself, confirm space with the carrier.

How should permissions and document access work?

Treat integration access and user access as separate responsibilities.

An integration account should have only the access required for its approved workflow. The destination system must still enforce which users and customers can see or change the received information.

Define:

• Which offices can access each customer and shipment.
• Whether sales users can see buy costs or only selling prices.
• Who can approve pricing changes or cancellations.
• Which document types customers can view.
• Who can upload, replace, download or withdraw documents.
• How access is removed when a user or customer relationship changes.

Test access using actual role combinations. A successful document transfer is not sufficient if the file becomes visible to the wrong customer.

If documents are shared by link, confirm that opening the link requires the appropriate authorization. Avoid treating possession of a URL as proof of permission.

What must pass testing before go-live?

Agree on expected results before running the tests.

Reconciliation should compare more than record counts. The counts can match while prices, statuses or customer associations are wrong.

Record Integration Acceptance Evidence

Keep one result for each required test, including failures that were corrected and retested. A successful API response alone does not establish that the right customer, amount, document or shipment status reached the right record.

Set release-blocking conditions before testing. For example, a duplicate booking, incorrect charge, lost update or unauthorized document access should remain open until corrected and retested. Document any accepted limitation with an owner, workaround and review date. Pass the integration decision into the wider freight software implementation plan, where it becomes one of the overall go-live gates.

Go-live checklist

Before enabling production transfers:

• Approve the object and field mappings.
• Confirm record ownership and conflict rules.
• Complete customer, branch and reference-code mappings.
• Record test results and resolve release-blocking defects.
• Configure production credentials and access.
• Assign monitoring, business-data and escalation owners.
• Identify records already transferred during migration.
• Agree how changes made during migration will be captured.
• Start with a controlled group of users or shipments where practical.
• Prepare a recovery plan for failed or incorrect transfers.

The recovery plan should explain how to pause processing, preserve pending work and reconcile records already created. Turning off a connection does not undo bookings, documents or other actions that have already occurred.

After launch, review failed transfers, processing delays, duplicate-prevention events and reconciliation differences. Keep this review active until the agreed acceptance conditions are met.

Where VelocityOS fits into the implementation

VelocityOS documents synchronization options across commercial and operational data. Use the overview of what Velocity can sync to identify candidate objects, then confirm the required mappings and connector behaviour with the implementation team.

A clear implementation scope should specify the systems involved, supported objects, direction of updates, validation rules, failure ownership and acceptance tests.