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
The shipping journey is divided into three main rate pillars: Origin, Freight, and Destination.
Support of the Origin and Freight rates will be added in a future version of the API. The current version provides full support of Destination-related charges only.
Each shipment’s fees are calculated separately for the buy side (fees paid to carriers) and the sell side (fees charged to customers).
Currently supported Destination Fee Types:
- Demurrage: Charges for container storage at the terminal beyond free days
- Detention: Charges 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 storing containers under their control, typically within port premises or inland depots
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"]
}
]
}How to Determine the Last Free Day
In the response, the first paymentTier always represents the free period, during which no charges apply.
For example:
"sell": {
"fees": [
{
"paymentTiers": [
{
"numberOfDays": 7,
"costPerDay": 0,
"startDate": "2024-12-20T00:00:00.000Z",
"endDate": "2024-12-26T00:00:00.000Z",
"lastWorkingDate": "2024-12-26T00:00:00.000Z",
"actual": {
"startDate": "2024-12-20T00:00:00.000Z",
"endDate": "2024-12-26T00:00:00.000Z",
"totalDays": 7,
"billableDays": 7,
"totalCharges": 0
}To determine the last free day:
- Use the
endDatefield — represents the final calendar day of the free period according to the contract. - Use
lastWorkingDatefield — represents the last day beforeendDatethat is not a weekend or holiday, based on the shipment’s POD (Port of Discharge) calendar.
These two fields may differ when the endDate falls on a non-working day.
The nested actual object shows what actually happened — the real dates and usage for this shipment based on shipment events and tracking.
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 |
Buy/Sell Response Codes
| Code | Description |
|---|---|
OK | Calculation completed successfully for this side |
MULTI_CURRENCY | Fee calculation could not be completed because the fees contain multiple currencies |
Mapping Errors
These errors occur when the system fails to map the shipment to a valid contract or tariff due to missing or mismatched data:
Missing Fields
| Code | Description |
|---|---|
MISSING_SHIPMENT_DETAILS | Shipment details are missing |
MISSING_ORGANIZATION_ID | Organization ID is missing |
MISSING_POD | Port of discharge is missing |
MISSING_POL | Port of loading is missing |
MISSING_ISO_CODE | Container ISO code is missing |
No Tariffs Found
| Code | Description |
|---|---|
NO_TARIFFS_FOUND | No tariffs found for this side |
Contract ID Errors
| Code | Description |
|---|---|
NO_BUY_CONTRACT_ID_NO_STANDARD | No buy contract ID provided and no standard tariff found |
NO_STANDARD_TARIFFS_FOR_SCAC | No standard tariffs found for this SCAC (carrier code) |
NO_MATCHING_CONTRACT_ID | Provided contract ID could not be matched |
NO_SELL_CONTRACT_ID | No sell contract ID provided |
Field Matching Errors
| Code | Description |
|---|---|
NO_MATCHING_FIELDS | No matching fields found in tariff |
NO_MATCHING_FIELDS_STANDARD | No matching fields found in standard tariff |
Validity Event Errors
| Code | Description |
|---|---|
OUTSIDE_VALIDITY_RANGE | Shipment is outside of the validity range for this contract |
OUTSIDE_VALIDITY_RANGE_STANDARD | Shipment is outside of the validity range for standard tariff |
NO_VALIDITY_EVENT | No validity event was found for this contract |
NO_VALIDITY_EVENT_STANDARD | No validity event was found for the standard tariff |