Introduction

Update the carrier appointment window for a Truckload shipment. The carrier appointment window will be displayed separately in the Movement UI and will not override the customer appointment window.

Update Appointment Window

Update the appointment window for all stops in a Truckload shipment. The carrier appointment window will be shown separately from the customer appointment window in the UI.

Requirements

Have the following information:

Carrier ID: SCAC, DOT_NUMBER, MC_NUMBER, or P44_EU
Shipment ID: BILL_OF_LADING or ORDER
Position Latitude & Longitude (send 0 if you are not providing a position update)
UTC Timestamp
Shipment Stop Number(s) and Appointment Window Start and End Times for each stop

The CARRIER_SHIPMENT_UPDATE_APPOINTMENT_WINDOW flag must be enabled for both the Customer Tenant and the Carrier Tenant before you can update appointment windows.

Workflow

Complete these steps:

Prepare a POST request to /api/v4/capacityproviders/tl/shipments/statusUpdates.
Enter the required appointment window information in the request schema. For example,

JSON

{
    "carrierIdentifier": {
        "type": "SCAC",
        "value": "P444"
    },
    "shipmentIdentifiers": [
        {
            "type": "BILL_OF_LADING",
            "value": "test-123"
        }
    ],
    "latitude": 0,
    "longitude": 0,
    "utcTimestamp": "2024-11-29T04:03:30",
    "shipmentStops": [
      {
        "stopNumber": 1,
        "appointmentWindow": {
            "startDateTime": "2024-11-29T20:30:00",
            "endDateTime": "2024-11-29T21:30:00"
        }
      },
      {
        "stopNumber": 2,
        "appointmentWindow": {
            "startDateTime": "2024-11-30T06:30:00",
            "endDateTime": "2024-11-30T07:30:00"
        }
      }
    ]
}

The number of stops in the request must match the number of stops in the shipment. You must include appointment window information for all stops in the shipment.

Send the request.

Expected Response

The request is successfully submitted and confirmed when a 202 Accepted response is received.

Errors

If there was a problem with your request, you will receive one of the following error codes:

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Fields & Objects

The table below describes only the minimum relevant fields necessary for updating the appointment window. These are also the same fields returned in the API Response 202 Accepted.

Field	Description
`carrierIdentifier`	This object contains your carrier identifier information.
`carrierIdentifier.type`	The carrier identifier type. Valid values include `SCAC`, `DOT_NUMBER`, `MC_NUMBER`, and `P44_EU`.
`carrierIdentifier.value`	The carrier identifier value.
`shipmentIdentifiers`	The identifiers for the shipment.
`shipmentIdentifiers.type`	The type of the shipment identifier. Valid values include `ORDER` or `BILL_OF_LADING`.
`shipmentIdentifiers.value`	The value of the shipment identifier.
`latitude`	Send `0` if you are not providing a position update, or your vehicle's current latitude in decimal degrees.
`longitude`	Send `0` if you are not providing a position update, or your vehicle's current longitude in decimal degrees.
`utcTimestamp`	The UTC time of the update formatted `yyyy-MM-dd'T'HH:mm:ss`. Local time must be converted to UTC.
`shipmentStops`	This array includes information for each shipment stop where you want to update the appointment window. The number of stops in this array must match the number of stops in the shipment.
`shipmentStops.stopNumber`	The number of the shipment stop.
`shipmentStops.appointmentWindow`	The appointment window start and end dates and times for the stop.
`shipmentStops.appointmentWindow.startDateTime`	When the appointment window starts formatted `yyyy-MM-dd'T'HH:mm:ss`.
`shipmentStops.appointmentWindow.endDateTime`	When the appointment window ends formatted `yyyy-MM-dd'T'HH:mm:ss`.

The carrier appointment window will be displayed separately in the UI and will not override the customer appointment window. Both appointment windows will be visible to users.