> ## 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 fuel surcharge on loads

> Set a flat customer fuel surcharge on up to 25 Alvys loads in one request, with a separate result for each load so you can resend only what failed.

The Update Fuel Surcharge on Loads endpoint sets a flat customer fuel surcharge on up to 25 loads in one request. Use it when another system, such as a fuel surcharge provider, calculates the surcharge for each load. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](https://docs.alvys.com/en/api/guides/versioning.md) page.

> [!NOTE]
>
> This endpoint requires the `load:update` scope. A load that is Released, Queued, Invoiced, Financed or Completed also requires the `invoice:update` scope. See [Authentication](https://docs.alvys.com/en/api/guides/authentication-1.md).

### What the update does

Each load's fuel surcharge becomes a manual flat amount, and the load's customer rate is recalculated, as when the fuel surcharge is edited in Alvys. The amount replaces the current fuel surcharge; it is not added to it.

* **A fuel surcharge contract stops applying.** If the load's fuel surcharge came from a contract, the load no longer uses that contract.
* **Paid trips keep their amounts.** On a trip whose driver, owner-operator or carrier is already paid, the trip value, carrier rate, owner-operator rate and trip fuel surcharge are not recalculated.
* **Paid percentage pay blocks the change.** An Invoiced, Financed or Completed load is refused when a trip's driver or owner-operator is paid by percentage and has already been paid, as in Alvys.
* **EDI tender updates keep your amount.** After you set a load's fuel surcharge here, a later EDI tender update that carries a fuel surcharge does not change it. The tender's line haul and the rest of the tender update still apply.
* **`Amount = 0` sets a \$0 surcharge.** The fuel surcharge stays on the load with a zero amount.

### Identify loads by load number

Send the Alvys load number. A trip number is not accepted. To start from your order numbers, look the loads up first with [Search loads](https://docs.alvys.com/en/api/reference/loads/search-loads.md), using `OrderNumbers` and `CustomerId`. An order number can match more than one load.

***

### Request parameters

The following parameter is available in the URL path:

| Parameter | Type | Required | Description |
| - | - | - | - |
| version | String | Yes | The version of the API. This endpoint is `2.0`. |

***

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| Items | Array | Yes | 1 to 25 items. Each load can appear only once. |

Each item in `Items`:

| Field | Type | Required | Description |
| - | - | - | - |
| LoadNumber | String | Yes | The Alvys load number. |
| Amount | Number | Yes | The flat fuel surcharge, from 0 to 1,000,000, with at most 2 decimal places. |

If any item is incomplete or out of range, the whole request is rejected with `400` and no load is changed. The `400` response names each failing item, for example `Items[2].Amount`.

***

### Example cURL request

```bash theme={null}
curl --location --request PUT 'https://integrations.alvys.com/api/p/v2.0/loads/fuel-surcharges' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Items": [
    { "LoadNumber": "100245", "Amount": 150.25 },
    { "LoadNumber": "100246", "Amount": 98.40 }
  ]
}'
```

Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token.

***

### Response fields

A valid request answers `200` with one result per item in `Results`. Each item is applied on its own, so one failed item does not stop the others.

| Field | Type | Description |
| - | - | - |
| LoadNumber | String | The load number as sent, trimmed. |
| Status | Integer | The outcome for this item. See the table below. |
| Changed | Boolean | `false` when the load already had this amount. |
| FuelSurchargeAmount | Number | The load's fuel surcharge after the call, when `Status` is `200`. |
| Error | String | Why the item was not applied, when `Status` is not `200`. |
| Warning | String | Set on a `200` when the amount was saved but a follow-up step, such as the accounting sync, failed. |

Item `Status` values:

| Status | Meaning |
| - | - |
| 200 | Applied. `Changed` is `false` when the load already had that amount. |
| 403 | The load is Released, Queued, Invoiced, Financed or Completed, and your credential does not have the `invoice:update` scope. |
| 404 | No load with this load number that your credential can access. A trip number also returns `404`. |
| 409 | The load changed while it was being updated. Read it again if you need to, then resend the item. |
| 422 | Alvys rejected the change. `Error` says why. |
| 500 | The update failed. `Error` says when a retry can help. |

### Resending is safe

Sending an item again applies it again, so you can resend any item, or the whole request. Resend the items that came back with `409`, `500`, or a `Warning`.

***

### Example response

```json theme={null}
{
  "Results": [
    {
      "LoadNumber": "100245",
      "Status": 200,
      "Changed": true,
      "FuelSurchargeAmount": 150.25,
      "Error": null,
      "Warning": null
    },
    {
      "LoadNumber": "100246",
      "Status": 404,
      "Changed": false,
      "FuelSurchargeAmount": null,
      "Error": "Load not found.",
      "Warning": null
    }
  ]
}
```

***

### Status codes

| Code | Description |
| - | - |
| 200 | The request was processed. Read each item's `Status` in `Results`. |
| 400 | The request body failed validation, for example more than 25 items, a duplicated load, or a missing amount. |
| 401 | Authentication failed or the token is missing. |
| 403 | The token is not authorized to update loads. |
| 429 | Too many requests. |


## OpenAPI

````yaml PUT /api/p/v{version}/loads/fuel-surcharges
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, and search loads; manage load documents, notes, and custom
      references.
  - name: Locations
    description: Read and search company location details.
  - name: Maintenance
    description: Read and search maintenance records.
  - name: References
    description: >-
      List tenant custom reference definitions and create or update values on
      existing loads, stops, and trips.
  - name: Subsidiaries
    description: >-
      List your company's subsidiaries and read a single subsidiary, so an
      integration can resolve a subsidiary id to a recognizable name.
  - name: Tenders
    description: Create, accept, reject, cancel, update, and search inbound EDI tenders.
  - name: Tolls
    description: Read and search toll transactions.
  - name: Tracking
    description: >-
      Record an asset's current location or telemetry from a third-party source,
      such as an external ELD or a self-reporting vehicle.
  - name: Trailers
    description: Read trailers, search trailer events, and manage trailer documents.
  - name: Trips
    description: >-
      Read and search trips; manage trip documents, stop appointments, arrivals,
      departures, and stop and trip custom references.
  - 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.
  - name: Accessorials
  - name: Credits
paths:
  /api/p/v{version}/loads/fuel-surcharges:
    put:
      tags:
        - Loads
      summary: Update fuel surcharge on loads
      description: >-
        Sets a flat customer fuel surcharge on up to 25 loads. Each load's fuel
        surcharge becomes a manual flat amount — a fuel surcharge contract on
        the load no longer applies — and the load's customer rate is
        recalculated as when the fuel surcharge is edited in Alvys. On a trip
        whose driver, owner-operator or carrier is already paid, the trip
        amounts (trip value, carrier rate, owner-operator rate and trip fuel
        surcharge) are not recalculated. As in the app, an Invoiced, Financed or
        Completed load is refused when a trip's driver or owner-operator is paid
        by percentage and has already been paid. `Amount` is at most 1,000,000.


        Items are applied independently and each gets its own `Status` in the
        response: `200` applied (`Changed` is false when the load already had
        that amount), `403` the load is Released, Queued, Invoiced, Financed or
        Completed, where the app requires billing access, and the client lacks
        the `invoice:update` scope, `404` no such load, `409` the load changed
        during the update, `422` Alvys rejected the change (see `Error`), `500`
        the update failed (`Error` says when a retry can help). A `200` with a
        `Warning` means the amount was saved but a follow-up step, such as the
        accounting sync, failed. Sending an item again re-applies it, so any
        item, or the whole request, can be resent.


        Loads are identified by Alvys load number; a trip number is not
        accepted. To start from order numbers, look the loads up with `POST
        /loads/search` (`OrderNumbers`, `CustomerId`) — an order number can
        match more than one load.


        Once a load's fuel surcharge is set here, a later EDI tender update that
        carries a fuel surcharge cannot change it, as after an edit in Alvys;
        the tender's line haul and the rest of the tender update still apply.
      parameters:
        - name: version
          in: path
          description: API version (e.g., 2.0)
          required: true
          schema:
            type: string
            default: '2.0'
            example: '2.0'
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Loads.LoadFuelSurchargeUpdateRequest
          application/json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Loads.LoadFuelSurchargeUpdateRequest
          text/json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Loads.LoadFuelSurchargeUpdateRequest
          application/*+json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Loads.LoadFuelSurchargeUpdateRequest
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Alvys.Models.Loads.LoadFuelSurchargeUpdateResponse
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
      security:
        - Public: []
components:
  schemas:
    Alvys.Models.Loads.LoadFuelSurchargeUpdateRequest:
      type: object
      properties:
        Items:
          type: array
          items:
            $ref: >-
              #/components/schemas/Alvys.Models.Loads.LoadFuelSurchargeUpdateItem
          nullable: true
      additionalProperties: false
    Alvys.Models.Loads.LoadFuelSurchargeUpdateResponse:
      required:
        - Results
      type: object
      properties:
        Results:
          type: array
          items:
            $ref: >-
              #/components/schemas/Alvys.Models.Loads.LoadFuelSurchargeUpdateResult
      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.Loads.LoadFuelSurchargeUpdateItem:
      type: object
      properties:
        LoadNumber:
          type: string
          nullable: true
        Amount:
          type: number
          format: double
          nullable: true
      additionalProperties: false
    Alvys.Models.Loads.LoadFuelSurchargeUpdateResult:
      required:
        - Changed
        - LoadNumber
        - Status
      type: object
      properties:
        LoadNumber:
          type: string
        Status:
          type: integer
          format: int32
        Changed:
          type: boolean
        FuelSurchargeAmount:
          type: number
          format: double
          nullable: true
        Error:
          type: string
          nullable: true
        Warning:
          type: string
          nullable: true
      additionalProperties: false
  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>`.

````