Skip to main content
HomeBlogGuidesHow to Connect Shipment Tracking Data to an Oms: Order Mapping and Sync Rules

How to Connect Shipment Tracking Data to an Oms: Order Mapping and Sync Rules

17TRACK

To connect shipment tracking data to an order management system (OMS), map each tracked package to an internal shipment record, then link that shipment to its order and fulfillment lines. Receive tracking updates through the provider’s supported interface, preserve the original events, and apply explicit rules for duplicates, late updates, shipment status, and order completion. Do not use a tracking number alone as the order identifier or let a single delivery event automatically close a multi-package order.

How to Connect Shipment Tracking Data to an Oms Order

This guide is for integration engineers and ecommerce operations teams implementing that connection. The recommended design separates carrier observations from business decisions: tracking data describes a package’s journey, while the OMS decides what that journey means for fulfillment, customer communication, and order closure.

Define which system owns each record

Before building an API connection, agree on ownership with the OMS administrator, fulfillment team, and customer-service team. Otherwise, a technically successful integration can still overwrite valid business data.

  • OMS: Owns orders, order lines, required quantities, cancellations, and the rules for order completion.
  • Fulfillment system: Owns the shipment or package records it creates, including packing allocations and label assignments. This may be the OMS itself or a separate warehouse system.
  • Tracking provider: Supplies tracking observations and any provider-defined status classifications.
  • Integration layer: Owns identifier cross-references, event processing, normalization, retry handling, and synchronization audit records.

Treat these as recommended boundaries, not assumptions about your software. Document exceptions. For example, if the warehouse can replace a shipping label, the integration needs an explicit update from that system rather than guessing that a newly observed number replaces an old one.

Build the order-to-package mapping before syncing statuses

A practical relationship is order → fulfillment → package → tracking assignment. Your OMS may use different names or combine some of these records. Preserve the relationships even if the database structure differs.

An order can have several fulfillments, and a fulfillment can contain several packages. A package may also acquire a replacement tracking assignment or a linked last-mile identifier. Those identifiers should not create additional ordered quantities.

RecordRecommended fieldsPurpose
OrderTenant or store ID, immutable OMS order IDSeparates merchants and avoids dependence on display order numbers.
FulfillmentFulfillment ID, order ID, allocated line IDs and quantitiesIdentifies which purchased items are being fulfilled.
PackageInternal package ID, fulfillment ID, package allocations where availableProvides a stable identity independent of tracking labels.
Tracking assignmentAssignment ID, package ID, provider account, carrier identifier, tracking number, active periodLinks incoming tracking observations to the correct package and assignment lifecycle.

Match updates through a stored cross-reference

When a shipment is created, persist its internal IDs before registering it for tracking. Store any provider-issued tracking record ID returned by the documented registration process. If the provider supports a merchant reference, use an opaque internal reference and retain the mapping locally.

For incoming updates, first resolve the stored provider record ID within the correct provider account and tenant. If that identifier is unavailable, use the documented combination of tracking number, carrier identity, account context, and assignment history. Treat this as a lookup strategy, not a guarantee that the combination is globally unique.

Do not match by customer name, email address, or an unscoped display order number. Preserve tracking numbers as strings so leading zeros survive. Avoid stripping characters or changing case unless the relevant carrier or provider contract permits that normalization.

If a lookup returns no match or several possible matches, quarantine the update for investigation. An unresolved event is safer than a confident update to the wrong customer’s order.

Handle split orders without inventing package allocations

Consider an illustrative order containing three units. Package A carries two units, and Package B carries one. Delivery of Package A means two units have delivery evidence; it does not mean the entire order is delivered.

If the fulfillment system records only that both packages belong to the same fulfillment, do not invent unit-level allocations. You can still calculate whether all required packages are delivered, but item-level delivery reporting should remain unavailable or explicitly uncertain until allocation data exists.

Connect the tracking API through a durable ingestion layer

Use a pipeline that keeps provider communication separate from OMS writes:

Shipment creation → tracking registration → incoming update or scheduled retrieval → durable event storage → mapping and normalization → OMS update → reconciliation

For a 17TRACK implementation, the Tracking API product page and official API documentation are the relevant starting points. Confirm the applicable registration interface, carrier identifiers, update delivery options, authentication requirements, status definitions, and account limits before implementing the adapter. The data model in this guide is an integration recommendation, not a claim that 17TRACK uses these field names or provides a native connector for your OMS.

If your selected provider supports webhooks, authenticate incoming requests using its documented mechanism and durably store accepted messages before acknowledging them. Keep slow OMS work outside the request path. Follow the provider’s actual acknowledgement and retry contract rather than assuming a particular response body or timeout.

If polling is required, store retrieval progress where the API supports it, control concurrency, and follow documented rate limits. Neither webhook receipt nor a successful polling request proves that the OMS was updated; record those outcomes separately.

Define sync rules that survive retries and late events

1. Make processing idempotent

Processing the same observation twice should not duplicate a shipment, advance quantities twice, or send the same customer notification again. HTTP does not make an arbitrary POST operation idempotent; the integration must implement duplicate protection. RFC 9110 explains HTTP method idempotency.

Use a stable provider event ID when one is documented and available. Otherwise, define a fingerprint from the assignment ID and relevant event fields, such as the event timestamp, source status, and location. Document the possibility of collisions or changed event descriptions. Keep the raw observation even when it does not produce another OMS action.

Protect each side effect separately. For example, an OMS status write and an email notification need their own deduplication controls. Use a transactional outbox or equivalent durable work record so a process crash cannot leave an accepted event without a scheduled update.

