Skip to main content
How-to

Total Quality Logistics (TQL) LTL Freight

Total Quality Logistics (TQL) is a freight broker that quotes less-than-truckload (LTL) shipments across many carriers at once. When you connect your TQL account, UltraCart asks TQL for a quote during checkout and shows your customer a single TQL: LTL shipping method priced at the lowest rate TQL returns.

Before you start​

You need a TQL account with API access. The TQL API uses five credentials, and UltraCart needs all of them:

  • Subscription Key: your TQL API subscription key.
  • Client ID and Client Secret: the API client credentials TQL issues to you.
  • TRAX Username and TRAX Password: the login you use for TQL's TRAX portal.

Your freight items also need freight classes and pallet packages. If you have not set those up yet, the Gold Coast freight tutorial walks through packages and item freight settings, and the same setup applies to TQL.

Enable TQL as a shipping carrier​

Turning on the TQL carrier adds a TQL tab to your shipping configuration, where you enter your credentials.

  1. Go to Main Menu > Configuration > Checkout > Shipping.
  2. On the Carriers tab, select the TQL checkbox.
  3. Select TQL in the Shipping Config menu on the left.
  4. Enter your Subscription Key, Client ID, Client Secret, TRAX Username, and TRAX Password.
  5. Leave Use Staging Environment cleared. Select it only while TQL has you testing against their staging system, because staging rates are not real prices.
  6. Click Save.

Add the TQL: LTL shipping method​

The TQL: LTL method is what your customers see at checkout. It appears in the method list only after the TQL carrier is enabled.

  1. Go to Main Menu > Configuration > Checkout > Shipping > Methods.
  2. Click New Method.
  3. Choose A single built-in shipping method, select TQL: LTL, and click Continue.
  4. If your customers may need a lift gate at delivery, select Lift Gate Option on the method.
  5. Save the method.

For the rest of the method settings, such as markups and restrictions, see Shipping Methods.

How UltraCart prices a TQL shipment​

UltraCart sends TQL one quote request per order and uses the cheapest price in the response. TQL can return several carriers and service levels (Standard, Guaranteed, and Volume), and your customer sees only the lowest one, as TQL: LTL.

The request is built from your packing solution:

  • Handling units: each pallet or box in the packing solution becomes one handling unit. Pallet packages are sent as pallets, crate packages as crates, and everything else as boxes.
  • Freight class: each handling unit uses the highest freight class of the items packed on it. A unit with no freight class set is sent as class 55. Classes 77 and 92 are sent as 77.5 and 92.5.
  • Residential delivery: when the shipping address is residential, UltraCart tells TQL the delivery is to a residence, so the quote includes that charge.
  • Lift gate: when the method has Lift Gate Option selected and the customer asks for a lift gate, UltraCart requests a delivery lift gate, so the quote includes that charge.
  • Shipment date: TQL does not quote pickups on weekends or holidays. A shipment date that falls on a Saturday or Sunday is sent as the following Monday. If TQL refuses a weekday as a holiday, UltraCart asks again for the next business day, up to three more times, and notes the date it used in the packing solution.

UltraCart stores the TQL quote ID on the order, so you can find the quote in TRAX when you book the shipment.

note

UltraCart rates TQL shipments only. Booking the shipment with a carrier and tracking it happen in TQL's TRAX portal.

TQL quotes shipments within and between the United States, Canada, and Mexico. For any other origin or destination, the TQL: LTL method is not offered.

When TQL rates do not appear​

If TQL: LTL is missing at checkout, open the packing solution for the order and look for the TQL entry in the No Estimates for Shipping Methods section. The message there tells you what went wrong:

  • TQL credentials are not configured: one of the five credential fields on the TQL tab is empty.
  • TQL could not log in with the TQL credentials in the shipping settings: TQL refused the login. Check each value against what TQL issued, and confirm your TRAX password has not changed. After a refused login, UltraCart waits 15 minutes before trying the same credentials again, so your checkout is not slowed by a login that keeps failing. Saving corrected credentials on the TQL tab ends the wait right away.
  • TQL is reporting a 401 Unauthorized or 403 forbidden: TQL rejected the credentials when asked for a quote. Check each value against what TQL issued.
  • TQL could not quote this shipment: TQL checked the shipment and found a problem with it. The rest of the message says what to fix:
    • TQL does not recognize the city, state and postal code of the shipping address together: the customer's city does not match the postal code, or the postal code is wrong. Correct the shipping address and estimate again.
    • TQL does not recognize the city, state and postal code of the ship from address together: the same problem with the address you ship from. Check the address on your distribution center.
    • TQL does not quote shipments picked up on a weekend or holiday: TQL refused the shipment date and the next few business days too, which can happen around a run of holidays. Try again after the holidays.
    • Any other text comes from TQL and names the problem it found, such as a missing dimension.
  • TQL is reporting a bad request: TQL refused the request without saying why. The text after the message is TQL's raw response. Send it to UltraCart support, along with the integration log described below.
  • TQL is reporting an internal error at this time: TQL's system had a problem answering. Try again later, and contact TQL if it continues.
  • TQL returned no carrier prices for this shipment: TQL answered, but none of its carriers quoted the shipment.
  • TQL only ships between the United States, Canada, and Mexico: the origin or destination is outside those countries.

For how to open the packing solution and read the other messages, see Troubleshooting Shipping.

Send TQL the request and response from the integration log​

Each failed TQL quote writes an integration log entry with the exact request UltraCart sent to TQL and the response TQL returned. TQL support usually asks for these when you report a quoting problem, so copy them from the log instead of rebuilding the shipment by hand.

  1. Go to Main Menu > Operations > Reporting and open Integration Logs - Errors.
  2. Find the TQL entry with the time of the failed quote, and open it.
  3. Send TQL the parts they ask for:
    • request: the quote request JSON, exactly as UltraCart sent it.
    • response: TQL's reply to the quote request, with the HTTP status in the summary.
    • token_request and token_response: included when UltraCart could not get a bearer token (TQL's login token). Your password is masked, and the client secret and subscription key show only their last four characters.
    • log: a summary that says whether UltraCart obtained a bearer token, which TQL environment it used, and the error your customer saw.

UltraCart writes an entry only when it contacted TQL and the quote failed. Missing credentials and unsupported countries do not create one, and neither does a repeat attempt during the 15-minute wait after a refused login. For how long entries are kept and the other ways to view them, see Integration Health Logs.

Was this page helpful?