Loads
Update fuel surcharge on loads
Set a flat customer fuel surcharge on up to 25 Alvys loads in one request, with a separate result for each load so you can resend only what failed.
PUT
/
api
/
p
/
v
{version}
/
loads
/
fuel-surcharges
Update fuel surcharge on loads
curl --request PUT \
--url https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json-patch+json' \
--data '
{
"Items": [
{
"LoadNumber": "<string>",
"Amount": 123
}
]
}
'const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
body: JSON.stringify({Items: [{LoadNumber: '<string>', Amount: 123}]})
};
fetch('https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges"
payload = { "Items": [
{
"LoadNumber": "<string>",
"Amount": 123
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json-patch+json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'Items' => [
[
'LoadNumber' => '<string>',
'Amount' => 123
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json-patch+json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges"
payload := strings.NewReader("{\n \"Items\": [\n {\n \"LoadNumber\": \"<string>\",\n \"Amount\": 123\n }\n ]\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json-patch+json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json-patch+json")
.body("{\n \"Items\": [\n {\n \"LoadNumber\": \"<string>\",\n \"Amount\": 123\n }\n ]\n}")
.asString();{
"Results": [
{
"LoadNumber": "<string>",
"Status": 123,
"Changed": true,
"FuelSurchargeAmount": 123,
"Error": "<string>",
"Warning": "<string>"
}
]
}{
"Errors": {},
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}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.
Each item in
If any item is incomplete or out of range, the whole request is rejected with
Replace
Item
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 = 0sets 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, usingOrderNumbers and CustomerId. An order number can match more than one load.
Request parameters
The following parameter is available in the URL path:| Parameter | Type | Required | Description |
|---|---|---|---|
| version | String | Yes | The version of the API. This endpoint is 2.0. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| Items | Array | Yes | 1 to 25 items. Each load can appear only once. |
Items:
| Field | Type | Required | Description |
|---|---|---|---|
| LoadNumber | String | Yes | The Alvys load number. |
| Amount | Number | Yes | The flat fuel surcharge, from 0 to 1,000,000, with at most 2 decimal places. |
400 and no load is changed. The 400 response names each failing item, for example Items[2].Amount.
Example cURL request
curl --location --request PUT 'https://integrations.alvys.com/api/p/v2.0/loads/fuel-surcharges' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"Items": [
{ "LoadNumber": "100245", "Amount": 150.25 },
{ "LoadNumber": "100246", "Amount": 98.40 }
]
}'
YOUR_ACCESS_TOKEN with your actual Bearer token.
Response fields
A valid request answers200 with one result per item in Results. Each item is applied on its own, so one failed item does not stop the others.
| Field | Type | Description |
|---|---|---|
| LoadNumber | String | The load number as sent, trimmed. |
| Status | Integer | The outcome for this item. See the table below. |
| Changed | Boolean | false when the load already had this amount. |
| FuelSurchargeAmount | Number | The load’s fuel surcharge after the call, when Status is 200. |
| Error | String | Why the item was not applied, when Status is not 200. |
| Warning | String | Set on a 200 when the amount was saved but a follow-up step, such as the accounting sync, failed. |
Status values:
| Status | Meaning |
|---|---|
| 200 | Applied. Changed is false when the load already had that amount. |
| 403 | The load is Released, Queued, Invoiced, Financed or Completed, and your credential does not have the invoice:update scope. |
| 404 | No load with this load number that your credential can access. A trip number also returns 404. |
| 409 | The load changed while it was being updated. Read it again if you need to, then resend the item. |
| 422 | Alvys rejected the change. Error says why. |
| 500 | The update failed. Error says when a retry can help. |
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 with409, 500, or a Warning.
Example response
{
"Results": [
{
"LoadNumber": "100245",
"Status": 200,
"Changed": true,
"FuelSurchargeAmount": 150.25,
"Error": null,
"Warning": null
},
{
"LoadNumber": "100246",
"Status": 404,
"Changed": false,
"FuelSurchargeAmount": null,
"Error": "Load not found.",
"Warning": null
}
]
}
Status codes
| Code | Description |
|---|---|
| 200 | The request was processed. Read each item’s Status in Results. |
| 400 | The request body failed validation, for example more than 25 items, a duplicated load, or a missing amount. |
| 401 | Authentication failed or the token is missing. |
| 403 | The token is not authorized to update loads. |
| 429 | Too many requests. |
Authorizations
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>.
Body
application/json-patch+jsonapplication/jsontext/jsonapplication/*+json
⌘I
Update fuel surcharge on loads
curl --request PUT \
--url https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json-patch+json' \
--data '
{
"Items": [
{
"LoadNumber": "<string>",
"Amount": 123
}
]
}
'const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
body: JSON.stringify({Items: [{LoadNumber: '<string>', Amount: 123}]})
};
fetch('https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges"
payload = { "Items": [
{
"LoadNumber": "<string>",
"Amount": 123
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json-patch+json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'Items' => [
[
'LoadNumber' => '<string>',
'Amount' => 123
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json-patch+json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges"
payload := strings.NewReader("{\n \"Items\": [\n {\n \"LoadNumber\": \"<string>\",\n \"Amount\": 123\n }\n ]\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json-patch+json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://integrations.alvys.com/api/p/v{version}/loads/fuel-surcharges")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json-patch+json")
.body("{\n \"Items\": [\n {\n \"LoadNumber\": \"<string>\",\n \"Amount\": 123\n }\n ]\n}")
.asString();{
"Results": [
{
"LoadNumber": "<string>",
"Status": 123,
"Changed": true,
"FuelSurchargeAmount": 123,
"Error": "<string>",
"Warning": "<string>"
}
]
}{
"Errors": {},
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}{
"Type": "<string>",
"Title": "<string>",
"Status": 123,
"Detail": "<string>",
"Instance": "<string>"
}