# Demurrage risk

> The Container Tracking API detects a demurrage risk from container events — the delay between gate in and loading at the port of loading, and between discharge and gate out at the port of discharge — compared with a threshold.

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`](/en/api/container-tracking/reference/get-shipment-detail) 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.

| Port | Delay start                                                       | Delay end                                                      | Fallback when an event is missing        |
| ---- | ----------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------- |
| POL  | Arrival 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 |
| POD  | Discharge 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.

::callout{type="info"}
Always prefer the load and discharge events to compute the time spent in port. Use the vessel departure and arrival dates only when the load or discharge event is unavailable.
::

::callout{type="warning"}
The availability of each event depends on the shipping line. The [Status and event codes](/en/api/container-tracking/guides/status-and-event-codes) page shows which events the major shipping lines provide.
::

## Example

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

```json
{
  "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.

<!-- TODO: review by product team -->
