--- title: "Patch a load" method: PATCH path: "/v2/loads" tags: ["Load Management"] --- # Patch a load `PATCH /v2/loads` ## Request - Base URL: `https://api.prod.goaugment.com` - URL: `https://api.prod.goaugment.com/v2/loads` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Apply one or more patch operations to an existing load using a JSON Patch-inspired format ([RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902)). Each operation targets a specific field by JSON Pointer path and specifies how to change it. Operations are applied to the stored load and the merged result is then validated as a whole. A patch can therefore be rejected because of fields it did not touch. Most commonly, replacing `/status` with `CUSTOMER_CONFIRMED` or a later status fails when the stored route stops have no appointment windows — see [Load Status Validation](/guide/start-developing/load-status-validation). ## Supported operations | `op` | Description | |---------|-------------| | `add` | Set a value or insert into an array at a specific index. | | `remove` | Remove a value or array element. | | `replace` | Replace an existing value. | | `append` | *(Custom)* Append an item to the end of an array. | | `upsert` | *(Custom)* Update an existing array element matching the `where` condition, or insert a new one if no match is found. | ## Allowed paths Operations are validated against an allowlist of supported paths. Attempts to modify other paths will be rejected. | `path` | Supported operations | Value example | |--------|---------------------|---------------| | `/status` | `add`, `replace` | `"DISPATCHED"` | | `/mode` | `add`, `replace` | `"FTL"` | | `/loadType` | `add`, `replace` | `"SPOT"` | | `/equipment` | `add`, `replace` | `"DRY_VAN"` | | `/equipmentDescription` | `add`, `replace` | `"53ft Dry Van"` | | `/commodity` | `add`, `replace` | `"Electronics"` | | `/service` | `add`, `replace` | `"STANDARD"` | | `/targetRate` | `add`, `replace` | `1250.00` | | `/maxRate` | `add`, `replace` | `3000.00` | | `/totalRate` | `add`, `replace` | `2750.00` | | `/highValueAmount` | `add`, `replace` | `50000` | | `/totalMiles` | `add`, `replace` | `1200` | | `/tarpSize` | `add`, `replace` | `"40x48"` | | `/customerName` | `add`, `replace` | `"Acme Corp"` | | `/customerContact` | `add`, `replace` | `"Jane Smith"` | | `/customerNotes` | `add`, `replace` | `"Call before delivery"` | | `/customerId` | `add`, `replace` | `"ACME-001"` | | `/isPostedToDAT` | `add`, `replace` | `true` | | `/bidExpiration` | `add`, `replace` | `"2025-08-21T12:34:56Z"` | | `/lastLocationUpdate` | `add`, `replace` | `"2025-10-15T20:20:00Z"` | | `/weight` | `add`, `replace` | `{"value": 45000, "unit": "LB"}` | | `/dimensions` | `add`, `replace` | `{"lengthInches": 600, "widthInches": 96, "heightInches": 108}` | | `/minimumTemperature` | `add`, `replace` | `{"value": 32, "unit": "F"}` | | `/maximumTemperature` | `add`, `replace` | `{"value": 68, "unit": "F"}` | | `/minimumBulkHeadTemperature` | `add`, `replace` | `{"value": 35, "unit": "F"}` | | `/maximumBulkHeadTemperature` | `add`, `replace` | `{"value": 65, "unit": "F"}` | | `/externalTrackingStatus` | `add`, `replace` | `{"source": "MACROPOINT", "code": "READY"}` | | `/customData` | `add`, `replace` | `{"key": "value"}` | | `/notes` | `add`, `remove`, `append`, `upsert` | `{"text": "Driver is 30 min out"}` | | `/accessorials` | `add`, `remove`, `append`, `upsert` | `"HAZMAT"` | | `/referenceNumbers` | `add`, `remove`, `append`, `upsert` | `{"name": "PO_NUMBER", "value": "PO-12345"}` | | `/trackingEvents` | `add`, `remove`, `append`, `upsert` | `{"eventType": "PICKED_UP", "eventSource": "CARRIER_API", "eventUtc": "2025-08-21T12:34:56Z"}` | | `/bidCustomValues` | `add`, `remove`, `append`, `upsert` | `{"name": "rush", "value": "true"}` | | `/commodityItems` | `add`, `remove`, `append`, `upsert` | `{"quantity": 10, "description": "boxes"}` | | `/route` | `add`, `remove`, `append`, `upsert` | `{"sequence": 1, "stopActivity": "PICKUP"}` | | `/carrier` | `add`, `remove`, `replace` | `add`: assign a carrier when the load has none.
`replace`: replace the carrier already on the load.
Both use `value` shaped as [**LoadPatchCarrier**](#model/LoadPatchCarrier).
`remove`: unassign the carrier (omit `value`). | | `/carrier/drivers` | `append`, `replace` | `append`: one [**LoadPatchCarrierDriver**](#model/LoadPatchCarrierDriver).
`replace`: array of the same schema (replaces the full drivers list). | | `/carrier/contacts` | `append`, `replace` | `append`: one [**LoadPatchCarrierContact**](#model/LoadPatchCarrierContact).
`replace`: array of the same schema (replaces the full contacts list). | ## Examples **Replace a simple field:** ```json { "op": "replace", "path": "/status", "value": "IN_TRANSIT" } ``` **Append to an array:** ```json { "op": "append", "path": "/notes", "value": { "text": "Driver is 30 min out" } } ``` **Upsert an array element (update stop 1 if it exists, insert if not):** ```json { "op": "upsert", "path": "/route", "value": { "sequence": 1, "stopActivity": "PICKUP" }, "where": { "sequence": 1 } } ``` **Assign carrier on load:** ```json { "op": "add", "path": "/carrier", "value": { "carrierId": "tms-carrier-42", "name": "Acme Trucking", "dotNumber": 1234567, "drivers": [{ "id": "drv-1", "name": "Driver One", "phone": "+12081234567" }], "contacts": [ { "role": "DISPATCHER", "name": "Dispatch", "email": "dispatch@example.com" }, { "role": "AP_REP", "name": "AP", "email": "ap@example.com" } ] } } ``` **Clear carrier from load:** ```json { "op": "remove", "path": "/carrier" } ``` **Append a driver:** ```json { "op": "append", "path": "/carrier/drivers", "value": { "id": "drv-2", "name": "Jane Driver", "phone": "+12081234568", "phoneExtension": "101" } } ``` **Replace carrier contacts:** ```json { "loadReference": "LOAD-12345", "operations": [ { "op": "replace", "path": "/carrier/contacts", "value": [ { "id": "contact-dispatch-1", "role": "DISPATCHER", "name": "Night dispatch", "email": "dispatch@example.com", "phone": "+12081234569", "phoneExtension": "202" }, { "id": "contact-ap-1", "role": "AP_REP", "name": "Accounts payable", "email": "ap@example.com", "phone": "+12081234570", "phoneExtension": "303" } ] } ] } ``` ## Request body - LoadPatchRequest - `loadReference` string, required: The load number (brokerage load ID) of the load to patch. - `operations` LoadPatchOperation[], required: One or more patch operations to apply, in order. - union - object - `op` 'remove', required - `path` string, required: A JSON Pointer ([RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)) identifying the field to operate on. Must be one of the allowed paths documented in the PATCH endpoint description. - object - `op` 'add' | 'replace' | 'append', required: The operation to perform. `add` and `replace` follow [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). `append` is a custom extension that pushes a new element onto an array field. - `path` string, required: A JSON Pointer ([RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)) identifying the field to operate on. Must be one of the allowed paths documented in the PATCH endpoint description. - `value` unknown, required - object - `op` 'upsert', required: Custom operation that updates an existing array element matching the `where` condition, or inserts a new one if no match is found. - `path` string, required: A JSON Pointer ([RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)) identifying the array field to operate on. Must be one of the allowed paths documented in the PATCH endpoint description. - `value` unknown, required - `where` object, required: A map of field names to expected values used to identify an existing array element. If a matching element is found it is replaced with `value`; otherwise `value` is appended. ## Response `204` Load patched successfully ## Other responses - `400`: Bad request — invalid operation, disallowed path, missing required field, or a merged result that fails validation (for example moving `/status` to `CUSTOMER_CONFIRMED` while stored route stops have no appointment windows). `details` carries the underlying validation output as a string. - `401`: Unauthorized - `404`: Load not found --- [API](https://skmtc.dev/goaugment/apis/augment-api.md) - [All operations](https://skmtc.dev/goaugment/apis/augment-api/llms.txt) - [OpenAPI document](https://skmtc.dev/goaugment/apis/augment-api/revisions/b61097634d79?raw)