Free time

Get the demurrage and detention clocks of a shipment

Use this to answer "how many free days are left on this shipment" or "what will demurrage cost us". Returns one demurrage clock and one detention clock per container, plus the clock that matters most right now (active_clock). Clocks only exist for ocean shipments, for each container that has loading, discharge, gate-out or empty-return events, and stay not_started until the container is discharged; for any other shipment the clock lists are empty and active_clock is null. Free days come from the shipment itself, the latest arrival notice, or the organization's carrier terms, in that order (see free_days_source).

get/shipments/{shipment_id}/free_time

Request

  • Base URL: https://trackberry.com/api/v1
  • URL: https://trackberry.com/api/v1/shipments/{shipment_id}/free_time
  • Auth: HTTP bearer

Path parameters

shipment_idstring required

The shipment id (shp_ prefix). An id from another organization, or with another prefix, is a 404.

Headers

Trackberry-Versionstring

The API version to build this response for, for example 2026-10-01. Optional: without it the organization's pinned version is used (and the organization is pinned to the latest version on its first request without the header). Applies to this request only. An unpublished version is a 400 with code invalid_version.

Response

The free-time summary of the shipment.

object'free_time_summary' required

Always free_time_summary.

shipment_idstring required

The shipment id.

shipment_referencestring required

The shipment's Trackberry reference.

transport_referencestring nullable required

The shipment's bill of lading, air waybill or container number.

at_riskboolean required

True when the demurrage clock is running with known free days and 2 days or fewer are left (or it is already overdue). Shipments with unknown terms are never at risk.

terms_unknownboolean required

True when the free days for demurrage or detention are not known, meaning neither the shipment, an arrival notice nor the organization's carrier terms supply them. Set the terms in Trackberry to get countdowns.

Changes

No recorded changes to this operation across all 1 revision of this API.