Update load - Alvys

PATCH

api

{version}

loads

{loadNumber}

Update load

curl --request PATCH \
  --url https://integrations.alvys.com/api/p/v{version}/loads/{loadNumber} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: <if-match>' \
  --data '
{
  "OrderNumber": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {
    'If-Match': '<if-match>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({OrderNumber: '<string>'})
};

fetch('https://integrations.alvys.com/api/p/v{version}/loads/{loadNumber}', 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/{loadNumber}"

payload = { "OrderNumber": "<string>" }
headers = {
    "If-Match": "<if-match>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(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/{loadNumber}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'OrderNumber' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "If-Match: <if-match>"
  ],
]);

$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/{loadNumber}"

	payload := strings.NewReader("{\n  \"OrderNumber\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("If-Match", "<if-match>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://integrations.alvys.com/api/p/v{version}/loads/{loadNumber}")
  .header("If-Match", "<if-match>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"OrderNumber\": \"<string>\"\n}")
  .asString();

{
  "Id": "<string>",
  "LoadNumber": "<string>",
  "OrderNumber": "<string>",
  "CustomerId": "<string>",
  "Status": "<string>",
  "LoadType": "<string>",
  "CustomerType": [
    "<string>"
  ],
  "Stops": [
    {
      "AppointmentRequested": true,
      "AppointmentConfirmed": true,
      "ScheduleType": "<string>",
      "Id": "<string>",
      "StopType": "<string>",
      "References": [
        {
          "Name": "<string>",
          "Value": "<string>",
          "Id": "<string>",
          "ReferenceId": "<string>",
          "Type": "<string>",
          "Access": "<string>",
          "Origin": "<string>"
        }
      ],
      "$type": "<string>",
      "AppointmentDate": "2023-11-07T05:31:56Z",
      "LoadingType": "<string>",
      "Address": {
        "Street": "<string>",
        "City": "<string>",
        "State": "<string>",
        "ZipCode": "<string>"
      },
      "Coordinates": {
        "Latitude": "<string>",
        "Longitude": "<string>"
      },
      "Status": "<string>",
      "ArrivedAt": "2023-11-07T05:31:56Z",
      "DepartedAt": "2023-11-07T05:31:56Z",
      "CompanyId": "<string>",
      "CompanyNumber": "<string>",
      "CompanyName": "<string>"
    }
  ],
  "InvoiceAs": "<string>",
  "Notes": [
    {
      "id": "<string>",
      "Description": "<string>",
      "NoteType": "<string>",
      "User": "<string>",
      "Time": "2023-11-07T05:31:56Z",
      "UserId": "<string>"
    }
  ],
  "CreatedAt": "2023-11-07T05:31:56Z",
  "CreatedBy": "<string>",
  "References": [
    {
      "Name": "<string>",
      "Value": "<string>",
      "Id": "<string>",
      "ReferenceId": "<string>",
      "Type": "<string>",
      "Access": "<string>",
      "Origin": "<string>"
    }
  ],
  "PONumber": "<string>",
  "CustomerName": "<string>",
  "CustomerNumber": "<string>",
  "ContractId": "<string>",
  "Fleet": {
    "Id": "<string>",
    "Name": "<string>",
    "InvoiceNumberPrefix": "<string>"
  },
  "OfficeId": "<string>",
  "Linehaul": {
    "Amount": 123,
    "Currency": 123
  },
  "FuelSurcharge": {
    "Amount": 123,
    "Currency": 123
  },
  "CustomerAccessorials": {
    "Amount": 123,
    "Currency": 123
  },
  "CustomerAccessorialsDetails": [
    {
      "Id": "<string>",
      "Type": "<string>",
      "Total": {
        "Amount": 123,
        "Currency": 123
      },
      "Rate": {
        "Amount": 123,
        "Currency": 123
      },
      "RateType": "<string>",
      "Uom": "<string>",
      "Quantity": 123,
      "IsPaid": true,
      "CreatedAt": "2023-11-07T05:31:56Z",
      "CreatedBy": "<string>",
      "UpdatedAt": "2023-11-07T05:31:56Z",
      "UpdatedBy": "<string>"
    }
  ],
  "CustomerRate": {
    "Amount": 123,
    "Currency": 123
  },
  "CustomerMileage": {
    "Distance": {
      "Value": 123
    },
    "Source": "<string>",
    "ProfileId": "<string>",
    "ProfileName": "<string>"
  },
  "InvoicedAmount": {
    "Amount": 123,
    "Currency": 123
  },
  "Weight": {
    "Value": 123
  },
  "Volume": {
    "Value": 123
  },
  "ScheduledPickupAt": "2023-11-07T05:31:56Z",
  "ScheduledDeliveryAt": "2023-11-07T05:31:56Z",
  "PickedUpAt": "2023-11-07T05:31:56Z",
  "DeliveredAt": "2023-11-07T05:31:56Z",
  "InvoicedAt": "2023-11-07T05:31:56Z",
  "LastInvoiceSentAt": "2023-11-07T05:31:56Z",
  "CancelledAt": "2023-11-07T05:31:56Z",
  "CancelledBy": "<string>",
  "CustomerServiceRepId": "<string>",
  "CustomerSalesAgentId": "<string>",
  "CustomerSalesManagerId": "<string>",
  "CustomerLoadPlannerId": "<string>",
  "UpdatedAt": "2023-11-07T05:31:56Z",
  "UpdatedBy": "<string>",
  "CustomerAccountManagerId": "<string>",
  "PaidAt": "2023-11-07T05:31:56Z",
  "TotalPaid": {
    "Amount": 123,
    "Currency": 123
  },
  "Payments": [
    {
      "Id": "<string>",
      "Amount": {
        "Amount": 123,
        "Currency": 123
      },
      "PaidAt": "2023-11-07T05:31:56Z"
    }
  ],
  "TenderId": "<string>",
  "IsDeleted": true,
  "RequiredEquipment": [
    "<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>"
}

{
  "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 Load endpoint applies a partial (PATCH) update to an existing load. Today the only writable field is the Order Number (the partner-facing “Shipment Id”); the payload shape allows future writable fields to be added without a breaking change. Fields that are omitted from the body are left unchanged. Updates use optimistic concurrency: you must send the load’s current ETag in an If-Match header. The current ETag is returned on the ETag response header of this endpoint and of the load read endpoints. For more information on how versioning works and how to include it in your requests, please refer to the Versioning page.

Request Parameters

The following parameters are available in the URL path:

Parameter	Type	Required	Description
version	String	Yes	The version of the API.
loadNumber	String	Yes	The load number of the load to update.

The following header is required:

Header	Type	Required	Description
If-Match	String	Yes	The load’s current `ETag`, for optimistic concurrency. If omitted, the request is rejected with `428`.

Request Body

Field	Type	Required	Description
OrderNumber	String	No	The partner-facing Order Number (“Shipment Id”). Must be 30 characters or fewer. Omit to leave it unchanged; a blank value is rejected.

Example CURL Request

curl --location --request PATCH 'https://integrations.alvys.com/api/p/v1/loads/{loadNumber}' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'If-Match: "00000000-0000-0000-0000-000000000001"' \
--data-raw '{
  "OrderNumber": "SHIP-100245"
}'

Replace {loadNumber} with the actual load number, the If-Match value with the load’s current ETag, and YOUR_ACCESS_TOKEN with your actual Bearer token.

Response

On success the endpoint returns the updated load (the same object shape as Get Loads), and the new optimistic-concurrency token on the ETag response header.

Status Codes

Code	Description
200	The load was updated; the response body contains the updated load.
400	The request body failed validation (e.g., Order Number longer than 30 characters or blank).
401	Authentication failed or the token is missing.
403	The token is not authorized to update loads.
404	No load was found for the given load number.
409	The update conflicts with the current state of the load.
412	The `If-Match` ETag did not match the load’s current version (it changed since you read it).
428	The `If-Match` header was not provided.

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>.

Headers

If-Match

string

required

The load's current ETag (from a prior GET/response), for optimistic concurrency. Required; if omitted the request is rejected with 428.

Path Parameters

loadNumber

string

required

version

string

default:1.0

required

API version (e.g., 1.0)

Example:

"1.0"

Body

OrderNumber

string | null

The partner-facing Order Number ("Shipment Id"). Maximum 30 characters. Omit the field to leave it unchanged; a present but blank/whitespace value is rejected.

Maximum string length: 30

Response

string

required

LoadNumber

string

required

OrderNumber

string

required

CustomerId

string

required

Status

string

required

LoadType

string

required

deprecated

CustomerType

string[]

required

Stops

object[]

required

Option 1
Option 2
Option 3

Show child attributes

InvoiceAs

string

required

Notes

object[]

required

Show child attributes

CreatedAt

string<date-time>

required

CreatedBy

string

required

References

object[]

required

Show child attributes

PONumber

string | null

CustomerName

string | null

CustomerNumber

string | null

ContractId

string | null

Fleet

object | null

Show child attributes

OfficeId

string | null

Linehaul

object | null

Show child attributes

FuelSurcharge

object | null

Show child attributes

CustomerAccessorials

object | null

Show child attributes

CustomerAccessorialsDetails

object[] | null

Show child attributes

CustomerRate

object | null

Show child attributes

CustomerMileage

object | null

Show child attributes

InvoicedAmount

object | null

Show child attributes

Weight

object | null

Show child attributes

Volume

object | null

Show child attributes

ScheduledPickupAt

string<date-time> | null

ScheduledDeliveryAt

string<date-time> | null

PickedUpAt

string<date-time> | null

DeliveredAt

string<date-time> | null

InvoicedAt

string<date-time> | null

LastInvoiceSentAt

string<date-time> | null

CancelledAt

string<date-time> | null

CancelledBy

string | null

CustomerServiceRepId

string | null

CustomerSalesAgentId

string | null

CustomerSalesManagerId

string | null

CustomerLoadPlannerId

string | null

UpdatedAt

string<date-time> | null

UpdatedBy

string | null

CustomerAccountManagerId

string | null

PaidAt

string<date-time> | null

TotalPaid

object | null

Show child attributes

Payments

object[] | null

Show child attributes

TenderId

string | null

IsDeleted

boolean | null

RequiredEquipment

string[] | null

⌘I

Update load

curl --request PATCH \
  --url https://integrations.alvys.com/api/p/v{version}/loads/{loadNumber} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: <if-match>' \
  --data '
{
  "OrderNumber": "<string>"
}
'

const options = {
  method: 'PATCH',
  headers: {
    'If-Match': '<if-match>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({OrderNumber: '<string>'})
};

fetch('https://integrations.alvys.com/api/p/v{version}/loads/{loadNumber}', 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/{loadNumber}"

payload = { "OrderNumber": "<string>" }
headers = {
    "If-Match": "<if-match>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(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/{loadNumber}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'OrderNumber' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "If-Match: <if-match>"
  ],
]);

$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/{loadNumber}"

	payload := strings.NewReader("{\n  \"OrderNumber\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("If-Match", "<if-match>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://integrations.alvys.com/api/p/v{version}/loads/{loadNumber}")
  .header("If-Match", "<if-match>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"OrderNumber\": \"<string>\"\n}")
  .asString();

{
  "Id": "<string>",
  "LoadNumber": "<string>",
  "OrderNumber": "<string>",
  "CustomerId": "<string>",
  "Status": "<string>",
  "LoadType": "<string>",
  "CustomerType": [
    "<string>"
  ],
  "Stops": [
    {
      "AppointmentRequested": true,
      "AppointmentConfirmed": true,
      "ScheduleType": "<string>",
      "Id": "<string>",
      "StopType": "<string>",
      "References": [
        {
          "Name": "<string>",
          "Value": "<string>",
          "Id": "<string>",
          "ReferenceId": "<string>",
          "Type": "<string>",
          "Access": "<string>",
          "Origin": "<string>"
        }
      ],
      "$type": "<string>",
      "AppointmentDate": "2023-11-07T05:31:56Z",
      "LoadingType": "<string>",
      "Address": {
        "Street": "<string>",
        "City": "<string>",
        "State": "<string>",
        "ZipCode": "<string>"
      },
      "Coordinates": {
        "Latitude": "<string>",
        "Longitude": "<string>"
      },
      "Status": "<string>",
      "ArrivedAt": "2023-11-07T05:31:56Z",
      "DepartedAt": "2023-11-07T05:31:56Z",
      "CompanyId": "<string>",
      "CompanyNumber": "<string>",
      "CompanyName": "<string>"
    }
  ],
  "InvoiceAs": "<string>",
  "Notes": [
    {
      "id": "<string>",
      "Description": "<string>",
      "NoteType": "<string>",
      "User": "<string>",
      "Time": "2023-11-07T05:31:56Z",
      "UserId": "<string>"
    }
  ],
  "CreatedAt": "2023-11-07T05:31:56Z",
  "CreatedBy": "<string>",
  "References": [
    {
      "Name": "<string>",
      "Value": "<string>",
      "Id": "<string>",
      "ReferenceId": "<string>",
      "Type": "<string>",
      "Access": "<string>",
      "Origin": "<string>"
    }
  ],
  "PONumber": "<string>",
  "CustomerName": "<string>",
  "CustomerNumber": "<string>",
  "ContractId": "<string>",
  "Fleet": {
    "Id": "<string>",
    "Name": "<string>",
    "InvoiceNumberPrefix": "<string>"
  },
  "OfficeId": "<string>",
  "Linehaul": {
    "Amount": 123,
    "Currency": 123
  },
  "FuelSurcharge": {
    "Amount": 123,
    "Currency": 123
  },
  "CustomerAccessorials": {
    "Amount": 123,
    "Currency": 123
  },
  "CustomerAccessorialsDetails": [
    {
      "Id": "<string>",
      "Type": "<string>",
      "Total": {
        "Amount": 123,
        "Currency": 123
      },
      "Rate": {
        "Amount": 123,
        "Currency": 123
      },
      "RateType": "<string>",
      "Uom": "<string>",
      "Quantity": 123,
      "IsPaid": true,
      "CreatedAt": "2023-11-07T05:31:56Z",
      "CreatedBy": "<string>",
      "UpdatedAt": "2023-11-07T05:31:56Z",
      "UpdatedBy": "<string>"
    }
  ],
  "CustomerRate": {
    "Amount": 123,
    "Currency": 123
  },
  "CustomerMileage": {
    "Distance": {
      "Value": 123
    },
    "Source": "<string>",
    "ProfileId": "<string>",
    "ProfileName": "<string>"
  },
  "InvoicedAmount": {
    "Amount": 123,
    "Currency": 123
  },
  "Weight": {
    "Value": 123
  },
  "Volume": {
    "Value": 123
  },
  "ScheduledPickupAt": "2023-11-07T05:31:56Z",
  "ScheduledDeliveryAt": "2023-11-07T05:31:56Z",
  "PickedUpAt": "2023-11-07T05:31:56Z",
  "DeliveredAt": "2023-11-07T05:31:56Z",
  "InvoicedAt": "2023-11-07T05:31:56Z",
  "LastInvoiceSentAt": "2023-11-07T05:31:56Z",
  "CancelledAt": "2023-11-07T05:31:56Z",
  "CancelledBy": "<string>",
  "CustomerServiceRepId": "<string>",
  "CustomerSalesAgentId": "<string>",
  "CustomerSalesManagerId": "<string>",
  "CustomerLoadPlannerId": "<string>",
  "UpdatedAt": "2023-11-07T05:31:56Z",
  "UpdatedBy": "<string>",
  "CustomerAccountManagerId": "<string>",
  "PaidAt": "2023-11-07T05:31:56Z",
  "TotalPaid": {
    "Amount": 123,
    "Currency": 123
  },
  "Payments": [
    {
      "Id": "<string>",
      "Amount": {
        "Amount": 123,
        "Currency": 123
      },
      "PaidAt": "2023-11-07T05:31:56Z"
    }
  ],
  "TenderId": "<string>",
  "IsDeleted": true,
  "RequiredEquipment": [
    "<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>"
}

{
  "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>"
}

​Request Parameters

​Request Body

​Example CURL Request

​Response

​Status Codes

Authorizations

Headers

Path Parameters

Body

Response

Request Parameters

Request Body

Example CURL Request

Response

Status Codes