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 a rates object.
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 endDate field — represents the final calendar day of the free period according to the contract.
Use lastWorkingDate field — represents the last day before endDate that 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