2. Store event time and receipt time separately

An event’s occurrence time and the time your integration received it answer different questions. Store both, along with the original timestamp representation and any supplied timezone offset. Do not silently assign the warehouse timezone to an event whose timezone is unknown.

A late-arriving in-transit scan should normally enrich history without replacing a newer delivered state. However, timestamps alone are insufficient: a provider may issue a correction, and events may have incomplete time information. Use documented sequence or revision fields when available, plus an explicit correction policy.

3. Normalize statuses without erasing source detail

Create a small internal vocabulary that the OMS understands, such as awaiting carrier acceptance, in transit, out for delivery, delivered, exception, and returning. Map the provider’s documented statuses into it. These are suggested internal categories, not universal carrier definitions.

Store the original status code, description, event location, provider record reference, and mapping-rule version. An unmapped value should create a reviewable condition rather than defaulting to delivered or failed. Label creation should not be treated as proof of physical carrier acceptance unless the source event explicitly supports that interpretation.

4. Use transition rules, not a simple numerical ranking

Shipment states do not always form a straight line. An exception can be followed by normal transit, and a delivery attempt is not delivery. Return movement may begin after an earlier delivery event.

  • Allow an exception to clear when subsequent evidence supports resumed movement.
  • Prevent an ordinary historical scan from silently replacing a delivered state.
  • Allow a documented correction through a controlled revision path.
  • Track return movement separately from outbound completion where the OMS supports it.
  • Route ambiguous or contradictory evidence to an operational queue.

Version these rules. When a mapping changes, decide whether it applies only to new events or whether historical records require a controlled recalculation.

Calculate order status from required fulfillment obligations

Package status and order status should be separate fields. A package marked delivered supplies evidence for that package; order completion depends on the remaining required quantities and your business policy.

A useful default is to mark an order fully delivered only when all delivery-required quantities have valid package-level delivery evidence and no required allocations remain unresolved. Exclude canceled quantities according to the OMS’s cancellation rules. Handle digital items, pickup orders, and other non-shipping obligations through their own completion conditions.

Replacement shipments require explicit relationships. If a lost package is replaced, decide whether the replacement supersedes the original delivery obligation. Otherwise, the original package may block completion indefinitely, or both packages may count toward fulfillment. Record the decision rather than deriving it from tracking status alone.

Keep delivery completion separate from financial closure, refund eligibility, and dispute resolution. A carrier delivery event should not automatically authorize a refund or settle a customer claim.

Recover from failures without losing the audit trail

Retry transient failures using bounded backoff and any documented retry guidance. Separate temporary connection failures from invalid identifiers, expired credentials, permission errors, and schema incompatibilities. The latter require corrective action, not endless retries.

Maintain a failed-work queue containing the affected tenant, package, event reference, attempted operation, error classification, and next action. Log enough context to investigate without copying unnecessary customer data or credentials into logs.

Run reconciliation in addition to the normal update path. Review active shipments with stale tracking information, accepted events whose OMS writes failed, unmatched observations, and differences between the integration’s calculated state and the OMS. Choose review frequency based on delivery commitments, API limits, and operational risk rather than applying an arbitrary universal schedule.

Assign ownership: engineering handles ingestion and write failures; fulfillment operations resolves missing package relationships; customer service reviews exceptions that require customer communication. A queue without an accountable owner is only a storage location.

Test the mapping and business rules before launch

Use controlled fixtures and a limited production rollout. Test the following cases against both the event history and the resulting OMS record:

  • A single-package order progresses normally to delivery.
  • A split order has one delivered package and one still moving.
  • The same event is received repeatedly without duplicate side effects.
  • An older transit scan arrives after delivery.
  • An unknown carrier or status enters the review queue.
  • A label is replaced without creating another fulfillment obligation.
  • A replacement shipment supersedes an original package under an approved rule.
  • The OMS is unavailable after an event has been accepted.
  • A process restarts between an OMS write and its acknowledgement.
  • The same display order number exists in two stores without cross-tenant matching.

Launch when every accepted event has a traceable processing outcome, ambiguous matches cannot update orders automatically, and operators can replay failed work safely. These are more useful acceptance criteria than simply demonstrating that an API request succeeds.

FAQ

Can I connect tracking numbers directly to orders?

For a strictly single-package workflow, a direct relationship may be sufficient initially. Still, use an internal shipment identity between the order and tracking assignment. It provides a migration path for split shipments, relabeling, and replacements without changing the meaning of the order record.

Should the integration use webhooks or polling?

Use the delivery mechanism supported by the provider and compatible with your infrastructure. Webhooks can reduce repeated retrieval, while polling can support retrieval-based workflows and reconciliation where available. Neither approach removes the need for durable storage, duplicate handling, and recovery.

What should happen when a tracking event has no matching order?

Store it in an unmatched-event queue and investigate the registration record, tenant context, carrier identity, and shipment creation timing. Do not create an order or attach the event to a plausible customer automatically. Replay it after the mapping is corrected.

Should delivery notifications come from the OMS or the tracking system?

Choose one owner for each notification type and trigger. If two systems can send the same message, disable one path or share a durable notification ledger. Also decide whether a message refers to one package or the complete order, especially for split fulfillment.

Does an exception status mean the order has failed?

No. An exception is an observation requiring interpretation, not necessarily a permanent outcome. Preserve the reason, monitor subsequent events, and use your escalation policy to decide when operations should intervene.

Sources