> ## Documentation Index > Fetch the complete documentation index at: https://docs.alvys.com/llms.txt > Use this file to discover all available pages before exploring further. # Fuel Surcharge Contracts > Set up per-customer fuel surcharge contracts with flat, distance, or percentage matrices, link them to lane rates, and let Alvys apply the surcharge automatically. ## Overview When you dispatch a load, the cost of fuel fluctuates. Fuel Surcharge Contracts allow you to define rules for how fuel surcharges are calculated and applied to loads, so you don't have to manually adjust rates every time fuel prices change. Fuel surcharge contracts are set up **per customer** and can be linked to lane rate contracts. When a load matches a lane with a fuel surcharge contract, the surcharge is automatically calculated based on the current week's fuel prices. **Navigation:** Companies > Select a Customer > Lane Rates tab > Fuel Surcharge Contracts *** ## Fuel Surcharge Types Alvys supports three types of fuel surcharge calculations: | **Type** | **How It Works** | **Best For** | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **Fixed** | A flat dollar amount per load OR a rate per mile. Does not change with fuel prices. | Simple contracts where the surcharge is a set amount regardless of fuel cost. | | **Distance** | A matrix of fuel price ranges mapped to dollar-per-mile rates. The system looks up the current fuel price, finds the matching tier, and multiplies the rate by the load's billing miles. | Contracts where the surcharge varies by fuel price and is calculated per mile. | | **Percentage** | A matrix of fuel price ranges mapped to percentage rates. The system looks up the current fuel price, finds the matching tier, and applies the percentage to the load's linehaul rate. | Contracts where the surcharge is a percentage of the linehaul, varying by fuel price. | *** ## Creating a Fuel Surcharge Contract ## Step 1: Navigate to Fuel Surcharge Contracts 1. Go to **Companies** > **Customers** in the left sidebar 2. Select the **Customer** you want to set up the contract for to open **Customer Profile** 3. Click **Contracted Lanes & Fuel Surcharges** button in top right corner of the page. 4. Click the **Fuel Surcharge Contracts** tab 5. Click **Add New Contract** ## Step 2: Configure Contract Details Fill in the following fields on the **Details** tab: | **Field** | **Description** | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Contract Name** | A descriptive name for this contract (e.g., "Customer ABC - FSC 2026"). | | **Type** | Select **Fixed**, **Distance**, or **Percentage** (see above). | | **Sub-Type** (Fixed only) | Choose **Flat** (one amount per load) or **Rate Per Mile** (amount multiplied by miles). | | **Amount** (Fixed only) | Enter the dollar amount for the surcharge. | | **Load Date** | Which date on the load determines the fuel price lookup: **Scheduled Pickup**, **Actual Pickup**, **Scheduled Delivery**, or **Actual Delivery**. | | **Date Offset** | Which week's EIA fuel prices to use: **Current Week**, **Previous Week**, **Begin of Month**, or **Custom Range**. | | **Custom Day Offset** | If using Custom Range, enter a day adjustment from -9 to +9 days relative to the load date. | | **Region** | The geographic region for the EIA fuel price lookup (e.g., "U.S."). | | **Rounding** | How to round the calculated rate: Whole Penny, Tenth of a Penny, Hundredth of a Penny — Rounded or Truncated. | ## Step 3: Set Up the Matrix (Distance and Percentage Only) If you selected **Distance** or **Percentage** as the type, click the **Matrix** tab to define your fuel price tiers. Each row in the matrix represents a fuel price range and the corresponding surcharge rate: | **Column** | **Description** | **Example** | | --------------- | --------------------------------------------------------------------------------------------------- | ----------------- | | **Start Price** | The lower bound of the fuel price range (per gallon). | \$3.00 | | **End Price** | The upper bound of the fuel price range (per gallon). | \$3.49 | | **Rate** | For **Distance**: the dollar rate per mile. For **Percentage**: the decimal rate (e.g., 0.05 = 5%). | \$0.08/mi or 0.05 | **Tips for the matrix:** * Click **Add Row** to add tiers one at a time * Click **Import CSV** to bulk-import tiers from a spreadsheet (click **Download Template** first to get the correct format) * Tiers must not overlap — each fuel price should fall into exactly one range * Values support up to **4 decimal places** for precision * For Percentage type, enter rates as decimals (0.05 = 5%), not as whole percentages ## Step 4: Enable and Save 1. Click **Save** *** ## Linking a Fuel Surcharge Contract to a Lane Rate Once you've created a fuel surcharge contract, you need to link it to one or more lane rate contracts for it to take effect on loads. 1. Go to **Companies** > **Customers** in the left sidebar 2. Select the **Customer** you want to set up the contract for to open **Customer Profile** 3. Click **Contracted Lanes & Fuel Surcharges** button in top right corner of the page. 4. Open or **Create** **Contract** 5. In the contract details, select the **Fuel Surcharge Contract** from the dropdown 6. Save the lane rate contract When a load matches this lane, the fuel surcharge will be automatically calculated and applied. *** ## How the Calculation Works When a load is created or updated with a lane rate contract that has a fuel surcharge: 1. The system determines the **load date** (based on the contract's Load Date setting) 2. It applies the **date offset** to determine which week's fuel prices to use 3. It looks up the **EIA weekly fuel price** for the configured region 4. Based on the contract type: * **Fixed (Flat):** Surcharge = the configured amount * **Fixed (Per Mile):** Surcharge = amount x billing miles * **Distance:** Finds the matrix tier matching the fuel price, then: Surcharge = tier rate x billing miles * **Percentage:** Finds the matrix tier matching the fuel price, then: Surcharge = tier rate x linehaul rate 5. The result is **rounded** per the contract's rounding setting 6. The surcharge appears as a separate line item on the load ⚠️ **Note:** If the load's dates are in the future and fuel prices aren't available yet, the system will flag the surcharge for recalculation once actual dates and prices are available. *** ## Example: Setting Up a Distance-Based Fuel Surcharge Let's say your customer contract states: "Fuel surcharge is $0.02 per mile for every $0.05 increase in fuel price above \$3.00/gallon." Here's how you'd set it up: 1. Create a new Fuel Surcharge Contract 2. Set **Type** to **Distance** 3. Set **Load Date** to **Scheduled Pickup** 4. Set **Date Offset** to **Previous Week** (most common) 5. Set **Region** to **U.S.** 6. On the **Matrix** tab, add rows: | **Start Price** | **End Price** | **Rate (\$/mile)** | | --------------- | ------------- | ------------------ | | \$3.00 | \$3.049 | \$0.02 | | \$3.05 | \$3.099 | \$0.04 | | \$3.10 | \$3.149 | \$0.06 | | \$3.15 | \$3.199 | \$0.08 | If the EIA fuel price for the load's week is $3.12/gallon and the load is 500 miles, the surcharge would be: **$0.06 x 500 = \$30.00\*\* *** ## Example: Setting Up a Percentage-Based Fuel Surcharge If your customer contract states: "Fuel surcharge is a percentage of the linehaul rate based on current fuel prices." 1. Create a new Fuel Surcharge Contract 2. Set **Type** to **Percentage** 3. Configure Load Date, Date Offset, Region, and Rounding as needed 4. On the **Matrix** tab, add rows: | **Start Price** | **End Price** | **Rate (decimal)** | | --------------- | ------------- | ------------------ | | \$3.00 | \$3.49 | 0.05 | | \$3.50 | \$3.99 | 0.08 | | \$4.00 | \$4.49 | 0.11 | 💡 **Percentage rates are entered as decimals:** 0.05 = 5%, 0.08 = 8%, 0.1234 = 12.34%. Do not enter "5" for 5%. If the fuel price is $3.75 and the linehaul is $2,000, the surcharge would be: **0.08 x $2,000 = $160.00** *** ## Frequently Asked Questions * **Where does Alvys get the fuel prices?** Alvys uses the **U.S. Energy Information Administration (EIA)** weekly retail diesel fuel prices, published every Monday. The prices are region-specific and updated automatically. * **Can I have multiple fuel surcharge contracts for the same customer?** Yes. You can create multiple contracts and assign different ones to different lane rate contracts for the same customer. * **What happens if the fuel price falls outside my matrix tiers?** If the current fuel price doesn't match any tier in the matrix, no surcharge will be applied. Make sure your tiers cover the expected range of fuel prices. * **Can I import my matrix from a spreadsheet?** Yes. On the Matrix tab, click **Download Template** to get a CSV template, fill in your tiers, then click **Import CSV** to upload it. * **How precise can the matrix values be?** All matrix values support up to **4 decimal places**. This applies to Start Price, End Price, and Amount. * **What is the Date Offset for?** Fuel prices are published weekly. The Date Offset lets you control which week's prices to use relative to the load date. Most customers use **Previous Week** since the current week's prices may not be published yet at the time of dispatch.