Breakthrough Fuel (BTF) based fuel surcharges are supported for stored rate Customer Quotes. Breakthrough Fuel provides the ability to capture daily fuel price changes to ensure fair market prices are paid on the Expected Ship Date of a Load using precise Lane information.
Breakthrough’s Load Lookup API provides partner organizations the ability to request fuel amounts for official Loads already in the FELIX system.
This API doesn’t insert new shipments or perform a fuel calculation; it simply returns the fuel amount already on the requested Load if provided by the shipper. It’s an alternative mechanism to SFTP, AS2, email, and on-screen lookups for obtaining fuel amounts for a Load.
Setup
Use the TMS Admin to create a Breakthrough Fuel Surcharge and configure the Breakthrough API to pull real-time fuel reports from FELIX.
Enter Credentials
Enable the Breakthrough Fuel integration.
Navigate to TMS Admin.
Select Credentials.
Select the Global Services tab.
Find Breakthrough in the list and open the card.
Check the Enabled box.
Enter the User ID and Password 1 into the text fields.
Click the Save button when finished.
Valid credentials are required from a Breakthrough Fuel subscription. See examples in the table below.
User ID | Password 1 | Password 2 | Customer Number |
|---|---|---|---|
Example: revenova_customer_name |
Example: oR1444487X5Tj$nyQuV |
Remote Site Settings
Upgrading from previous versions of the TMS may include outdated information. Check that the Remote Site Settings for the Breakthrough Fuel integration URL are updated.
Click the Setup Gear icon in the top right corner.
From the drop-down, click Setup.
In the Quick Find Toolbar, type Remote Site Settings and click the link.
From the list of remote sites, find Breakthrough and click the Edit link.
Confirm the Remote Site URL matches the Service URL.
When testing in a sandbox, confirm the Remote Site URL matches the Test Service URL.
Service URL:
https://api.askfelix.com/Test Service URL:
https://api.testfelix.com/Carrier Authorization Form
Complete the Carrier Authorization Form and send it to carriersupport@breakthroughfuel.com and ben.vandezande@breakthroughfuel.com.
The authorization form with written consent is required from the customer and the hauling shippers. The BTF team can begin setting up in our API and provide the credentials. The first set of credentials is set for the ‘testing’ phase. Once testing is complete, the BTF team will provision another production password that must be entered.
Create a Breakthrough Fuel Surcharge
Create a new Breakthrough Fuel Surcharge by navigating to the TMS Admin → Fuel Surcharges.
Click New Fuel Surcharge.
Enter the FSC table name, like “Breakthrough Fuel.”
From the Fuel Surcharge Source list, select Breakthrough Fuel.
Click Save.

Rate Entries
To include Breakthrough Fuel surcharges on Customer and Carrier Quotes and invoices, create a Rate Entry from the TMS Admin → Rate Entries. Use the following fields to build out rate entries:
Field Name | Field Description | Field Default Value | Required? |
|---|---|---|---|
Transportation Profile | Customer or Carrier Transportation Profile associated with the Rate Entry. | Y | |
Mode | The Load’s transportation method for the Rate Entry. | Y | |
Lane | The Load’s Stop location pair for the Rate Entry. | Y | |
Contract ID | An agreement or reference number from a Load to pair with the Rate Entry. | N | |
Category | The profile type, either Customer or Carrier, that the Rate Entry applies to. | Y | |
Lane Match Option | The Lane type for the Rate Entry, either Intrastate or Interstate. | N | |
Effective Date | The start date of the Rate Entry, if applicable. | N | |
Rate Type | The type of Rate Entry.
| Y | |
A numerical value determined by the Lane selected. | 999 | Y | |
Expiration Date | The end date of the Rate Entry, if applicable. | N | |
Fuel Surcharge* | The Fuel Surcharge or Fuel Surcharge table associated with the Rate Entry.
| Y
| |
Fleet Loads Only | Indicates if the Rate Entry applies to Fleet-specific Loads only. | N | |
Status | Determines what stage the Rate Entry is currently in to be applied with the following values to select:
| Pending | Y |
Currency ISO Code | The three letter currency identifier. | USD - U.S. Dollar
| Y |
Pricing Notes | Any specific notes related to the pricing model of the Rate Entry. | N |

