Skip to content
English
Customer portal
Go to Tai Software
  • There are no suggestions because the search field is empty.

Dispatch Internals: Triggers, Paths, and Status Rules

How the Tai TMS dispatches a load: what triggers it, API first with EDI 204 fallback, the status-transition rule, re-dispatch, and carrier exceptions.

This internal article documents the exact mechanics the Tai TMS uses to dispatch a shipment to a carrier — what triggers a dispatch, which legs dispatch, when it uses an API versus an EDI tender, the precise status-transition rule, how a rejected dispatch is retried, and the carrier-specific exceptions staff should know.

Overview

This is the staff-only reference for how electronic dispatch actually decides what to do. It covers what starts a dispatch, which transit legs are eligible, the "API first, EDI fallback" decision, the precise rule that determines whether a successful dispatch advances a shipment to Dispatched or only to Sent, how the carrier's EDI response completes an EDI dispatch, how staff re-send a rejected dispatch, and the known carrier exceptions (CoyoteGO, Dayton Freight, FedEx, EDI Express, TForce Guaranteed, Xpress Global). It also clarifies the division of labor between the main TMS and the standalone carrier-integration service. Use it when explaining why a shipment landed in a particular status after dispatch, or why a dispatch did or did not happen.

How it works

When a shipment's leg is set to Ready (or is re-sent by staff), the TMS runs its dispatch logic:

  1. What triggers a dispatch. A dispatch starts when a standard status update sets a transit leg to Ready — from the shipment's Update Status screen, from a bulk status update, or when a shipment is created with a leg at Ready or a save changes a leg to Ready. Staff can also re-send a dispatch with the Dispatch Again button on the shipment screen (it appears only while the shipment carries the Rejected by Carrier alert and re-sends the linehaul leg), and TMS Admin has a Force API Dispatch tool on its accounting-summary page. A status update to Sent or Dispatched does not by itself start a dispatch. Status changes that the system writes on its own while processing a dispatch result, or that cascade from a consolidated shipment to its children, do not start one either.
  2. Leg eligibility. Only two kinds of transit leg are dispatchable: the main line-haul leg and a delivery-local leg. Any other leg type — including a consolidated shipment's consolidation leg — is ignored: dispatch does nothing for it.
  3. Status gate. The target leg must be at the Ready or Sent stage for dispatch to run. If it is at any other status, dispatch does nothing unless a forced dispatch is explicitly requested (a force flag bypasses the status gate).
  4. Which carrier connection is used. For the line-haul leg the TMS uses the tariff's dedicated dispatch connection if one is configured, otherwise the tariff's main carrier connection. For a delivery-local leg it uses that leg's tariff connection.
  5. Choose the path — API first. The system uses the direct API path when the carrier's integration supports API dispatch and the carrier connection has "Enable API Dispatch" turned on (a forced dispatch also selects the API path). "Supports API dispatch" means there is a carrier API capability record for that carrier's integration type marking it as API-dispatch-capable.
  6. The API call. The TMS builds the request from the shipment (stops, commodities, accessorials mapped to the carrier's codes for outgoing or both-direction dispatch accessorials, reference numbers, service level) and posts it to the carrier-integration service. The default request timeout is about 15 seconds; a carrier connection can override it with a dispatch timeout setting. If the service answers "unauthorized", the dispatch is recorded as a failed API dispatch with an authentication error.
  7. After a successful API dispatch the TMS writes two automation-log entries marked as API — a load tender and an accepted response — so API dispatches appear alongside EDI tenders in automation reporting.
  8. EDI-204 fallback. If the API attempt does not succeed (it returned a failure or returned no response at all), or the API path was not available for the carrier, and this is not a forced dispatch, and the line-haul carrier has an enabled EDI setting, and the carrier connection has "Enable EDI 204" turned on, then the system queues an outbound EDI 204 load tender instead, and the dispatch is recorded as an EDI dispatch. If those fallback conditions are not all met, there is no EDI attempt. Queued EDI tenders are sent by a background job that runs about every ten minutes.
  9. Apply the outcome and set status (see the precise rule below).
  10. Follow-up work. After a dispatch attempt the system also runs insurance handling for the shipment, records returned reference numbers, attaches returned documents, and — when the carrier's response includes a bill-to address — saves that address on the shipment and, where the tariff has a bill-to, can add the factoring company as a billing party.

Because an API failure is processed before the EDI fallback is considered, a shipment whose API dispatch failed can already carry a Rejected by Carrier alert even though an EDI 204 was then queued successfully.

Business rules & limits

Precise status-transition rule

When a dispatch succeeds, the shipment is advanced to Dispatched only if all three of these are true:

  • the shipment was actually dispatched (the carrier accepted), and
  • the shipment's status before the attempt was earlier in the lifecycle than Sent (that is, it was Quote, Committed, or Ready — not already Sent or later), and
  • the dispatch was carried out over the API path (not EDI).

If any of those is not true, a successful dispatch sets the shipment to Sent instead of Dispatched. In particular, a successful EDI dispatch results in Sent, never Dispatched, because EDI acceptance is confirmed asynchronously. A successful Dispatch Again on a shipment that is already Sent also stays at Sent, because the status before the attempt was not earlier than Sent.

When a dispatch fails but the carrier is configured, the shipment status is set through the same rule (which resolves to Sent) and a "Rejected by Carrier" alert is added if one is not already present. When a dispatch fails because dispatch is disabled/not configured, a configuration error ("Dispatch not available or configured for carrier ...") is recorded instead of a rejection alert. Every dispatch error is written to the shipment's private activity log as "Dispatch Error - Code: ... - Message: ..."; any error text that contains HTML markup is replaced with a generic "something went wrong" message before it is written.

How the carrier's EDI response completes an EDI dispatch

After an EDI 204 tender, the carrier's EDI 990 response drives the status. An accepted response (reservation action A or B) moves the shipment to Dispatched; a declined response (D) sets it to Sent and adds the Rejected by Carrier alert. The pickup number (reference qualifier P8) is saved as the carrier pickup number if the shipment does not already have one, and the PRO number (qualifier CN) is saved when it differs from the current one. Later carrier EDI 214 status messages and carrier API tracking move the shipment forward only: they are ignored for a Quote, ignored once the shipment is Delivered or later, and never set an earlier status than the shipment already has.

Reference numbers saved from a successful dispatch

The pickup number is saved as the carrier pickup number on the line-haul leg, or as the delivery carrier PRO number when the delivery-local leg was dispatched. A returned PRO number is saved only if the shipment has no line-haul PRO number yet. A returned BOL number is saved as the secondary BOL number, and any returned quote number, API quote number, tracking reference, or custom reference is saved too. (Forward Air is a special case: its pickup number is also used as the PRO number when none exists.) A returned BOL link is not stored on the shipment. A private activity-log entry "Submitted to carrier (...) for API Dispatch" lists what was saved.

CoyoteGO exception

CoyoteGO is deliberately excluded from advancing to Dispatched. Even on a successful dispatch it is left at Sent, and a follow-up order-status job is scheduled to run one minute later to retrieve the real status asynchronously. This is intended behavior — do not treat a CoyoteGO load sitting at Sent right after dispatch as a bug.

Dayton Freight exception

For Dayton Freight, if the carrier returns a pickup number, any dispatch errors that came back are suppressed (cleared) and only logged as a private note rather than surfaced as a rejection, and the returned PRO number is logged. So a Dayton Freight dispatch that produced a pickup number is treated as successful even if the carrier also returned error text.

EDI Express tracking exception

EDI Express is a normal carrier integration with its own dispatcher (not a generic EDI failover). Separately, when carrier API tracking for an EDI Express shipment that is at Sent reports the second attempt at a rescheduled pickup, the shipment is moved to Dispatched.

FedEx dispatch (Freight toggle and e-Pro option)

FedEx dispatch has two independent carrier-connection settings. The ship with e-Pro option chooses between booking through FedEx's shipment endpoint (on) and creating an LTL pickup request (off). The FedEx Freight (LTL) toggle switches authentication to FedEx's separate freight identity service with a freight-scoped credential, for both paths; on the e-Pro path it also books through FedEx's freight shipment endpoint instead of the standard one. Functionally the dispatch returns the usual pickup/PRO/BOL identifiers through the normalized result, but a FedEx Freight account used with the toggle off — or a standard FedEx account with the toggle on — fails authentication, and a freight authentication failure returns a message about a FedEx platform mismatch. So when troubleshooting a FedEx dispatch that fails only at the authentication step, confirm the FedEx Freight toggle matches the kind of FedEx account the credentials belong to.

Other carrier-specific request rules

  • TForce: a connection can be switched to TForce's newer REST dispatcher with the "use updated V2" setting. Within it, a shipment with the Guaranteed service level goes through TForce's shipping service, which needs the pickup stop's scheduled ready and close times (sent with seconds). A missing ready or close date fails the dispatch with "A pickup ready date is required." or "A pickup close date is required."
  • Xpress Global: the pickup and consignee stops send the stop's email contact as well as the phone number, and each commodity line is sent as "Rolls" when its package type is roll and "Pallets" otherwise.

Enable flags that gate dispatch

Two per-carrier-connection settings gate electronic dispatch:

  • Enable API Dispatch — must be on (together with the carrier's integration actually supporting API dispatch) for the real-time API path to be used.
  • Enable EDI 204 — must be on, along with the line-haul carrier having an enabled EDI setting, for the EDI-204 fallback to fire.

If neither path is enabled/available for the carrier, dispatch is reported as "not available," which is the normal "not configured" outcome rather than a failure. For LTL shipments the shipment screen also shows the notice "Electronic dispatching is not available for this shipment" when neither path is available; that notice is worked out from the tariff's main carrier connection, not from a separate dedicated dispatch connection, so it can disagree with what a dispatch will actually do for a tariff that has a dedicated dispatch connection.

Where staff see dispatch results

The reliable places to read a dispatch outcome are the shipment's status, its alerts (Rejected by Carrier), its reference numbers, and its private activity log. The Update Status screen contains pop-up messages for "dispatched," "dispatch failed," and "not available," but in the code reviewed on 2026-10-12 they depend on a status field that the update-status response no longer returns, so they should not be expected to appear. The Dispatch Again button does show a success message or the carrier's error codes and messages.

Division of labor: main TMS vs. carrier-integration service

  • The API-to-EDI failover decision lives in the main TMS, not in the standalone carrier-integration service. The main TMS decides whether to call the API, and, if that fails, whether to queue an EDI 204.
  • The standalone carrier-integration service performs API dispatch only. It resolves the right carrier dispatcher (about 110 carrier connection types are mapped, several sharing a dispatcher), calls the carrier's API, and returns a single normalized result. It always labels its result as an API dispatch and has no EDI fallback of its own. (One supported carrier happens to be named "EDI Express," but that is a specific carrier integration, not a generic EDI failover mechanism.)
  • The carrier-integration service is error-tolerant by design: individual carrier dispatchers do not throw out; every failure — authentication, timeout, server error, or a generic exception — is captured and returned as a dispatch-error entry rather than crashing the call. "Success" is inferred as "no errors returned and dispatch not disabled," not a flag the carrier sets. Callers must inspect the returned result. Generic error messages are truncated (to about 1000 characters) for logging, and only some error entries carry an error code (authentication/timeout/server); others carry only a message.
  • A carrier connection type that has no dispatcher mapped fails outside that error-tolerant wrapper, because the dispatcher is looked up before the wrapper starts; it does not come back as a tidy "unsupported carrier" result.
  • Missing required credentials or parameters for a carrier (username, password, license key, or account number) surface as a configuration/authentication error before the carrier is even called; a required parameter with a disallowed value surfaces as a support-facing error.

Timing and other limits

  • API dispatch is effectively synchronous (default request timeout is about 15 seconds), so acceptance and reference numbers come back within seconds.
  • EDI dispatch is queued/batched: tenders are sent roughly every ten minutes and the carrier's response arrives on the carrier's own schedule; this is why EDI never advances a shipment straight to Dispatched.
  • The standalone dispatch endpoint does not validate the inbound request shape up front, so a malformed dispatch request is not rejected early — problems instead surface as returned dispatch errors.

Frequently asked questions

What starts an electronic dispatch in the Tai TMS?

In the Tai TMS a dispatch starts when a standard status update sets a transit leg to Ready (single or bulk update, a shipment created with a Ready leg, or a save that changes a leg to Ready). Staff can re-send with the Dispatch Again button, which appears when the shipment has the Rejected by Carrier alert, and TMS Admin can use Force API Dispatch. Setting a shipment to Sent or Dispatched by itself does not start a dispatch.

Which transit legs can be dispatched in the Tai TMS?

In the Tai TMS only the main line-haul leg and a delivery-local leg are dispatchable. Any other transit-leg type — including the consolidation leg of a consolidated shipment — is ignored by the dispatch logic, so dispatch will simply do nothing for those legs.

When does the Tai TMS use API dispatch versus an EDI tender?

The Tai TMS uses the real-time API path when the carrier's integration supports API dispatch and the carrier connection has "Enable API Dispatch" turned on (a forced dispatch also uses API). If the API attempt fails or returns no response, or the API path is not available, and it was not a forced dispatch, and the line-haul carrier has an enabled EDI setting with "Enable EDI 204" turned on, the TMS falls back to queuing an EDI 204 load tender. If those fallback conditions are not all met, no EDI attempt is made.

After a successful dispatch, why did the shipment go to Sent instead of Dispatched?

In the Tai TMS a successful dispatch advances a shipment to Dispatched only when the carrier accepted, the status before the attempt was earlier than Sent, and the dispatch went over the API path. If the dispatch was via EDI, or the shipment was already at Sent or later (for example a Dispatch Again after a rejection), or any of those conditions is not met, a successful dispatch resolves to Sent instead. A successful EDI dispatch in particular always lands on Sent until the carrier's EDI 990 response accepts the tender.

How does an EDI tender get from Sent to Dispatched?

In the Tai TMS the carrier's EDI 990 response does it. An accepted response (action A or B) moves the shipment to Dispatched and saves the carrier's pickup number (if the shipment has none) and PRO number; a declined response (D) sets the shipment to Sent and adds the Rejected by Carrier alert.

Why is a CoyoteGO shipment sitting at Sent right after I dispatched it?

In the Tai TMS, CoyoteGO is intentionally kept at Sent even on a successful dispatch, and a follow-up order-status job runs one minute later to pull the real status asynchronously. This is expected behavior for CoyoteGO and is not a dispatch failure.

Does the standalone carrier-integration service handle the EDI fallback?

No. In the Tai TMS the standalone carrier-integration service performs API dispatch only — it calls the carrier's API and returns a normalized result, always labeled as an API dispatch, with no EDI fallback of its own. The decision to fall back to an EDI 204 tender is made upstream in the main TMS, not in that service.

What determines whether electronic dispatch is even attempted?

In the Tai TMS, dispatch is attempted only for a line-haul or delivery-local leg whose status is Ready or Sent (a forced dispatch bypasses that status gate). Beyond that, the API path requires the carrier to support API dispatch and the connection's "Enable API Dispatch" setting to be on, and the EDI fallback requires an enabled carrier EDI setting plus the connection's "Enable EDI 204" setting. If none of those are available, dispatch reports as "not available," which is the normal not-configured outcome.

Why does a failed dispatch sometimes show a "Rejected by Carrier" alert and other times a configuration error?

In the Tai TMS, when a dispatch fails but the carrier is actually configured for dispatch, the shipment gets a "Rejected by Carrier" alert (added only if one is not already present). When the failure is because dispatch is disabled or not configured for that carrier, the system records a configuration error ("Dispatch not available or configured for carrier ...") instead. The two messages distinguish a real carrier rejection from a missing/disabled integration.

A shipment has a Rejected by Carrier alert but an EDI tender went out. Is that a bug?

No. In the Tai TMS an API failure is processed before the EDI fallback is considered, so the alert is added and the status set to Sent first; the fallback then queues the EDI 204. Read the activity log and the carrier's EDI 990 response to see the real outcome.

Is there anything special about Dayton Freight dispatches?

Yes. In the Tai TMS, if Dayton Freight returns a pickup number, any dispatch errors that also came back are suppressed and only logged privately rather than raised as a rejection, and the returned PRO number is logged. So a Dayton Freight dispatch that produced a pickup number is treated as successful even if error text accompanied it.

Why does a FedEx dispatch fail authentication for one FedEx account but work for another?

In the Tai TMS, the FedEx Freight (LTL) toggle on the carrier connection switches authentication to FedEx's separate freight identity service (with a freight-scoped credential), and on the e-Pro path it also changes the shipment endpoint. The two are not interchangeable, so a FedEx Freight account used with the toggle off — or a standard FedEx account with the toggle on — fails at the authentication step. When a FedEx dispatch fails only on authentication, confirm the FedEx Freight toggle matches the kind of FedEx account the credentials belong to.

Why did a TForce Guaranteed dispatch fail with a pickup date message?

In the Tai TMS, a TForce shipment with the Guaranteed service level is booked through TForce's shipping service, which requires scheduled ready and close times on the pickup stop. If either is missing the dispatch fails with "A pickup ready date is required." or "A pickup close date is required." Fix the pickup stop's times and use Dispatch Again.