Skip to content
Documentation sections

Demurrage risk

Demurrage fees are charged when a container stays in a port longer than the free time allotted by the carrier or the port authority. Detecting the risk early lets the owner of the shipment adapt the schedule and pay fewer fees. A single call to the Container Tracking API endpoint GET /shipment returns the container events this detection needs.

When demurrage fees are charged

Demurrage fees can be charged in two situations:

  • at the port of loading (POL), when the container has arrived at the terminal and has not been loaded on a vessel yet;
  • at the port of discharge (POD), when the container has been discharged from the vessel and has not left the port yet.

Detection logic

A demurrage risk is detected by measuring, at each port, the delay between two events of the container, and by raising an alert when that delay exceeds a threshold you choose.

PortDelay startDelay endFallback when an event is missing
POLArrival of the container at the terminal: status CGI (gate in)Load of the container on the vessel: status CLL (loaded)Vessel departure from the POL (VDL) instead of the load
PODDischarge of the container from the vessel: status CDD (discharged)Departure of the container from the port: status CGO (gate out)Vessel arrival at the POD (VAD) instead of the discharge

Apply it to the events of each container, in containers[].events of the response:

  1. At the POL, find the event with status CGI and the event with status CLL. When the CLL event is missing, use the vessel departure date instead.
  2. At the POD, find the event with status CDD and the event with status CGO. When the CDD event is missing, use the vessel arrival date instead.
  3. Compute the delay between the two dates of each port.
  4. Compare each delay with your threshold, and raise an alert when it is exceeded.
  5. When the event that ends the delay is still missing — the container has not been loaded, or has not left the port — the delay cannot be computed yet. Keep updating the shipment: shipping lines add events regularly.

Example

The response below, shortened to the container events, tracks a container loaded at Melbourne (AUMEL) and bound for Colombo (LKCMB):

{
  "containers": [
    {
      "status": "IN_TRANSIT",
      "events": [
        {
          "location": { "name": "MELBOURNE", "locode": "AUMEL" },
          "description": "Gate in at Port terminal",
          "eventType": "EQUIPMENT",
          "eventCode": "GTIN",
          "status": "CGI",
          "date": "2024-05-29T07:34:00Z",
          "isActual": true
        },
        {
          "location": { "name": "MELBOURNE", "locode": "AUMEL" },
          "description": "Loaded on board",
          "eventType": "EQUIPMENT",
          "eventCode": "LOAD",
          "status": "CLL",
          "date": "2024-06-02T03:51:00Z",
          "isActual": true
        },
        {
          "location": { "name": "COLOMBO", "locode": "LKCMB" },
          "description": "Vessel Arrival",
          "eventType": "TRANSPORT",
          "eventCode": "ARRI",
          "status": "VAD",
          "date": "2024-07-06T13:30:00Z",
          "isActual": false
        }
      ]
    }
  ]
}

Detection at the port of loading

  • The container has both a CGI event (gate in) and a CLL event (loaded) at Melbourne.
  • The CGI date is 2024-05-29T07:34:00Z, the CLL date is 2024-06-02T03:51:00Z.
  • The time spent at the port of loading is 3 days, 20 hours and 17 minutes.

Compare that time with your threshold to decide whether to send an alert.

Detection at the port of discharge

  • The container has only a VAD event (vessel arrival) at Colombo, estimated, and no CGO event (gate out).
  • The demurrage risk cannot be computed at the port of discharge yet.

Keep updating the data of this shipment: the shipping line adds events as the voyage progresses.