Flow Fuel Plans: optimize a truck fuel plan
optimize_fuel_planFlow Fuel Plans. Build an optimized diesel fuel plan for a truck route. Send the truck profile, current fuel, origin, and destination; ValveRide Flow routes the leg, discovers truck stops along it, prices them from its live retail diesel grid, applies your discount schedule on net price, and returns where to stop, how many gallons to buy, and the estimated savings (IFTA tax-aware). The response includes a tripId; to replan mid-trip, call again with that tripId, currentLocation set to the truck's live position, and the updated currentFuelGallons. A replan of the same trip costs far less than a new plan: on a monthly Flow Fuel Plans tier every 10 replans count as 1 plan, and from the trial credit a new plan draws $2.25 and a replan of the same trip $0.08. Monthly tiers: Starter $99/month for 200 plans, Growth $349/month for 1,000 plans, Partner $799/month for 3,000 plans. VENDOR RULE: if the user restricts fueling to a brand or network ("Love's only", "we can only fuel at Pilot or Flying J"), you MUST set vendorRule.allowedVendors to those brands. It is a hard rule: only those stations are considered and, if none works, the tool returns no_feasible_plan_under_vendor_rule instead of an off-brand stop. Put any discount the user mentions for that brand in discountSchedule with the same vendor in the SAME call (for example "10 cents off at Love's" = vendorRule.allowedVendors ["Loves"] plus discountSchedule [{vendor:"Loves", discountType:"CENTS_PER_GALLON", discountAmount:10}]). The response echoes vendorRule and appliedDiscounts so you can confirm both were enforced.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| truck | Yes | ||
| origin | Yes | Where the trip starts, as {lat,lng} or a place string like "Des Moines, IA" | |
| tripId | No | Optional: the tripId returned by this trip's first call. Pass it (with an updated currentLocation) to replan the SAME trip at the replan rate (10 replans count as 1 plan on a monthly tier); omit it for a new trip. Must match the trip's destination and be within 14 days. | |
| options | No | Optional planning knobs | |
| taxRates | No | Optional per-jurisdiction diesel tax overrides; defaults to current US/CA rates | |
| vendorRule | No | STRICT vendor allowlist. Set this whenever the user says they can only fuel at certain brands ("Love's only"). Only stations of these brands are considered; the plan never falls back to other brands. Aliases are accepted (Love's / Loves / Love, Pilot / Flying J / PFJ, TA / Petro). Infeasible under the rule returns the structured error no_feasible_plan_under_vendor_rule. | |
| destination | Yes | Destination as {lat,lng} or a place string like "Denver, CO" | |
| currentLocation | No | Optional: the truck's live position for a mid-trip replan. Defaults to origin; when set, the plan covers the remaining leg from here. | |
| discountSchedule | No | Your negotiated fuel discounts, applied on top of retail to optimize on net price | |
| currentFuelGallons | Yes | Fuel currently in the tank, in gallons |