D&D Calculation Status

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 a rates object.
  • 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 dnd as null.

Status Codes

Status CodeDescription
DND_EMPTYNo READY contract mappings
DND_IN_PROGRESSMapped, some fees not calculated yet, shipment still active
DND_INCOMPLETEMapped, some fees not calculated, shipment no longer active
DND_CALCULATEDEvery mapped fee is calculated

Status Fields

FieldDescription
codeThe current status code
previousCodeThe status before the last change. Can be null
readyMappingsNumber of READY contract mappings for the shipment
calculatedFeesNumber of calculated fees linked to those mappings
ratioreadyMappings:calculatedFees, for example 3:3
changedAtTimestamp (UTC) of when the status code last changed
lastChangedAtTimestamp (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, reasonSourceWhat 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 fieldValues
SHIPMENT_DND_CALCULATION_STATUS_CODEOne or more status codes, for example ["DND_CALCULATED"]
SHIPMENT_DND_CALCULATION_STATUS_LAST_CHANGED_ATA date range, for example [{ "gte": "2026-10-29T00:00:00Z" }]
SHIPMENT_DND_CALCULATION_STATUS_CHANGED_ATA 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 lastChangedAt on 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.