Overview
The Detention and Demurrage Fees API is designed to provide you with a breakdown of operational fees for international ocean shipments. It supports advanced tariff calculations, fee modeling, and clear visibility into cost components, currently focusing on Detention and Demurrage (D&D) fees at the Destination stage. Future versions will include a broader fee support across the Origin, Freight, and Destination legs of a shipment.
API Response Structure
Top-level Response Object
The API response is organized as follows:
- Each response includes a list of
trackedShipments, while each shipment contains aratesobject. - Shipment’s rates contain a breakdown by Origin, Freight, and Destination.
- Fees are organized by buy and sell sides, with associated contract IDs, fees, currencies, and billable day structures.
Rate Structure
A rate includes fees of the the following three types that correspond to a shipment journey legs:
- Origin (to be implemented in a future version)
- Freight (to be implemented in a future version)
- Destination
The following Destination fee sub-types are currently supported:
- Demurrage: Fees for container storage at the terminal beyond free days
- Detention: Fees for holding containers outside the terminal after pickup and before return
- Combined: A merged fee covering both demurrage and detention under a single structure
- Carrier storage: Fees charged by the carrier for container storage, usually at port facilities or inland depots
Buy and Sell
- Buy: What the forwarder pays to the carrier
- Sell: What the forwarder charges the customer. Sell calculations are optional and may return null if the contract data is missing or not configured.
Request Example
query TrackedShipments($filterBy: [FilterByInput!]) {
trackedShipments(filterBy: $filterBy) {
data {
shipment {
rates {
destination {
dnd {
total
currency
response {
code
message
}
buy {
contractId
currency
response {
code
message
}
totalFees
fees {
... on DndFeeDetails {
feeType
daysCalculation {
description
}
totalCharges
currency
billableDays
paymentTiers {
numberOfDays
costPerDay
startDate
endDate
lastWorkingDate
actual {
startDate
endDate
totalDays
billableDays
totalCharges
}
}
}
}
}
sell {
contractId
currency
totalFees
fees {
... on DndFeeDetails {
feeType
daysCalculation {
description
}
totalCharges
currency
billableDays
paymentTiers {
numberOfDays
costPerDay
startDate
endDate
lastWorkingDate
actual {
startDate
endDate
totalDays
billableDays
totalCharges
}
}
}
}
response {
code
message
}
}
}
}
}
}
}
}
}GraphQL Variables
{
"filterBy": [
{
"field": "shipment_id",
"values": ["Add Shipment ID here"]
}
]
}Fee Object Structure
Each fee object, under either buy or sell, includes:
| Field | Description |
|---|---|
feeType | Type of fee (demurrage, detention, etc.) |
daysCalculation | Logic for calculating days (e.g., calendar vs. working days) |
totalCharges | Calculated monetary value for the fee |
billableDays | Number of billable days based on the tariff |
currency | ISO currency code |
paymentTiers | Breakdown of charges by day ranges or rate brackets |
actual | Actual dates the fee applied (with startDate, endDate, totalDays, and billableDays) |
tariffId | Internal reference to the applied tariff |
mappingId | Identifier linking to internal mapping logic or external rules |
Error Handling
These errors occur when the system fails to map the shipment to a valid contract or tariff due to missing or mismatched data:
| Error Name | Description |
|---|---|
MISSING_SHIPMENT_DETAILS | Required shipment data (e.g., dates, locations) is missing or incomplete |
MISSING_ORGANIZATION_ID | The shipment is not associated with a valid organization ID |
MISSING_POD | Port of discharge (POD) is missing from the shipment details |
MISSING_POL | Port of loading (POL) is missing from the shipment details |
MISSING_ISO_CODE | Container type (ISO code) is missing and is required for tariff matching |
NO_TARIFFS_FOUND | No tariffs are available that match the shipment criteria |
NO_BUY_CONTRACT_ID_NO_STANDARD | No buy contract ID was provided, and no matching standard tariff was found |
NO_SELL_CONTRACT_ID | No sell contract ID was provided for the shipment |
NO_MATCHING_FIELDS_STANDARD | None of the standard tariff rules matched the shipment fields |
OUTSIDE_VALIDITY_RANGE_STANDARD | Shipment falls outside the validity period of any matching standard tariff |
NO_STANDARD_TARIFFS_FOR_SCAC | No standard tariffs were found for the carrier (SCAC code) |
NO_VALIDITY_EVENT_STANDARD | Standard tariff validity could not be determined due to missing or invalid event dates |
NO_MATCHING_CONTRACT_ID | A contract ID was provided, but no matching contract was found |
NO_MATCHING_FIELDS | The contract was found, but its conditions do not match the shipment details |
OUTSIDE_VALIDITY_RANGE | The contract exists but is not valid for the shipment’s dates |
NO_VALIDITY_EVENT | Required event dates (e.g., gate-in, discharge) are missing, so contract validity cannot be checked |
Fee Calculation Response Codes
These response codes indicate the status of the fee calculation process for the buy and sell sides, and help identify missing or inconsistent data affecting the results:
| Status Code | Description |
|---|---|
OK | The fee calculation completed successfully with all required data. |
MULTI_CURRENCY | Fee calculation could not be completed because buy and sell fees use different currencies. |
MISSING_FEES | Both buy and sell fee data are missing, so no calculation can be performed. |
MISSING_BUY_FEES | Buy-side fee data is missing, preventing accurate cost or profit calculation. |
MISSING_SELL_FEES | Sell-side fee data is missing, so profit and loss cannot be determined. |