Skip to main content
PUT
Update fuel surcharge on loads
The Update Fuel Surcharge on Loads endpoint sets a flat customer fuel surcharge on up to 25 loads in one request. Use it when another system, such as a fuel surcharge provider, calculates the surcharge for each load. For more information on how versioning works and how to include it in your requests, please refer to the Versioning page.
This endpoint requires the load:update scope. A load that is Released, Queued, Invoiced, Financed or Completed also requires the invoice:update scope. See Authentication.

What the update does

Each load’s fuel surcharge becomes a manual flat amount, and the load’s customer rate is recalculated, as when the fuel surcharge is edited in Alvys. The amount replaces the current fuel surcharge; it is not added to it.
  • A fuel surcharge contract stops applying. If the load’s fuel surcharge came from a contract, the load no longer uses that contract.
  • Paid trips keep their amounts. On a trip whose driver, owner-operator or carrier is already paid, the trip value, carrier rate, owner-operator rate and trip fuel surcharge are not recalculated.
  • Paid percentage pay blocks the change. An Invoiced, Financed or Completed load is refused when a trip’s driver or owner-operator is paid by percentage and has already been paid, as in Alvys.
  • EDI tender updates keep your amount. After you set a load’s fuel surcharge here, a later EDI tender update that carries a fuel surcharge does not change it. The tender’s line haul and the rest of the tender update still apply.
  • Amount = 0 sets a $0 surcharge. The fuel surcharge stays on the load with a zero amount.

Identify loads by load number

Send the Alvys load number. A trip number is not accepted. To start from your order numbers, look the loads up first with Search loads, using OrderNumbers and CustomerId. An order number can match more than one load.

Request parameters

The following parameter is available in the URL path:

Request body

Each item in Items: If any item is incomplete or out of range, the whole request is rejected with 400 and no load is changed. The 400 response names each failing item, for example Items[2].Amount.

Example cURL request

Replace YOUR_ACCESS_TOKEN with your actual Bearer token.

Response fields

A valid request answers 200 with one result per item in Results. Each item is applied on its own, so one failed item does not stop the others. Item Status values:

Resending is safe

Sending an item again applies it again, so you can resend any item, or the whole request. Resend the items that came back with 409, 500, or a Warning.

Example response


Status codes

Authorizations

Authorization
string
header
required

OAuth 2.0 client-credentials access token. Obtain one from https://auth.alvys.com/oauth/token (grant_type=client_credentials, audience=https://api.alvys.com/public/), then paste it here. The playground sends it as Authorization: Bearer <token>.

Path Parameters

version
string
default:2.0
required

API version (e.g., 2.0)

Example:

"2.0"

Body

Items
object[] | null

Response

OK

Results
object[]
required