Breakthrough Fuel Integration
What is the Breakthrough Fuel Integration Feature?
Shipwell is excited to announce the integration of Breakthrough Fuel (BTF) into the Shipwell platform. Breakthrough Fuel is a US Venture company that provides technology-driven fuel management capabilities, enabling shippers to obtain highly accurate, real-time fuel surcharge (FSC) calculations directly from BTF's platform.
With this integration, Shipwell customers who use Breakthrough Fuel for fuel management 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. The result is more accurate billing, improved transparency, and a streamlined fuel surcharge workflow, all from within your Shipwell account.
How does the Breakthrough Fuel Integration feature work?
Shipwell provides a seamless self-service connection through the Integration Marketplace, allowing users to link their existing Breakthrough Fuel account using their BTF Client ID and Client Secret. Once connected, customers can configure their Fuel Surcharge (FSC) tables to use Breakthrough Fuel as the data source. When a qualifying shipment reaches "In Transit" status, Shipwell automatically calls the BTF API with the shipment's details and applies the returned fuel surcharge as a financial line item — no action required from the user.
To use the Breakthrough Fuel Integration, you must have an active Breakthrough Fuel account. Contact Breakthrough Fuel directly to establish an account and obtain your credentials before beginning setup.
Key Breakthrough Fuel Integration functionality
Connect your Breakthrough Fuel account to your Shipwell account via the Integration Marketplace.
Designate an FSC table to use Breakthrough Fuel as the data source.
Automatically receive real-time fuel surcharge calculations from BTF when a shipment is picked up.
View the BTF-calculated fuel surcharge as a financial line item on your shipment.
BTF fuel surcharge amounts are applied automatically in contract tendering workflows.
Benefits to using the Breakthrough Fuel Integration
Key benefits of integrating your Breakthrough Fuel account into Shipwell include:
Real-time, accurate fuel surcharge calculations powered by Breakthrough Fuel's data
Elimination of manual FSC entry and external reconciliation
Centralized fuel cost management within the Shipwell platform
Consistent FSC application across shipments and contract tenders
Full audit trail of BTF-calculated surcharges stored on each shipment
Flexibility to use BTF for select FSC tables while maintaining standard tables for others
Setting up the Breakthrough Fuel Integration — Initial Connection
Before connecting, ensure you have your Breakthrough Fuel Client ID and Client Secret available. If you do not have a Breakthrough Fuel account, contact Breakthrough Fuel directly to establish one.
Once you have your credentials, follow these steps to connect your account:
Navigate to the Manage tab in Shipwell and select Integrations. This will take you to the Integration Marketplace.
Locate the Breakthrough Fuel card.
Click the card to open the connection form. You will see the helper text: "To enable the Breakthrough Fuel integration, you will need to input your Client ID and secret."
Enter your Client ID (required) and Client Secret (required). The Client Secret field will be masked as you type.
Click Connect. Shipwell will validate your credentials with Breakthrough Fuel.
On successful connection, the Breakthrough Fuel card will display a green checkmark and "Connected" status.
NOTE: If connection fails, verify that your Client ID and Client Secret are correct. Contact your Breakthrough Fuel account team if you need assistance with your credentials.
NOTE: The Client Secret field will appear empty each time you return to this screen. This is expected — Shipwell does not display your stored secret for security purposes.
Using the Breakthrough Fuel Integration — Configuring an FSC Table
Once your Breakthrough Fuel account is connected, you can designate one or more Fuel Surcharge (FSC) tables to use BTF as the data source. You may maintain multiple FSC tables; only tables explicitly configured for Breakthrough Fuel will trigger BTF calculations.
Navigate to your FSC Table settings Manage, Company, Lane Management, Fuel Surcharge.
In the FSC Settings window, locate the Fuel Source dropdown.
From the dropdown, select Breakthrough Fuel .
When Breakthrough Fuel is selected, the following fields are not required: Base Fuel Price, Rate Update Frequency, and Day Rates are Updated.
Complete any remaining required fields and save. The FSC table will display an indicator confirming it is configured to use Breakthrough Fuel.
NOTE: You must have your Breakthrough Fuel account connected before configuring an FSC table to use BTF.
Using the Breakthrough Fuel Integration — Viewing Your Fuel Surcharge on a Shipment
Once a BTF-configured FSC table is applied to a shipment via contract, Shipwell will automatically retrieve and apply the fuel surcharge when the shipment is picked up. No manual action is required.
Navigate to the Shipment Detail page for the shipment you want to review.
After the shipment moves to In Transit status, allow approximately 30–60 seconds for the BTF calculation to process.
Navigate to the Financials section of the shipment. You will see the BTF-calculated fuel surcharge applied as a line item with charge code 405 (Fuel Surcharge).
NOTE: The BTF fuel surcharge is calculated at pickup only. If you do not see the line item immediately after the shipment moves to In Transit, allow a brief moment for processing to complete before refreshing.
NOTE: If a BTF calculation cannot be completed due to a connectivity issue, shipment processing will continue as normal. Contact your Customer Success Manager if you believe a calculation was missed.
Swifty AI Agent Chat
Swifty now includes a built-in AI agent that can answer questions and look up live data from across your Shipwell account — no special commands needed. Just ask.
What it can help with
Shipments — Find and summarize shipments, check status, pull tracking info and ETAs, surface notes, messages, and documents like BOLs and PODs.
Carriers & contracts — Check carrier relationships and assignments, view contract rates and lanes.
Orders — Search purchase orders, check order status and line items.
Invoices — Look up freight invoices and see where they are in the approval process.
Tenders — Check whether a tender is pending, accepted, or rejected.
Routing guides & appointments — Look up routing guide policies and check facility dock appointments and hours.
Address book — Search saved locations and address book entries.
Platform how-to — Get step-by-step guidance on any Shipwell feature, pulling directly from the Shipwell Help Center.
UI workflows & feature explanations — Ask how any part of the platform works and get plain-language, step-by-step walkthroughs grounded in the actual Shipwell codebase.
Data & reporting — Request custom reports pulling from Shipwell’s data warehouse — shipment volumes, carrier performance, invoice summaries, and more.
Codebase intelligence — For technical users and support teams, the agent has full knowledge of the Shipwell codebase and can explain system behavior, feature boundaries, and how things work under the hood.
Swifty is read-only — it looks things up and explains them, but never creates, updates, or deletes anything.
Developer Tools
The Shipwell MCP Server is a production-deployed Model Context Protocol (MCP) server that gives AI assistants such as Claude, Cursor, OpenAI, OpenClaw, Claude Code, and any MCP-compatible agent - direct, safe access to Shipwell data without custom API development.
It exposes 90+ tools across all major Shipwell domains, enabling AI agents to:
Query shipment data
Trigger logistics actions
Orchestrate multi-step workflows natively
Live endpoints:
Environment | MCP Endpoint | Shipwell API |
Sandbox | ||
Production |
Getting Started - Quickstart Guide
Prerequisites:
A Shipwell API token (obtained via Shipwell Settings → API Management)
Node.js 18+ (for Claude Desktop / Cursor setups using mcp-remote)
Setup Steps (Claude Desktop / Cursor):
Obtain your Shipwell API token from Settings → API Management
Add the MCP server config block to your Claude Desktop or Cursor config
Point to
<https://mcp.shipwell.com/mcp> (or production or sandbox endpoint)Agent auto-discovers all 90+ tools via MCP tool-discovery - no API docs required
Tool Reference — Domains & Tools
90+ tools across all major Shipwell domains:
Domain | Key Tools | Access / Permissions |
Shipments | list, get, create, update, search dashboard, bulk action, CSV download | Read + Write |
Stops | list, get, update | Read + Write |
Carrier Assignments | get, create, update, remove | Read + Write |
Orders (Corrogo + Legacy) | list, get, create, update | Read + Write |
Carriers & Contracts | list carriers, list contracts, get lanes, calculate charges | Read |
Tenders | list, get | Read |
Tracking & Documents | get tracking, list/get documents | Read |
Notes & Messages | list/create notes, list messages | Read + Write |
Invoices | list | Read |
Facilities & Dock Scheduling | full CRUD, availability, appointments, docks, load types | Read + Write |
Routing Guides | list, get, create, update, delete, initiate, trigger workflow | Read + Write |
Custom Fields | list, get, create, update, delete | Read + Write |
Address Book / Companies / Users | list/get address book, companies, users, tags | Read |
Help Center | search articles, get full article text (Intercom KB) | Read |
Rating (Genesis) | create rating request, poll status, fetch rates | Read |
Meta / Safety | get_server_mode, state machine, check_operation_allowed | Read |
Safety & Write Access
Read-only by default
The hosted server ships with all write tools disabled. This is intentional - no accidental mutations on production freight data.
Write access
Available on request through your Shipwell account team. Write access is a paid tier (read-only access is free with your Shipwell API token).
Dry-run mode
Before enabling live writes, use dry-run mode to simulate any write operation:
SHIPWELL_MCP_DRYRUN=true
The agent runs in simulation mode and returns a structured risk report with:
Identified side effects
State preconditions
Risk level:
low/medium/high/critical
Agent-safe design
Every write tool explicitly documents:
Its side effects
Required state preconditions
Risk level
State machine reference
Built-in tools and a machine-readable JSON resource describe valid transitions, locked fields, and side effects for every shipment, stop, and order status.
Best Practice in Setup
Go to docs.shipwell.com for detailed setup instructions and best practices
Swifty Update Slack Setup Integration
Setting up Swifty with your Slack channel is now self-service
Customers with access to AI Studio can now integrate Swifty with their own Slack channel directly from the AI Studio > Swifty Configuration > Channel Integration page.
Required Slack Permissions
During setup, you'll be asked to grant the following permissions to the Swifty app:
Information Swifty can view:
Content and info about you (to identify who is making requests)
Content and info about channels & conversations (to read messages where Swifty is mentioned)
Actions Swifty can take:
Perform actions as you (to authenticate requests against your Shipwell permissions)
Perform actions in channels & conversations (to post shipment and order details in response to mentions)
Swifty also requires a designated channel to post as an app via webhook.
Required Shipwell Permissions
The user setting up the integration must have:
Shipwell AI Studio access (to configure the integration)
Slack workspace admin or app installation permissions (to add apps to your workspace)
For Swifty to respond with Shipment or Order information, the requesting Slack user must:
Have appropriate permissions in Shipwell to view the requested shipment or order data
If a user lacks permissions for a specific shipment or order, Swifty will not display sensitive information.
Two Ways to Set Up
Option 1: From the Shipwell Platform
Navigate to AI Studio > Swifty Configuration > Channel Integration
Click Connect on the Slack card
Sign in to your Slack workspace
Select the channel where you want Swifty to post during the Slack authorization screen
Review and approve the permissions
You'll be automatically redirected back to Shipwell with the integration connected
Option 2: From the Slack App Marketplace
Find "Swifty" in the Slack App Directory and click Add to Slack
Sign in to your Slack workspace (if not already signed in)
Select the channel where you want Swifty to post during the Slack authorization screen
Review and approve the permissions
After installation, you'll see a "Swifty Installed" confirmation page
Open your Slack workspace and navigate to the channel you selected
Swifty will send a welcome message with a "Connect Shipwell Account" button
Click the "Connect Shipwell Account" button to be directed to the Shipwell AI Studio > Swifty Configuration page
Sign in to Shipwell (if not already signed in) to link the integration to your company
A confirmation message will appear in your Slack channel once linking is complete
Key Differences Between the Two Flows:
Shipwell Platform flow: Integration is immediately connected to your Shipwell company (you're already authenticated)
Slack Marketplace flow: Creates a "pending" integration that must be linked to your Shipwell company by clicking the button in the welcome message
What Swifty Can Do in Slack
Once integrated, Swifty enables your team to:
Request real-time status updates for Shipments by mentioning @Swifty followed by a shipment ID
Request status updates for Orders by mentioning @Swifty followed by an order ID
View key details including current status, next stop, planned/ETA times, origin, destination, and more
Access quick links to full Shipment Details and Tracking Info in the Shipwell platform
Shipment Update Example
Order Update Example
Known Limitations:
The Swfity Slack App Integration page is currently behind the AI Studio feature flag. This will be moved to the Company Level Integrations Marketplace page in the future.
Track and Trace Worker Enhancements
This release improves shipment tracking accuracy and flexibility by enhancing how delivery stops are processed and validated before marking shipments as delivered.
Improvements
Enhanced Delivery Stop Processing
Out-of-Order Stop Updates
The Track and Trace agent now supports updating delivery stops in any order, providing greater flexibility when processing carrier status updates that arrive non-sequentially.
Delivery Validation and Stop Completion
Before marking a shipment as delivered based on carrier responses, the system now validates that all stops have been updated with status information. If any stops are missing updates, the system will:
Request the missing stop information
Update incomplete stops with the required data
Only then mark the shipment as delivered
This ensures complete and accurate shipment tracking data before finalizing delivery status.
Text/SMS
Customer Impact:
More reliable delivery status tracking
Reduced instances of incomplete shipment records
Better data quality for reporting and customer visibility
Improved handling of carrier updates received in non-standard sequence
Load Optimization Enhancements
Improved error messaging for the Orders Dashboard, Optimized Orders Bulk Actions flow. Users now receive detailed, actionable error messages when order optimization fails, replacing the previous generic "Unknown error occurred" message.
What's New
Shipment ID Visibility in Load Optimization
Shipment IDs are now displayed immediately when you create shipments from the Load Optimization flow
See Shipment IDs in three key locations:
Success notification banner after shipment creation
Load # row in the Load Plan table
Title bar on the Load Plan Details page
Shipment IDs are clickable and copyable for quick access and sharing
Streamlined Workflow
No more manual searching for shipments you just created
Quickly verify optimization results by accessing the shipment directly
Share Shipment IDs with carriers or team members without leaving the page
Improved visibility across the Load Plan table and details views
Improvements
Before: The success message only showed "Successfully built 1 shipment"
After: Success message now includes the actual Shipment ID along with the Load Number, so you can immediately navigate to or share the shipment
---------------------------------------------------------------------------------------
Enhanced Error Messages for Load Optimization
When optimizing orders fails, you'll now see specific details about which orders have issues and exactly what needs to be fixed
Error messages now include:
Order identifiers for affected orders
Specific validation failures (e.g., missing package counts, invalid weights, date issues)
Current vs. expected values to help you quickly identify the problem
No more need to check browser developer tools to understand what went wrong
Improvements
Before: Generic error message "Load Plan Creation Failed - An unknown error occurred."
After: Detailed error breakdown
Better User Experience
Error notifications now display multiple errors in an easy-to-read format
Longer notification timeout for multi-line errors, so you have time to read all details
Errors remain actionable - you can quickly identify and fix data issues without technical support
API Changes
Added btf_shipper_id and btf_division_id to Breakthrough Fuel Config
We added two new required fields to the Breakthrough Fuel (BTF) integration configuration endpoint.
What’s new
btf_shipper_id — The customer’s BTF shipper identifier, used in the BTF API URL path and payload
shipperIdfield. Max 64 characters.btf_division_id — The customer’s BTF division ID, used in the payload
divisionIdfield. Often the same value asbtf_shipper_id. Max 64 characters.Both fields are returned in the response upon successful creation.
Affected endpoints
POST /integrations/breakthrough/config/
Analytics Model Updates
Table: fact_logistics_provider_variance
Financial charge line items for shipments from the logistics provider's perspective or point of view. This table is used for comparing against approved logistics provider amounts in fact_shipment_financials to identify cost variances.
Field Name | Field Description |
fact_logistics_provider_variance_key | Primary key |
dim_shipment_detail_key | Foreign key to the dim_shipment_detail table for joining with fact_shipment_financials |
reference_id | Shipment's 6-digit unique identifier |
charge_lineitem_id | ID of the charge line item |
category_name | Charge line item category name |
charge_code | Charge line item code |
charge_description | Charge line item description (unit_name) |
currency_code | Currency code for the charge amount |
custom_data | JSON object containing optional client manual entry data |
carrier_assessed_amount | Total amount assessed by the carrier/logistics provider (unit_amount * unit_quantity). Compare with provider_amount_total from fact_shipment_financials to identify variances. |
customer_id | ID of the customer company in the vendor assignment |
vendor_id | ID of the vendor/carrier company in the vendor assignment |
customer_name | Name of the customer company |
vendor_name | Name of the vendor/carrier company |
shipment_id | ID of the shipment |
charge_updated_at | Timestamp when the charge was last updated |
_loaded_datetime | Timestamp when the record was loaded into the table |
Table: dim_shipment_detail
This table contains details of the shipment.
Field Name | Field Description |
service_level | Shipment's service level. Indicates the delivery speed or service tier. |
Table: fact_stop
Each row represents a stop on a shipment.
Field Name | Field Description |
appointment_window_start_timestamp | The scheduled appointment window start timestamp for this stop |
appointment_window_end_timestamp | The scheduled appointment window end timestamp for this stop |
Description |
Fuel Surcharge Not Updating Automatically – Needs Review |
Incorrect billing section on LTLs tendered to CTX |
LTL delivery date overwritten by P44 tracking events despite LD flag titan.dev-do-not-update-del-date-on-ltl-dispatch |
Routing Guide Failed to Auto-Trigger on 104→206 FTL/REEFER Shipments |
[BE] always sync all contract lane active in active states with root RFP when the sync endpoint is hit. |
Investigate incorrect Bill To assignment and shipment status mapping for CloudTrucks dispatches |
Extend document request polling period for CloudTrucks shipments |
Estes Direct Integration: Origin and Destination showing same location in carrier system |
Fall back postal code lookup when geocoding does not return postal code |
ABF (Direct Connection) tracking not working |
CHR integration not transmitting all accessorials |
Pre PRO and automated tracking not working for R+L direct connection |
ESTES & AVE direct not working |
Tracking Failure: Milestone "Delivered" not triggering for FedEx/CHR |
Direct rates for R&L & ESTES failing for PR loads |
ESTES - sending package weight and not total weight on rate requests |
Fix incorrect service level mapping for Estes |
Estes- Indicate Guaranteed on pickup request |
Estes - Request ALL service levels when getting rates |
XPO - Limited Access Pickup and Delivery |
Bulk tender function failing for multiple shipments |
Invalid message stating incorrect stop # |
Shipments transitioning to Delivered too soon |
Rate History Not Displaying for Shipment Lanes |
Carrier Assignment Failure & Shipment Data Corruption |
Bulk action: change shipment status fails silently with no actionable error for Hanes |
Packaging type updates |
Mismatch Between 'Stops' Hover Dates/Times and Shipment Detail Stop Dates/Times |
SLA's not being applied correctly |
Pricing Intel: Lane history stopped working after 26.04 release |
Unexpected Delivery Date Changes |
Tive geofence events silently dropped for tendered shipments |
Locus geofence tracking events silently dropped for shipments stuck in "tendered" status |
Invoiced Expected Amount on the settlements dashboard was not refreshing when shipment charges changed and caused a false EXCEPTION status on an invoice. |
Settlements stopped recalculating totals when missing line items were added to a shipment to match an invoice. |
Planned Dates disappeared in the New Shipment Builder when viewing or editing a shipment. The planning-window fields are now hidden behind the frontend-planned-windows feature flag when off. |
Qty column was missing from shipment downloads. |
CSV Order Importer rejected blank Pickup Address Line 2 cells. |
NetSuite vendor bill creation failed due to a charge category format mismatch (LH vs LINE_HAUL). |
New NetSuite Transactions Mapping UI for invoice and bill fields. |
Backend support for NetSuite Transactions Mapping. |
Teams Swifty Channel access for HFS |
T&T multistop updates need to accommodate stops being delivered out of order |
Slack Bot deployment to the Slack Marketplace |
T&T If the carrier says a shipment is delivered, but stops are not updated, request an update for all missing stops |
When Creating Shipments from the Load Plan, now shows the Shipment ID of the shipment created |
Integrate Document Intelligence code into document-store service |
Order planning assistant is popping up when it shouldn't and causing user disruptions. |
Swifty Teams order number search is broken |