Get Detention and Demurrage Optimization Tracking Updates

Detention and Demurrage Optimization tracking follows the same API endpoints and workflows as standard Ocean Port to Port tracking, with additional enhanced data for import terminals where project44 has data connectivity.

All tracking APIs available for standard ocean shipments work with Detention and Demurrage Optimization. The key difference is the additional terminal events, cost information, and facility details provided for supported import terminals.

API Endpoints

Use the same four targeted endpoints as standard ocean tracking:

Event History - /api/v4/shipments/{shipmentId}/eventhistory - Returns shipment events and milestones
Position History - /api/v4/shipments/{shipmentId}/positionhistory - Returns shipment positions
Route Information - /api/v4/shipments/{shipmentId}/tracking - Returns route segments and stop information
Full Tracking History - /api/v4/shipments/{shipmentId}/tracking/history - Returns all tracking information

Enhanced Terminal Events

For terminals where project44 has data connectivity, you'll receive additional event types specific to detention and demurrage optimization:

Event Type	Description	Description Field
`LAST_FREE_DAY`	The last day that the container can be picked up from the terminal without incurring demurrage charges	`Import Demurrage`
`LAST_FREE_DAY`	The last day that the equipment can be returned to the carrier without incurring detention charges	`Import Detention`
`PICKED_UP`	The pickup-appointment time booked for collecting the container from the terminal	-
`CUSTOMS_HOLD`	The container is being held at the terminal by customs	-
`CARRIER_HOLD`	The container is being held at the terminal by the carrier	-
`HELD`	The container is being held at the terminal by any party other than carrier, customs	-
`CUSTOMS_CLEARANCE`	The container has been released by customs and is available for pickup	-
`RECEIVE_FROM_CARRIER`	The container has been released by the carrier and is available for pickup	-
`AVAILABLE`	The container is available for pickup after being held	-
`CLEAN_TRUCK_FEE_CLEARANCE`	The container has been cleared from clean truck fee requirements and is available for pickup	-
`CLEAN_TRUCK_FEE_HOLD`	The container is being held due to clean truck fee requirements	-
`OTHER_HOLD`	The container is being held for other unspecified reasons	-
`OTHER_HOLD_CLEARANCE`	The container has been cleared from other hold reasons and is available for pickup	-
`TERMINAL_CLEARANCE`	The container has been cleared by the terminal and is available for pickup	-
`TERMINAL_HOLD`	The container is being held at the terminal	-
`TRAFFIC_MITIGATION_FEE_CLEARANCE`	The container has been cleared from traffic mitigation fee requirements and is available for pickup	-
`TRAFFIC_MITIGATION_FEE_HOLD`	The container is being held due to traffic mitigation fee requirements	-

LAST_FREE_DAY is delivered as two separate events distinguished by the description field: Import Demurrage and Import Detention. Each corresponds to one of the two cost types in Cost Information below — the Import Demurrage event maps to the IMPORT_DEMURRAGE cost, and the Import Detention event maps to the IMPORT_DETENTION cost.

The granular hold/clearance event pairs above (CARRIER_HOLD/RECEIVE_FROM_CARRIER, CUSTOMS_HOLD/CUSTOMS_CLEARANCE, CLEAN_TRUCK_FEE_HOLD/CLEAN_TRUCK_FEE_CLEARANCE, TRAFFIC_MITIGATION_FEE_HOLD/TRAFFIC_MITIGATION_FEE_CLEARANCE, TERMINAL_HOLD/TERMINAL_CLEARANCE, OTHER_HOLD/OTHER_HOLD_CLEARANCE) are available only where the terminal reports that level of detail — currently North America and Rotterdam. Everywhere else, only the legacy HELD and AVAILABLE events are sent. A container receives one style or the other, not both.

For complete details on all event types and their descriptions, refer to the Ocean Shipment Schema Events.

Cost Information

The Full Tracking History endpoint includes enhanced cost data in the response:

{
  "costs": [
    {
      "type": "IMPORT_DETENTION",
      "identifiers": [
        {
          "type": "CONTAINER_TYPE",
          "value": "45GP"
        },
        {
          "type": "CONTAINER_ID",
          "value": "MEDU1234567"
        }
      ],
      "totalCost": {
        "currency": "USD",
        "amount": 1000
      },
      "tier": "SECOND_PERIOD"
    },
    {
      "type": "IMPORT_DEMURRAGE",
      "identifiers": [
        {
          "type": "CONTAINER_TYPE",
          "value": "45GP"
        },
        {
          "type": "CONTAINER_ID",
          "value": "MEDU1234567"
        }
      ],
      "totalCost": {
        "currency": "USD",
        "amount": 2000
      },
      "tier": "THEREAFTER_PERIOD"
    }
  ]
}

Cost Fields

Field	Description
`costs.type`	Type of cost: `IMPORT_DEMURRAGE`, `IMPORT_DETENTION`
`costs.totalCost.currency`	Currency: `USD`, `CAD`, `MXN`, `EUR`
`costs.totalCost.amount`	Monetary amount of the cost
`costs.tier`	Cost tier: `FREE_PERIOD`, `FIRST_PERIOD`, `SECOND_PERIOD`, `THEREAFTER_PERIOD`
`costs.identifiers`	Asset identifiers the cost pertains to

Enhanced Terminal Information

Terminal locations include detailed facility information:

Field	Description
`name`	Name of the terminal
`address.postalCode`	Postal code of terminal
`address.addressLines`	Detailed address of terminal
`address.city`	City of terminal
`address.state`	State of terminal
`address.country`	Country of terminal
`identifiers.type`	Location identifier type: `FACILITY_ID`, `PORT_UN_LOCODE`
`identifiers.value`	Value of location identifier

Standard Ocean Milestones

All standard ocean milestones are included, plus enhanced terminal-specific events:

Core Ocean Milestones:

PICKED_UP_AT_ORIGIN
GATE_IN_FULL_AT_PORT_OF_LOADING
LOAD_ONTO_VESSEL_AT_PORT_OF_LOADING
VESSEL_DEPARTURE_FROM_PORT_OF_LOADING
VESSEL_ARRIVAL_AT_PORT_OF_DISCHARGE
DISCHARGE_FROM_VESSEL_AT_PORT_OF_DISCHARGE
GATE_OUT_FULL_AT_PORT_OF_DISCHARGE
GATE_IN_EMPTY_CONTAINER_AT_TERMINAL

Enhanced Detention and Demurrage Milestones (for supported terminals):

Terminal hold and release events
Cost calculation updates
Last free day notifications
Customs and carrier status changes

Example: Get Full Tracking History

GET /api/v4/shipments/cfa01403-d76d-4e01-a551-17589083d7d7/tracking/history

The response includes all standard ocean tracking data plus enhanced terminal information and cost data for supported import terminals.

Asynchronous Processing

Like standard ocean tracking, Detention and Demurrage optimization data is processed asynchronously. Enhanced terminal information appears as containers reach terminals where project44 has data connectivity.

Error Handling

Error handling follows the same pattern as standard ocean shipments:

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

See Error Response Codes for more information.

For complete API documentation and workflows, refer to the Ocean Port to Port tracking guide. All endpoints and methods apply to Detention and Demurrage Optimization with the additional enhanced data described above.