Breakthrough Fuel (BTF) Integration

What is the Breakthrough Fuel Integration?

Shipwell integrates with Breakthrough Fuel (BTF), a technology-driven fuel management provider, so shippers can obtain highly accurate, real-time fuel surcharge (FSC) calculations directly from BTF. Customers who use Breakthrough Fuel can connect their BTF account directly to Shipwell. Once connected, fuel surcharges on qualifying shipments are calculated automatically using BTF's data — no manual entry or external reconciliation required — for more accurate billing, improved transparency, and a streamlined fuel surcharge workflow, all from within your Shipwell account.

How it works

You link your existing Breakthrough Fuel account through the Integration Marketplace using your BTF Client ID and Client Secret. Once connected, you configure one or more Fuel Surcharge (FSC) tables to use Breakthrough Fuel as the data source. When a qualifying shipment is picked up, Shipwell automatically calls Breakthrough with the shipment's details and applies the returned fuel surcharge as a financial line item (charge code 405) — no action required.

Requirements

An active Breakthrough Fuel account with a Client ID and Client Secret (contact Breakthrough Fuel directly to establish one).
The integration is self-service — connect it yourself via the Integration Marketplace; no additional enablement is required.

Setting up: connecting your account

Navigate to the Manage tab in Shipwell and select Integrations to open the Integration Marketplace.
Locate the Breakthrough Fuel card.
Click the card to open the connection form.
Enter your Client ID (required) and Client Secret (required; masked as you type).
Click Connect. Shipwell validates your credentials with Breakthrough Fuel.
On success, the card displays a green checkmark and "Connected" status.

NOTE: If connection fails, verify your Client ID and Client Secret with your Breakthrough Fuel account team.

NOTE: The Client Secret field appears empty each time you return to this screen. This is expected — Shipwell does not display your stored secret for security.

Configuring an FSC table to use Breakthrough Fuel

Once connected, designate one or more FSC tables to use BTF as the data source. Only tables explicitly configured for Breakthrough Fuel will trigger BTF calculations.

Navigate to Manage → Company → Lane Management → Fuel Surcharge.
In the FSC Settings window, locate the Fuel Source dropdown.
Select Breakthrough Fuel.
When Breakthrough Fuel is selected, these fields are not required: Base Fuel Price, Rate Update Frequency, and Day Rates are Updated.
Complete any remaining required fields and save. The table displays an indicator confirming it uses Breakthrough Fuel.

NOTE: You must connect your Breakthrough Fuel account before configuring an FSC table to use BTF.

Viewing your fuel surcharge on a shipment

Open the Shipment Detail page for the shipment.
After the shipment moves to In Transit, allow about 30–60 seconds for the calculation to process.
Open the Financials section. The BTF-calculated fuel surcharge appears as a line item with charge code 405 (Fuel Surcharge).

How a Breakthrough Fuel calculation is triggered — requirements & troubleshooting

When the fuel calculation runs

The Breakthrough fuel surcharge is calculated once, at pickup — specifically when your shipment's first stop is confirmed as departed (picked up). That pickup confirmation can be recorded through any supported method — a manual status update, a carrier tracking/telematics integration, an API update, or an EDI status message. The trigger is the pickup confirmation itself, not any one channel.

Because Breakthrough prices fuel against the actual pickup date, the calculation is intentionally not run at booking (the real pickup date isn't known yet) and not re-run at delivery.

Requirements for the calculation to occur

All of the following must be true for a Breakthrough fuel surcharge to be calculated and applied:

Breakthrough Fuel is connected for your account (Manage → Integrations, "Connected" status).
The shipment is booked under a contract — not left as an uncontracted spot load.
That contract uses an FSC table configured for Breakthrough Fuel. Applying such a contract adds an empty fuel-surcharge (charge code 405) placeholder for Breakthrough to fill.
The pickup is confirmed — the first stop is recorded as departed.

If any one of these is missing — no active connection, no contract, a contract whose FSC table isn't set to Breakthrough, or a pickup that's never confirmed — the calculation will not run and the fuel surcharge will not populate.

Troubleshooting — my fuel surcharge didn't populate

What you see	Likely reason	What to do
No fuel surcharge (405) line at all	The shipment isn't under a contract with a Breakthrough FSC table (for example, a spot load)	Confirm the shipment is covered by the correct contract, and that the contract's FSC table is set to Breakthrough Fuel
Empty 405 line after delivery	The pickup was never confirmed, or the pickup status update arrived incomplete or out of sequence, so the calculation never triggered	Confirm the pickup on the shipment. Because pricing runs only at pickup, the surcharge may need to be added manually for that load — notify your Customer Success Manager
Line still blank shortly after pickup	The calculation is still processing (it runs in the background)	Wait 30–60 seconds and refresh the Financials section

NOTE: Breakthrough prices fuel using the actual pickup date, so a timely, accurate pickup confirmation is important. If a pickup event is missed or incomplete, the surcharge will not back-fill automatically from a later delivery event — contact your Customer Success Manager if a calculation appears to have been missed.

FAQ

Do I need a Breakthrough Fuel account to use this integration?
Yes — you must have an active Breakthrough Fuel account with a Client ID and Client Secret before connecting. Contact Breakthrough Fuel directly to establish an account.
How do I connect my Breakthrough Fuel account to Shipwell?
Navigate to Manage → Integrations and click the Breakthrough Fuel card. Enter your Client ID and Client Secret and click Connect. No additional enablement is required.
What if my connection attempt fails?
Verify your Client ID and Client Secret with your Breakthrough Fuel account team. If the issue persists, contact your Shipwell Customer Success Manager.
Does connecting Breakthrough Fuel apply to all of my shipments?
No — BTF calculations apply only to shipments whose contract uses an FSC table configured for Breakthrough Fuel. You may have multiple FSC tables, some using BTF and others using Shipwell's standard fuel data.
When is the fuel surcharge calculated?
Automatically when the shipment is picked up (moves to In Transit). No user action is required.
Will the fuel surcharge be included when I tender a shipment via contract?
Yes — when a shipment is created through a contract that uses a BTF-configured FSC table, the BTF-calculated fuel surcharge is applied as part of the tender amount.
I don't see the fuel surcharge on my shipment right after pickup — what should I do?
BTF calculations process in the background. Wait 30–60 seconds after pickup, then refresh the Financials section. If it's still not showing, contact your Customer Success Manager
Can I disconnect Breakthrough Fuel from my Shipwell account?
Yes — navigate to Manage → Integrations, click the Breakthrough Fuel card, and click Disconnect. Any FSC tables configured for BTF should be reviewed and updated after disconnecting to avoid calculation errors on future shipments.
Is my Client Secret stored securely?
Yes — credentials are encrypted at rest and in transit. Your Client Secret is never displayed after initial entry and is never included in logs or error messages.
Can I use Breakthrough Fuel for some shipments but not others?
Yes — BTF is configured at the FSC table level. You can designate only specific tables to use Breakthrough Fuel; shipments using non-BTF FSC tables continue to use Shipwell's standard fuel surcharge calculation.