Apply one or more patch operations to an existing load using a JSON Patch-inspired format (RFC 6902).

Each operation targets a specific field by JSON Pointer path and specifies how to change it.

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", "packageType": "PALLET"}
/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. remove: unassign the carrier (omit value).
/carrier/drivers	append, replace	append: one LoadPatchCarrierDriver. replace: array of the same schema (replaces the full drivers list).
/carrier/contacts	append, replace	append: one LoadPatchCarrierContact. replace: array of the same schema (replaces the full contacts list).

Examples

Replace a simple field:

{ "op": "replace", "path": "/status", "value": "IN_TRANSIT" }

Append to an array:

{ "op": "append", "path": "/notes", "value": { "text": "Driver is 30 min out" } }

Upsert an array element (update stop 1 if it exists, insert if not):

{ "op": "upsert", "path": "/route", "value": { "sequence": 1, "stopActivity": "PICKUP" }, "where": { "sequence": 1 } }

Assign carrier on load:

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

{ "op": "remove", "path": "/carrier" }

Append a driver:

{
  "op": "append",
  "path": "/carrier/drivers",
  "value": {
    "id": "drv-2",
    "name": "Jane Driver",
    "phone": "+12081234568",
    "phoneExtension": "101"
  }
}

Replace carrier contacts:

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