Breakthrough Fuel

Prev Next

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.

  1. Navigate to TMS Admin.

  2. Select Credentials.

  3. Select the Global Services tab.

  4. Find Breakthrough in the list and open the card.

  5. Check the Enabled box.

  6. Enter the User ID and Password 1 into the text fields.

  7. 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

  • Provided via BTF post-authorization document is received

Example: revenova_customer_name

  • Provided via BTF post-authorization document is received

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.

  1. Click the Setup Gear icon in the top right corner.

  2. From the drop-down, click Setup.

  3. In the Quick Find Toolbar, type Remote Site Settings and click the link.

  4. From the list of remote sites, find Breakthrough and click the Edit link.

  5. Confirm the Remote Site URL matches the Service URL.

  6. 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.

  1. Click New Fuel Surcharge.

  2. Enter the FSC table name, like “Breakthrough Fuel.”

  3. From the Fuel Surcharge Source list, select Breakthrough Fuel.

  4. 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.

Note: It’s recommended to select Fuel.

Y

Match Priority

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.

Note: When creating a new Rate Entry, the Fuel Surcharge field only appears when Freight+Fuel or Fuel are selected as the Rate Type.

Y

Note: When the Fuel Surcharge field is Freight+Fuel, the field IS NOT required. When the Fuel Surcharge field is Fuel, the field IS required.

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

  • Quoted

  • Accepted

  • Rejected

  • Cancelled

The Rate Entry Status should be Accepted to apply the Breakthrough Fuel Surcharge on quotes and invoices.

Pending

Y

Currency ISO Code

The three letter currency identifier.

USD - U.S. Dollar

Note: For multi-currency orgs, the default value for the Currency ISO Code field reflects the default currency of the org.

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"
}