Overview
The D&D calculation status shows how complete the Detention and Demurrage (D&D) fees of a tracked shipment are. It is calculated per shipment from its contract mappings and calculated fees, and you can filter on it, so you can fetch only the shipments whose D&D data changed since your last request.
For the fee breakdown itself, see the D&D Fees API.
API Response Structure
Top-level Response Object
- Each response includes a list of
trackedShipments, while each shipment contains aratesobject. - The status is under
shipment.rates.destination.dnd.calculationStatus. There is one status per shipment, covering both the buy and sell sides. - Shipments with no D&D data return
dndas null.
Status Codes
| Status Code | Description |
|---|---|
DND_EMPTY | No READY contract mappings |
DND_IN_PROGRESS | Mapped, some fees not calculated yet, shipment still active |
DND_INCOMPLETE | Mapped, some fees not calculated, shipment no longer active |
DND_CALCULATED | Every mapped fee is calculated |
Status Fields
| Field | Description |
|---|---|
code | The current status code |
previousCode | The status before the last change. Can be null |
readyMappings | Number of READY contract mappings for the shipment |
calculatedFees | Number of calculated fees linked to those mappings |
ratio | readyMappings:calculatedFees, for example 3:3 |
changedAt | Timestamp (UTC) of when the status code last changed |
lastChangedAt | Timestamp (UTC) of when anything in the status last changed: the code, the mapping or fee counts, or a recalculated fee amount. Use it to filter and poll for changes |
lastChangeReason, reason, reasonSource | What triggered the last status update (for example a mapping change on the shipment, a fee event or a shipment status change), and which part of the system raised it: `MAPPING`, `FEE` or `SHIPMENT`. The list of reasons can grow, so treat `reason` as text and do not rely on a fixed set. `reasonSource` can be null |
Request Example
The query below returns shipments whose fees are calculated and that changed since a given time.
query DndCalculatedSince($limit: PositiveInt!, $offset: NonNegativeInt!, $filterBy: [FilterByInput!]) {
trackedShipments(limit: $limit, offset: $offset, includeDnd: true, filterBy: $filterBy) {
totalFiltered
data {
shipment {
id
rates {
destination {
dnd {
calculationStatus {
code
previousCode
readyMappings
calculatedFees
ratio
lastChangedAt
}
}
}
}
}
}
}
}
Use shipment { id } in your selection, not shipmentId.
GraphQL Variables
{
"limit": 100,
"offset": 0,
"filterBy": [
{ "field": "SHIPMENT_DND_CALCULATION_STATUS_CODE", "values": ["DND_CALCULATED"] },
{ "field": "SHIPMENT_DND_CALCULATION_STATUS_LAST_CHANGED_AT", "ranges": [{ "gte": "2026-10-29T00:00:00Z" }] }
]
}
Filter Fields
| Filter field | Values |
|---|---|
SHIPMENT_DND_CALCULATION_STATUS_CODE | One or more status codes, for example ["DND_CALCULATED"] |
SHIPMENT_DND_CALCULATION_STATUS_LAST_CHANGED_AT | A date range, for example [{ "gte": "2026-10-29T00:00:00Z" }] |
SHIPMENT_DND_CALCULATION_STATUS_CHANGED_AT | A date range on changedAt, for example [{ "gte": "2026-10-29T00:00:00Z" }] |
How to Fetch Only Shipments That Changed
First sync. Paging with offset and limit stops at 100,000 results (offset + limit), so a first request that matches more than that cannot be paged to the end. Slice by SHIPMENT_DND_CALCULATION_STATUS_LAST_CHANGED_AT (for example one month per slice) and page within each slice.
After that, poll for changes.
- Filter on the status code you care about and on
lastChangedAton or after your last poll time minus 10 minutes. - De-duplicate on shipment ID +
lastChangedAt, because the overlap returns some shipments twice. - Re-read the latest
lastChangedAt. After a recalculation a shipment can pass through several codes within seconds. - All three filter fields can also be used for sorting.
