Delivery Updated
The DELIVERY_UPDATED callback is triggered whenever an existing delivery in FourKites is modified — including changes to ETA, status, stop details, or associated order and shipment information. Use this callback to keep your downstream systems in sync with the latest delivery state in real time.
The payload structure is identical to DELIVERY_CREATED. Compare deliveryDestinationETA against deliveryPreviousDestinationETA to detect ETA changes, and check deliveryETAStatus to determine whether the delivery is on time or late.
Request Parameter
{
"messageType": "DELIVERY_UPDATED",
"companyPermalink": "string",
"fourKitesOrderId": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2025-01-15T10:30:45.123456789Z",
"uuid": "string",
"subStatusType": "delivery",
"subStatus": "string",
"eventTimestamp": "2025-01-15T10:30:45.123456789Z",
"timezone": "Coordinated Universal Time",
"timezoneShortName": "UTC",
"timezoneOffset": 0,
"isSuccess": true,
"updatedAt": "2025-01-15T10:30:45.123456789Z",
"requestId": "string",
"deliveryDetails": {
"deliveryIdentifier": "string",
"status": "string",
"shipmentNumber": "string",
"type": "INBOUND",
"eventTime": "2025-01-15T10:30:45.123456789Z",
"deliveryDestination": [
{
"gln": "string",
"organisationName": "string",
"name": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string"
}
],
"deliveryOrigin": [
{
"gln": "string",
"organisationName": "string",
"name": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"state": "string",
"country": "string",
"zip": "string"
}
],
"deliveryDestinationETA": "2025-01-16T10:30:45.123456789Z",
"deliveryPreviousDestinationETA": "2025-01-15T10:30:45.123456789Z",
"deliveryETAStatus": "LATE",
"deliveryAdditionalInfo": [
{
"avpList": {
"customKey": "customValue"
}
}
],
"orderNumbers": ["ORD001"],
"shipmentNumbers": ["SHIP001"],
"trackingNumbers": [12345],
"orderAttributes": [
{
"OrderNumber": "ORD001",
"OrderAdditionalInfo": {
"customKey": "customValue"
},
"OrderLines": [
{
"LineItemNumber": "1",
"ProductSKU": "SKU001",
"ProductID": "PROD001",
"Upc": "123456789012",
"Gtin": "1234567890123",
"LineStatus": "in_transit",
"LineAdditionalInfo": {
"customKey": "customValue"
}
}
]
}
],
"shipmentAttributes": [
{
"ShipmentId": "123",
"CarrierId": "CARRIER001",
"ShipmentNumber": "SHIP001",
"Mode": "TL",
"Scac": "ABCD",
"CarrierName": "Carrier Name",
"MasterReferenceNumber": "MRN001",
"MasterSequenceNumber": 1,
"ShipmentAdditionalInfo": [
{
"StopName": "Destination DC",
"StopReferenceId": "STOP002",
"StopType": "DELIVERY",
"Timezone": "America/New_York",
"Eta": "2025-01-16T10:30:45.123456789Z",
"LoadETAStatus": "LATE",
"LoadETAStatusUsingWantTime": "LATE",
"AppointmentTime": "2025-01-15T14:00:00.000Z",
"WantTime": "2025-01-15T14:00:00.000Z",
"ArrivedAt": null,
"DepartedAt": null,
"Status": "in_transit",
"StopReferenceNumbers": ["REF003"],
"TransportationMode": "TL",
"OrderNumbers": ["ORD001"],
"LocationId": "LOC002",
"Name": "Destination DC",
"City": "New York",
"State": "NY",
"Country": "US",
"Address": "456 Broadway",
"Zip": "10001"
}
]
}
]
}
}Field Descriptions
Top-Level Fields
Field Name | Description | Key Always Present? | Value Always Present? | Data Type | Max Length |
|---|---|---|---|---|---|
messageType | The type of callback message (e.g., DELIVERY_UPDATED) | Yes | Yes | String | No Max |
companyPermalink | The unique permalink identifier for the company | Yes | Yes | String | No Max |
fourKitesOrderId | The unique FourKites-generated UUID for the order | Yes | Yes | String (UUID) | No Max |
createdAt | The timestamp when the callback was generated | Yes | Yes | Timestamp | No Max |
uuid | Unique ID for the callback | Yes | Yes | String | No Max |
subStatusType | The category of the sub-status (e.g., delivery) | Yes | No | String | No Max |
subStatus | The sub-status value | Yes | No | String | No Max |
eventTimestamp | The timestamp of the triggering event | Yes | Yes | Timestamp | No Max |
timezone | Full timezone name (e.g., Coordinated Universal Time) | Yes | No | String | No Max |
timezoneShortName | Abbreviated timezone name (e.g., UTC) | Yes | No | String | No Max |
timezoneOffset | UTC offset in hours | Yes | No | Integer | No Max |
isSuccess | Indicates if the event was processed successfully | Yes | Yes | Boolean | — |
updatedAt | Timestamp of the last update to the callback | Yes | Yes | Timestamp | No Max |
requestId | Unique identifier for the API request | Yes | No | String | No Max |
deliveryDetails | Object containing full delivery details | Yes | No | Object | No Max |
deliveryDetails Object
Field Name | Description | Key Always Present? | Value Always Present? | Data Type | Max Length |
|---|---|---|---|---|---|
deliveryIdentifier | Unique identifier for the delivery | Yes | Yes | String | No Max |
status | Current status of the delivery | Yes | Yes | String | No Max |
shipmentNumber | Shipment number associated with the delivery | Yes | No | String | No Max |
type | Direction of the delivery (e.g., INBOUND, OUTBOUND) | Yes | No | String | No Max |
eventTime | Timestamp of the delivery event | Yes | No | Timestamp | No Max |
deliveryDestination | List of destination location details for the delivery | Yes | No | Array[Object] | No Max |
deliveryOrigin | List of origin location details for the delivery | Yes | No | Array[Object] | No Max |
deliveryDestinationETA | Estimated arrival time at the delivery destination | Yes | No | Timestamp | No Max |
deliveryPreviousDestinationETA | Previous ETA at the delivery destination before any revision | Yes | No | Timestamp | No Max |
deliveryETAStatus | ETA status for the delivery (e.g., ON_TIME, LATE) | Yes | No | String | No Max |
deliveryAdditionalInfo | Custom key-value attribute pairs for the delivery | Yes | No | Array[Object] | No Max |
orderNumbers | List of order numbers associated with the delivery | Yes | No | Array[String] | No Max |
shipmentNumbers | List of shipment numbers associated with the delivery | Yes | No | Array[String] | No Max |
trackingNumbers | List of tracking numbers associated with the delivery | Yes | No | Array[Integer] | No Max |
orderAttributes | List of order-level attributes including line item details | Yes | No | Array[Object] | No Max |
shipmentAttributes | List of shipment-level attributes including stop details | Yes | No | Array[Object] | No Max |
Location Object Fields
Applies to: deliveryDestination, deliveryOrigin
Field Name | Description | Key Always Present? | Value Always Present? | Data Type | Max Length |
|---|---|---|---|---|---|
gln | Global Location Number | Yes | No | String | No Max |
organisationName | Name of the organization | Yes | No | String | No Max |
name | Name of the location | Yes | No | String | No Max |
addressLine1 | Primary street address | Yes | No | String | No Max |
addressLine2 | Secondary address line | Yes | No | String | No Max |
city | City | Yes | No | String | No Max |
state | State or province | Yes | No | String | No Max |
country | Country | Yes | No | String | No Max |
zip | Postal or ZIP code | Yes | No | String | No Max |
orderAttributes Array
Field Name | Description | Key Always Present? | Value Always Present? | Data Type | Max Length |
|---|---|---|---|---|---|
OrderNumber | Order number associated with the delivery | Yes | No | String | No Max |
OrderAdditionalInfo | Custom key-value attribute pairs for the order | Yes | No | Object | No Max |
OrderLines | List of order line items associated with the delivery | Yes | No | Array[Object] | No Max |
OrderLines.LineItemNumber | Line item number | Yes | No | String | No Max |
OrderLines.ProductSKU | SKU of the product | Yes | No | String | No Max |
OrderLines.ProductID | Unique product identifier | Yes | No | String | No Max |
OrderLines.Upc | Universal Product Code | Yes | No | String | No Max |
OrderLines.Gtin | Global Trade Item Number | Yes | No | String | No Max |
OrderLines.LineStatus | Current status of the line item | Yes | No | String | No Max |
OrderLines.LineAdditionalInfo | Custom key-value attribute pairs for the line item | Yes | No | Object | No Max |
shipmentAttributes Array
Field Name | Description | Key Always Present? | Value Always Present? | Data Type | Max Length |
|---|---|---|---|---|---|
ShipmentId | Unique identifier for the shipment | Yes | Yes | String | No Max |
CarrierId | Unique identifier for the carrier | Yes | No | String | No Max |
ShipmentNumber | Shipment number | Yes | No | String | No Max |
Mode | Transportation mode (e.g., TL, LTL) | Yes | No | String | No Max |
Scac | Standard Carrier Alpha Code for the carrier | Yes | No | String | No Max |
CarrierName | Name of the carrier | Yes | No | String | No Max |
MasterReferenceNumber | Master reference number for the shipment | Yes | No | String | No Max |
MasterSequenceNumber | Master sequence number for the shipment | Yes | No | Integer | No Max |
ShipmentAdditionalInfo | List of stop-level details for the shipment | Yes | No | Array[Object] | No Max |
shipmentAttributes.ShipmentAdditionalInfo — Per Stop Fields
Field Name | Description | Key Always Present? | Value Always Present? | Data Type | Max Length |
|---|---|---|---|---|---|
StopName | Name of the stop location | Yes | No | String | No Max |
StopReferenceId | Reference identifier for the stop | Yes | No | String | No Max |
StopType | Type of stop (e.g., PICKUP, DELIVERY) | Yes | No | String | No Max |
Timezone | Timezone for the stop (e.g., America/Chicago) | Yes | No | String | No Max |
Eta | Estimated time of arrival at the stop | Yes | No | Timestamp | No Max |
LoadETAStatus | ETA status based on scheduled time (e.g., ON_TIME, LATE) | Yes | No | String | No Max |
LoadETAStatusUsingWantTime | ETA status based on want time (e.g., ON_TIME, LATE) | Yes | No | String | No Max |
AppointmentTime | Scheduled appointment time at the stop | Yes | No | Timestamp | No Max |
WantTime | Requested arrival time at the stop | Yes | No | Timestamp | No Max |
ArrivedAt | Actual arrival timestamp at the stop | Yes | No | Timestamp | No Max |
DepartedAt | Actual departure timestamp from the stop | Yes | No | Timestamp | No Max |
Status | Current status of the stop (e.g., completed) | Yes | No | String | No Max |
StopReferenceNumbers | List of reference numbers for the stop | Yes | No | Array[String] | No Max |
TransportationMode | Transportation mode for the stop (e.g., TL) | Yes | No | String | No Max |
OrderNumbers | List of order numbers associated with the stop | Yes | No | Array[String] | No Max |
LocationId | Unique identifier for the stop location | Yes | No | String | No Max |
Name | Name of the stop location | Yes | No | String | No Max |
City | City of the stop location | Yes | No | String | No Max |
State | State of the stop location | Yes | No | String | No Max |
Country | Country of the stop location | Yes | No | String | No Max |
Address | Street address of the stop location | Yes | No | String | No Max |
Zip | Postal or ZIP code of the stop location | Yes | No | String | No Max |