Update a Load's Order Number via the Public API

What's New?

We've added a PATCH /p/v1.0/loads/{loadNumber} endpoint to the Public API. Partners running an external system of record (e.g. AS400) can now write their generated identifier back onto an Alvys load as the Order Number (Shipment ID) — programmatically, with no human in the loop.

The endpoint is a partial update: only the fields you send are modified, leaving everything else untouched. It's shaped so additional writable load fields can be added later without breaking the contract. In this first iteration, orderNumber is the only writable field.

What Changed?

Previously, a load's Order Number could only be set in the UI — there was no public write path. Now you can update it directly:

curl --location --request PATCH 'https://integrations.alvys.com/api/p/v1.0/loads/3039979' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'If-Match: "8DBAC1F2E3..."' \
--data-raw '{
  "orderNumber": "2026-00471"
}'

A successful call returns 200 OK with the updated load representation and a fresh ETag.

Preventing Accidental Overwrites

To help prevent one update from accidentally overwriting another, this endpoint requires the latest record version when making changes.

When you retrieve or update a record, the response includes an ETag. Send that value in the If-Match request header when making your next update.

If you receive 412 Precondition Failed, retrieve the record again to get the latest ETag, then retry the update.

After a successful update, the new ETag is returned in both the response body and the ETag response header, so you can use it for the next update without making another GET request.

Validation & History

• A blank or empty Order Number is rejected with 400 Bad Request — the same rule as the internal Order Number update.
• Every change is written to the load's history (the same audit trail as the UI path).
• EDI-originated loads are rejected. The Order Number on an EDI load is locked to the value received on the inbound tender and cannot be changed through this endpoint.

Endpoints Affected

PATCH /p/v1.0/loads/{loadNumber} is new and updates a load's Order Number.

No request or response shapes were changed for existing endpoints. This update is fully backward compatible.

Response Codes