Matching carrier rate confirmations to booked loads without guessing

When a carrier signs a rate confirmation, the broker wants three things to happen: the rate con lands on the right load, the load shows the carrier and the pay, and nobody types it twice. The middle step is the hard one. This paper describes how SmartLoads decides which load a rate con belongs to, and why most of that decision is plain rules.

For what a rate con is and how it differs from a notice of release or a bill of lading, see the document guide.

Why matching is hard

The number printed on a rate con comes from one of several numbering systems:

• The broker's TMS, for example an Aljex Pro number.
• The SmartLoads load number.
• Sometimes the shipper's own reference.

These systems don't share numbers. A customer load number and an Aljex Pro number can collide by accident. And because a shipper's board is re-imported every day, one customer number can sit on dozens of archived rows from past days.

Lanes collide too. One plant can ship three loads to the same city on the same day, at the same rate. Matching on lane alone would be a coin toss.

So the matcher looks for agreement between independent facts, and when it can't find enough, it asks a person.

Reading is the SI's job, deciding is the rules' job

The rate con arrives as a PDF or a photo, by email forward or from the SmartLoads panel in Outlook. The SI reads it into a fixed set of fields: broker, load number, shipper and pickup numbers, carrier name, MC, DOT and contact, driver, truck and trailer, equipment, carrier pay, and each stop's city, state and date. It also answers one question first: is this a carrier rate confirmation at all?

Everything after that is a pure function, decideRateConMatch(extract, candidateLoads), with no model involved. It returns one of three results, a ranked list of up to five candidate loads, and a note in plain words saying why. The same function serves both entry points, the forwarding address and the Outlook panel, so a rate con matches the same way however it arrives.

Finding candidates

Candidates are always scoped to the agency that received the rate con. The pipeline collects two groups:

1. By number. Loads whose Aljex Pro number or SmartLoads load number equals the printed number, on any date, up to five per column. The Aljex Pro number is on the load when an earlier Aljex invoice match linked it.
2. By lane window. Loads with a board date within three days of the printed pickup date, filtered by the pickup and delivery states when they're printed. With no printed date, the window reaches back ten days from today.

Tier 1: the printed number, if the load fits

A number hit counts only when the load also fits the rate con:

• The load isn't booked to a different MC than the one printed.
• Printed pickup and delivery states don't contradict the load's states.
• With a printed pickup date, the load's ship date or board date is within three days of it.
• With no printed date, the pickup and delivery states both match and the load is booked.

If exactly one numbered load fits, it's a match: "Matched on load number …". A number that points only at loads that don't fit becomes "possible", with a note to check it.

Tiers 2 and 3: the lane near the pickup date

A lane matches when the pickup and delivery cities are the same after normalizing ("Saint" and "St", "Fort" and "Ft", punctuation and spacing), and the states agree whenever both sides have one.

Loads on the lane within three days are candidates. Only loads within two days, and not already linked to another rate con, can be auto-matched. Then:

• Tier 2. If exactly one of them is booked to the carrier whose MC is printed on the rate con, it's a match.
• Tier 3. If none matched by MC, and exactly one is booked but not yet covered (and not booked to a different MC), it's a match. A rate con usually arrives right after booking, so the one load waiting for its rate con is the natural answer.

Lanes never auto-match without a printed pickup date. A rate con with no date can still match by its number, but never by lane alone.

When it isn't sure

Anything else is "possible" or "unmatched":

Possible candidates are ranked: MC match first, then booked but uncovered, then uncovered, then the closest date. Number hits that didn't fit come after, newest board date first, so a pile of archived rows can't push today's load off the list. The note says why it stopped: "Several booked loads fit equally well; pick the right one", or "The rate con has no pickup date; pick the right load on this lane".

The own-brokerage guard

One document looks a lot like a rate con and isn't: the shipper's notice of release. It names the brokerage as the carrier and shows the rate the shipper pays the brokerage. Read as a rate con, it would record the brokerage as its own carrier at the customer's rate.

So before matching, any "rate con" whose carrier is the brokerage itself, and which the brokerage didn't issue, is reclassified as shipper paperwork. Names are compared after normalizing: "&" and "and" drop out, as do suffixes like LLC and Inc. The issuer is what separates the two cases, because the brokerage's own rate con to a carrier with a similar name is issued by the brokerage.

The cover is a person's click

A match changes nothing on the load. The load shows "Rate con received" and a broker or admin clicks Mark covered. That write has its own guards:

• It only lands if the load is still not covered, and still booked or unbooked exactly as the dialog showed it. A second click, or a booking made in the meantime, is never overwritten.
• Per-ton loads are refused. Their carrier rate is per ton, so a rate con's total would be multiplied by the tons.
• A different carrier replaces the old carrier's MC, DOT and driver.
• Each agency chooses whether Mark covered may also book an unbooked load. A database trigger enforces "booked loads only" even if a screen read the setting before an admin changed it.

SI never books or covers a load. That holds here by construction: the match result has no write path.

Testing

decideRateConMatch is pure and Deno-tested against fixtures for each tier, the no-date case, the other-carrier case, a load that already has a rate con, and archived copies of a load number. The own-brokerage check has its own tests. Because the SI only fills fields, a change in how a document is read can't change the matching rules, and a change in the rules can be tested without calling a model.

When a rate con reaches the agency's rate con address, its other systems can hear about it too: the Partner API sends a rate_con.received webhook. For the same read-then-match pattern on shipper paperwork, see the Cover Card, and for reading scanned PDFs in general, validation first.

Frequently asked questions

Why not let the SI pick the load?

Because the answer has to be right and explainable. A model can read a messy PDF well, but choosing between three similar loads is a rules question with a correct answer. Rules can be tested, they give the same answer twice, and every match carries a note saying why.

What happens when the rate con has no pickup date?

It can still match by its printed load number, if the states match a booked load. It never matches by lane alone. The candidates are listed and a person picks.

Can a rate con cover a load automatically?

No. A match only shows "Rate con received" on the load. A broker or admin clicks Mark covered, and that write checks the load hasn't changed since the dialog opened.

How does it avoid matching an old load with the same number?

A number hit must also fit the pickup date within three days, or the states on a booked load. Old rows with the same number fail that check and drop to the bottom of the candidate list.