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

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
                    mappingId
                    daysCalculation {
                      code
                      description
                    }
                    totalCharges
                    currency
                    billableDays
                    paymentTiers {
                      numberOfDays
                      costPerDay
                      actual {
                        startDate
                        endDate
                        totalDays
                        billableDays
                        totalCharges
                      }
                    }
                  }
                }
              }
              sell {
                contractId
                currency
                totalFees
                fees {
                  ... on DndFeeDetails {
                    feeType
                    mappingId
                    daysCalculation {
                      code
                      description
                    }
                    totalCharges
                    currency
                    billableDays
                    paymentTiers {
                      numberOfDays
                      costPerDay
                      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.