Patch a load

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.

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.

Supported operations

Allowed paths

Operations are validated against an allowlist of supported paths. Attempts to modify other paths will be rejected.

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