Load
Set the Customer Load Id on Loads for specific customers.
The customer may send Load identifiers such as a PO Number or a Reference Number. This value corresponds to the {shipperLoadID} in the Breakthrough API URL.
The Customer Load Id field is the common identifier across all three parties for the Load: customer, shipper, and FELIX. The Customer Load ID field also passes through the FuelSurchargeUpdateJob to retrieve a fuel report from FELIX.
The Shipment Number is the Customer Load Id from the Load record.
A flow may need to be created to automatically insert the PO Number (or other Load identifier) from the Load field into the Customer Load Id field.
If the Customer Load Id field isn’t populated, an error message with 'null' is displayed at the end of the URL. For example, https://api.askfelix.com/fuel-report/ChicagoPizza/null.
Transportation Profile
Set the Breakthrough Fuel Shipper Id for each customer by navigating to the Customer Transportation Profile → Rates → Customer Product and Pricing Information.
Note: The Breakthrough Fuel integration only functions for Customer Transportation Profiles.
If the Shipper Id is invalid, an “Unauthorized” error message is displayed.
The Shipper Id corresponds to the {shipperId} in the Breakthrough Fuel API URL. The Shipper Id is set up in the FELIX Breakthrough Fuel system and entered on the Transportation Profile.
Warning
Do not allow spaces in the Breakthrough Fuel Shipper Id field. The following error message is displayed: "Your client has issued a malformed or illegal request." Example: https://api.askfelix.com/fuel-report/Chicago Pizza.
Breakthrough API Integration
Run the FuelIndexUpdateJob to retrieve retail diesel information from the EIA. The FuelSurchargeUpdateJob runs after the FuelIndexUpdateJob, triggering the FELIX system to create an updated retail diesel price report from current real-time Lane data.
Aside from running the FuelIndexUpdateJob and FuelSurchargeJob, users trigger the Breakthrough API request by also building and refreshing quotes with applied Rate Entries using the Pricing Workbench, Quote Wizard, or FQA.
TMS Operation | Breakthrough Endpoint | Request Type | Response |
|---|---|---|---|
FuelIndexUpdateJob | Receives a matched breakthrough fuel report in FELIX | GET | 200: SUCCESS - Match found 400: FAILURE - Unauthorized 400: FAILURE - Match not found |
Base URL for the Breakthrough Get Fuel Surcharge request:
https://api.askfelix.com/fuel-report/{shipperId}/{shipperLoadId}There is one (1) field stored within the TMS after triggering the Breakthrough Get Fuel Surcharge request:
TMS Object | TMS Field | Type | Breakthrough Field |
|---|---|---|---|
Customer Quote | Fuel Surcharge | Currency | fuel_price_currency |
See a sample GET response with a 200: SUCCESS below:
{
"resultCode": "SUCCESS",
"resultMessage": "Match found",
"scac": "FLST",
"reference_number": "BB00868703",
"carrier_reference_1": "",
"carrier_reference_2": "",
"carrier_reference_3": "",
"carrier_reference_4": "",
"carrier_reference_5": "",
"invoice_amount": 181.16,
"fuel_price_currency": "USD",
"movement_eligible_credit": 181.16,
"reefer_eligible_credit": 0.00
}See a sample GET response for a 400: FAILURE due to an unauthorized request:
{
"resultCode": "FAILURE",
"resultMessage": "unauthorized"
}See a sample GET response for a 400: FAILURE due to a match not found:
{
"resultCode": "FAILURE",
"resultMessage": "Match not found"
}