> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update load

> Partially update a load by load number in Alvys, changing only the supplied fields such as rate, references, equipment, assigned driver, or stop details.

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](/docs/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

```bash theme={null}
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](/reference/loads/get-load)), 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.                                                      |


## OpenAPI

````yaml PATCH /api/p/v{version}/loads/{loadNumber}
openapi: 3.0.1
info:
  title: Alvys
  description: >-
    Alvys provides a robust set of REST APIs to allow you to integrate Alvys
    into virtually any platform. These APIs cover most of Alvys' major product
    areas with additional endpoints being added regularly based on customer
    requests.
  contact:
    name: Alvys Support
    url: https://www.alvys.com/resources/contact/
  version: v1
servers:
  - url: https://integrations.alvys.com
    description: Public API Server
  - url: https://api.alvys.com/
    description: Public API Server
security:
  - Public: []
tags:
  - name: Authentication
    description: Obtain an OAuth 2.0 access token for the Alvys Public API.
  - name: Carrier Settlement Statements
    description: >-
      Search carrier settlement statements and retrieve a single statement by
      number.
  - name: Carriers
    description: Read carrier records, search carriers, and manage carrier documents.
  - name: Customers
    description: Create, read, update, delete, and search customer records.
  - name: Deductions
    description: >-
      Create one-time deductions and search or delete existing deduction
      records.
  - name: DispatchPreferences
    description: Dispatch preferences endpoints for reading dispatch rules and preferences.
  - name: Driver Settlement Statements
    description: >-
      Search driver settlement statements and retrieve a single statement by
      number.
  - name: Drivers
    description: >-
      Read driver records, search drivers and driver events, and manage driver
      documents.
  - name: Fuel
    description: Read and search fuel transactions.
  - name: Invoices
    description: >-
      Read invoices, create carrier invoices, and record carrier and customer
      payments.
  - name: Loads
    description: Read, update, search loads, and manage load documents and notes.
  - name: Locations
    description: Read and search company location details.
  - name: Maintenance
    description: Read and search maintenance records.
  - name: Tenders
    description: Create, accept, reject, cancel, update, and search inbound EDI tenders.
  - name: Tolls
    description: Read and search toll transactions.
  - name: Trailers
    description: Read trailers, search trailer events, and manage trailer documents.
  - name: Trips
    description: >-
      Read, search trips, manage trip documents, and record stop appointments,
      arrivals, and departures.
  - name: Trucks
    description: Read trucks, search truck events, and manage truck documents.
  - name: Users
    description: List and search users.
  - name: Visibility
    description: >-
      Read inbound and outbound visibility history and search outbound
      visibility errors.
  - name: Webhooks
    description: >-
      Create, read, update, delete, enable, disable, verify, test, and rotate
      secrets for webhook subscriptions; read event types, delivery logs, and
      health metrics.
paths:
  /api/p/v{version}/loads/{loadNumber}:
    patch:
      tags:
        - Loads
      summary: Update load
      parameters:
        - name: loadNumber
          in: path
          required: true
          schema:
            type: string
        - name: version
          in: path
          description: API version (e.g., 1.0)
          required: true
          schema:
            type: string
            default: '1.0'
            example: '1.0'
        - name: If-Match
          in: header
          required: true
          description: >-
            The load's current ETag (from a prior GET/response), for optimistic
            concurrency. Required; if omitted the request is rejected with 428.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Alvys.Models.Loads.LoadWriteRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/Alvys.Models.Loads.LoadWriteRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/Alvys.Models.Loads.LoadWriteRequest'
          application/json-patch+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Alvys.Models.Loads.LoadWriteRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alvys.Models.Loads.LoadResponse'
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '412':
          description: Precondition Failed (If-Match ETag did not match the current load)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '428':
          description: Precondition Required (If-Match header missing)
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
      security:
        - Public: []
components:
  schemas:
    Alvys.Models.Loads.LoadWriteRequest:
      type: object
      additionalProperties: false
      properties:
        OrderNumber:
          type: string
          description: >-
            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.
          maxLength: 30
          nullable: true
    Alvys.Models.Loads.LoadResponse:
      required:
        - CreatedAt
        - CreatedBy
        - CustomerId
        - CustomerType
        - Id
        - InvoiceAs
        - LoadNumber
        - LoadType
        - Notes
        - OrderNumber
        - References
        - Status
        - Stops
      type: object
      properties:
        Id:
          type: string
        LoadNumber:
          type: string
        OrderNumber:
          type: string
        PONumber:
          type: string
          nullable: true
        CustomerId:
          type: string
        CustomerName:
          type: string
          nullable: true
        CustomerNumber:
          type: string
          nullable: true
        Status:
          type: string
        LoadType:
          type: string
          deprecated: true
        ContractId:
          type: string
          nullable: true
        CustomerType:
          type: array
          items:
            type: string
        Stops:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.Trips.StopResponse'
        Fleet:
          allOf:
            - $ref: '#/components/schemas/FleetResponse'
          nullable: true
        InvoiceAs:
          type: string
        OfficeId:
          type: string
          nullable: true
        Linehaul:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
          nullable: true
        FuelSurcharge:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
          nullable: true
        CustomerAccessorials:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
          nullable: true
        CustomerAccessorialsDetails:
          type: array
          items:
            $ref: >-
              #/components/schemas/Alvys.Models.Accessorials.CustomerAccessorialResponse
          nullable: true
        CustomerRate:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
          nullable: true
        CustomerMileage:
          allOf:
            - $ref: '#/components/schemas/Alvys.Models.Loads.LoadResponseMileage'
          nullable: true
        InvoicedAmount:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
          nullable: true
        Weight:
          allOf:
            - $ref: '#/components/schemas/Alvys.Weight'
          nullable: true
        Volume:
          allOf:
            - $ref: '#/components/schemas/Alvys.Volume'
          nullable: true
        ScheduledPickupAt:
          type: string
          format: date-time
          nullable: true
        ScheduledDeliveryAt:
          type: string
          format: date-time
          nullable: true
        PickedUpAt:
          type: string
          format: date-time
          nullable: true
        DeliveredAt:
          type: string
          format: date-time
          nullable: true
        InvoicedAt:
          type: string
          format: date-time
          nullable: true
        LastInvoiceSentAt:
          type: string
          format: date-time
          nullable: true
        Notes:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.Notes.NoteDto'
        CreatedAt:
          type: string
          format: date-time
        CreatedBy:
          type: string
        CancelledAt:
          type: string
          format: date-time
          nullable: true
        CancelledBy:
          type: string
          nullable: true
        References:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.References.ReferenceResponse'
        CustomerServiceRepId:
          type: string
          nullable: true
        CustomerSalesAgentId:
          type: string
          nullable: true
        CustomerSalesManagerId:
          type: string
          nullable: true
        CustomerLoadPlannerId:
          type: string
          nullable: true
        UpdatedAt:
          type: string
          format: date-time
          nullable: true
        UpdatedBy:
          type: string
          nullable: true
        CustomerAccountManagerId:
          type: string
          nullable: true
        PaidAt:
          type: string
          format: date-time
          nullable: true
        TotalPaid:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
          nullable: true
        Payments:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.Loads.LoadResponsePaymentDto'
          nullable: true
        TenderId:
          type: string
          nullable: true
        IsDeleted:
          type: boolean
          nullable: true
        RequiredEquipment:
          type: array
          items:
            type: string
          nullable: true
      additionalProperties: false
    Microsoft.AspNetCore.Mvc.ValidationProblemDetails:
      required:
        - Errors
      type: object
      properties:
        Errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
    Microsoft.AspNetCore.Mvc.ProblemDetails:
      type: object
      properties:
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
    Alvys.Models.Trips.StopResponse:
      required:
        - $type
      type: object
      oneOf:
        - $ref: '#/components/schemas/Alvys.Models.Trips.AppointmentStopResponse'
        - $ref: '#/components/schemas/Alvys.Models.Trips.DeliveryWindowStopResponse'
        - $ref: '#/components/schemas/Alvys.Models.Trips.WaypointStopResponse'
      properties:
        $type:
          type: string
          description: Type discriminator for polymorphic serialization
      additionalProperties: false
      discriminator:
        propertyName: $type
        mapping:
          appointment:
            $ref: '#/components/schemas/Alvys.Models.Trips.AppointmentStopResponse'
          delivery_window:
            $ref: '#/components/schemas/Alvys.Models.Trips.DeliveryWindowStopResponse'
          waypoint:
            $ref: '#/components/schemas/Alvys.Models.Trips.WaypointStopResponse'
    FleetResponse:
      type: object
      properties:
        Id:
          type: string
          nullable: true
        Name:
          type: string
          nullable: true
        InvoiceNumberPrefix:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Money:
      required:
        - Amount
      type: object
      properties:
        Amount:
          type: number
          format: double
        Currency:
          type: integer
          format: int32
          nullable: true
      additionalProperties: false
    Alvys.Models.Accessorials.CustomerAccessorialResponse:
      required:
        - Id
        - Quantity
        - Rate
        - RateType
        - Total
        - Type
        - Uom
      type: object
      properties:
        Id:
          type: string
        Type:
          type: string
        Total:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        Rate:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        RateType:
          type: string
        Uom:
          type: string
        Quantity:
          type: number
          format: double
        IsPaid:
          type: boolean
          nullable: true
        CreatedAt:
          type: string
          format: date-time
          nullable: true
        CreatedBy:
          type: string
          nullable: true
        UpdatedAt:
          type: string
          format: date-time
          nullable: true
        UpdatedBy:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Models.Loads.LoadResponseMileage:
      required:
        - Distance
      type: object
      properties:
        Distance:
          allOf:
            - $ref: '#/components/schemas/Alvys.Distance'
        Source:
          type: string
          nullable: true
        ProfileId:
          type: string
          nullable: true
        ProfileName:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Weight:
      required:
        - UnitOfMeasure
        - Value
      type: object
      properties:
        Value:
          type: number
          format: double
        UnitOfMeasure:
          allOf:
            - $ref: '#/components/schemas/Alvys.WeightWeightUnits'
      additionalProperties: false
    Alvys.Volume:
      required:
        - UnitOfMeasure
        - Value
      type: object
      properties:
        Value:
          type: number
          format: double
        UnitOfMeasure:
          allOf:
            - $ref: '#/components/schemas/Alvys.VolumeVolumeUnits'
      additionalProperties: false
    Alvys.Models.Notes.NoteDto:
      required:
        - Description
        - id
        - NoteType
        - User
      type: object
      properties:
        id:
          type: string
        Description:
          type: string
        NoteType:
          type: string
        Time:
          type: string
          format: date-time
          nullable: true
        User:
          type: string
        UserId:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Models.References.ReferenceResponse:
      required:
        - Name
        - Value
      type: object
      properties:
        Id:
          type: string
          nullable: true
        ReferenceId:
          type: string
          nullable: true
        Name:
          type: string
        Value:
          type: string
        Type:
          type: string
          nullable: true
        Access:
          type: string
          nullable: true
        Origin:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Models.Loads.LoadResponsePaymentDto:
      required:
        - Amount
        - Id
      type: object
      properties:
        Id:
          type: string
        Amount:
          allOf:
            - $ref: '#/components/schemas/Alvys.Money'
        PaidAt:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
    Alvys.Models.Trips.AppointmentStopResponse:
      required:
        - AppointmentConfirmed
        - AppointmentRequested
        - Id
        - References
        - ScheduleType
        - StopType
      type: object
      properties:
        AppointmentRequested:
          type: boolean
        AppointmentConfirmed:
          type: boolean
        AppointmentDate:
          type: string
          format: date-time
          nullable: true
        ScheduleType:
          type: string
        LoadingType:
          type: string
          nullable: true
        Id:
          type: string
        Address:
          allOf:
            - $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
          nullable: true
        Coordinates:
          allOf:
            - $ref: '#/components/schemas/Alvys.Models.Coordinates'
          nullable: true
        Status:
          type: string
          nullable: true
        StopType:
          type: string
        ArrivedAt:
          type: string
          format: date-time
          nullable: true
        DepartedAt:
          type: string
          format: date-time
          nullable: true
        References:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.References.ReferenceResponse'
        CompanyId:
          type: string
          nullable: true
        CompanyNumber:
          type: string
          nullable: true
        CompanyName:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Models.Trips.DeliveryWindowStopResponse:
      required:
        - Id
        - References
        - ScheduleType
        - StopType
      type: object
      properties:
        StopWindow:
          allOf:
            - $ref: '#/components/schemas/Alvys.Models.Trips.DateTimeWindowDto'
          nullable: true
        ScheduleType:
          type: string
        LoadingType:
          type: string
          nullable: true
        Id:
          type: string
        Address:
          allOf:
            - $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
          nullable: true
        Coordinates:
          allOf:
            - $ref: '#/components/schemas/Alvys.Models.Coordinates'
          nullable: true
        Status:
          type: string
          nullable: true
        StopType:
          type: string
        ArrivedAt:
          type: string
          format: date-time
          nullable: true
        DepartedAt:
          type: string
          format: date-time
          nullable: true
        References:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.References.ReferenceResponse'
        CompanyId:
          type: string
          nullable: true
        CompanyNumber:
          type: string
          nullable: true
        CompanyName:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Models.Trips.WaypointStopResponse:
      required:
        - $type
        - Id
        - References
        - StopType
      type: object
      properties:
        StopWindow:
          allOf:
            - $ref: '#/components/schemas/Alvys.Models.Trips.DateTimeWindowDto'
          nullable: true
        Id:
          type: string
        Address:
          allOf:
            - $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
          nullable: true
        Coordinates:
          allOf:
            - $ref: '#/components/schemas/Alvys.Models.Coordinates'
          nullable: true
        Status:
          type: string
          nullable: true
        StopType:
          type: string
        ArrivedAt:
          type: string
          format: date-time
          nullable: true
        DepartedAt:
          type: string
          format: date-time
          nullable: true
        References:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.References.ReferenceResponse'
        CompanyId:
          type: string
          nullable: true
        CompanyNumber:
          type: string
          nullable: true
        CompanyName:
          type: string
          nullable: true
        $type:
          enum:
            - waypoint
          type: string
          description: Type discriminator for polymorphic serialization
      additionalProperties: false
    Alvys.Distance:
      required:
        - UnitOfMeasure
        - Value
      type: object
      properties:
        Value:
          type: number
          format: double
        UnitOfMeasure:
          allOf:
            - $ref: '#/components/schemas/Alvys.DistanceDistanceUnits'
      additionalProperties: false
    Alvys.WeightWeightUnits:
      enum:
        - Kilograms
        - Grams
        - Pounds
        - Ounces
        - Tons
        - CWT
        - MetricTon
        - LongTon
      type: string
    Alvys.VolumeVolumeUnits:
      enum:
        - Gallons
        - Liters
        - Bushels
        - CubicFoot
        - CubicMeter
        - Quarts
      type: string
    Alvys.Features.Locations.ShortAddress:
      required:
        - City
        - State
        - Street
        - ZipCode
      type: object
      properties:
        Street:
          type: string
        City:
          type: string
        State:
          type: string
        ZipCode:
          type: string
      additionalProperties: false
    Alvys.Models.Coordinates:
      required:
        - Latitude
        - Longitude
      type: object
      properties:
        Latitude:
          type: string
        Longitude:
          type: string
      additionalProperties: false
    Alvys.Models.Trips.DateTimeWindowDto:
      required:
        - Begin
        - End
      type: object
      properties:
        Begin:
          type: string
          format: date-time
        End:
          type: string
          format: date-time
      additionalProperties: false
    Alvys.DistanceDistanceUnits:
      enum:
        - Miles
        - Kilometers
        - Meters
        - Feet
      type: string
  securitySchemes:
    Public:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        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>`.

````