--- title: "Get the demurrage and detention clocks of a shipment" method: GET path: "/shipments/{shipment_id}/free_time" tags: ["Free time"] --- # Get the demurrage and detention clocks of a shipment `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 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`). ## Path parameters - `shipment_id` string, required ## Headers - `Trackberry-Version` string ## Response `200` The free-time summary of the shipment. - FreeTimeSummary: The demurrage and detention position of one shipment. Demurrage is the charge for leaving a container at the terminal past its free days; detention is the charge for keeping the empty container past its free days. Only ocean shipments have clocks. - `object` 'free_time_summary', required: Always `free_time_summary`. - `shipment_id` string, required: The shipment id. - `shipment_reference` string, required: The shipment's Trackberry reference. - `transport_reference` string, nullable, required: The shipment's bill of lading, air waybill or container number. - `at_risk` boolean, 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_unknown` boolean, 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. - `demurrage` FreeTimeClock[], required: One demurrage clock per container. Empty for shipments that are not ocean or have no tracking events for it. - `object` 'free_time_clock', required: Always `free_time_clock`. - `kind` 'demurrage' | 'detention', required: Which charge this clock measures. - `container_number` string, nullable, required: The container the clock is for. Null when tracking events carry no container number. - `state` 'not_started' | 'running' | 'running_unknown_terms' | 'stopped' | 'end_not_reported' | 'return_not_reported', required: `not_started` means the clock has nothing to count from yet; `running` means it is counting against known free days; `running_unknown_terms` means it is counting but the free days are unknown (only `elapsed_days` is filled); `stopped` means it has ended (see `ended_on`, `used_days`, `overdue_days`); `end_not_reported` (demurrage) and `return_not_reported` (detention) mean the clock gave up waiting for the ending event because the container was archived or received in the warehouse, or 30 days passed without it. - `free_days` integer, nullable, required: The number of free days that apply. Null when unknown. - `free_days_source` 'shipment' | 'notice' | 'carrier' | 'null', nullable, required: Where `free_days` comes from, in order of authority. `shipment` means set on the shipment itself; `notice` means read from the latest arrival notice; `carrier` means the organization's negotiated terms for this carrier. Null when `free_days` is unknown. - `free_days_basis` 'calendar' | 'working' | 'null', nullable, required: How days are counted. `calendar` counts every day; `working` skips weekends and the country's public holidays. Null when there are no known terms. - `started_on` string, date, nullable, required: The port-local day the clock started (the discharge day for demurrage, the gate-out day for detention). Null while `not_started`. - `ended_on` string, date, nullable, required: The port-local day the clock ended. Null unless `stopped`. - `last_free_day` string, date, nullable, required: The last day that is still free. Null unless `running`. - `days_left` integer, nullable, required: Free days remaining after today, counted on `free_days_basis`. 0 means today is the last free day. Negative once overdue (at least -1). Null unless `running`. - `elapsed_days` integer, nullable, required: Calendar days since the start, counting the start day. Only set while `running_unknown_terms`. - `used_days` integer, nullable, required: How many days were used between start and end, counting both. Only set when `stopped`. - `overdue_days` integer, nullable, required: How many days beyond the free days were used. 0 when the clock stopped in time. Only set when `stopped` and the free days are known. - `carrier` string, nullable, required: The carrier the terms belong to, as a label. - `detention` FreeTimeClock[], required: One detention clock per container, in the same order as `demurrage`. Empty for shipments that are not ocean. - `object` 'free_time_clock', required: Always `free_time_clock`. - `kind` 'demurrage' | 'detention', required: Which charge this clock measures. - `container_number` string, nullable, required: The container the clock is for. Null when tracking events carry no container number. - `state` 'not_started' | 'running' | 'running_unknown_terms' | 'stopped' | 'end_not_reported' | 'return_not_reported', required: `not_started` means the clock has nothing to count from yet; `running` means it is counting against known free days; `running_unknown_terms` means it is counting but the free days are unknown (only `elapsed_days` is filled); `stopped` means it has ended (see `ended_on`, `used_days`, `overdue_days`); `end_not_reported` (demurrage) and `return_not_reported` (detention) mean the clock gave up waiting for the ending event because the container was archived or received in the warehouse, or 30 days passed without it. - `free_days` integer, nullable, required: The number of free days that apply. Null when unknown. - `free_days_source` 'shipment' | 'notice' | 'carrier' | 'null', nullable, required: Where `free_days` comes from, in order of authority. `shipment` means set on the shipment itself; `notice` means read from the latest arrival notice; `carrier` means the organization's negotiated terms for this carrier. Null when `free_days` is unknown. - `free_days_basis` 'calendar' | 'working' | 'null', nullable, required: How days are counted. `calendar` counts every day; `working` skips weekends and the country's public holidays. Null when there are no known terms. - `started_on` string, date, nullable, required: The port-local day the clock started (the discharge day for demurrage, the gate-out day for detention). Null while `not_started`. - `ended_on` string, date, nullable, required: The port-local day the clock ended. Null unless `stopped`. - `last_free_day` string, date, nullable, required: The last day that is still free. Null unless `running`. - `days_left` integer, nullable, required: Free days remaining after today, counted on `free_days_basis`. 0 means today is the last free day. Negative once overdue (at least -1). Null unless `running`. - `elapsed_days` integer, nullable, required: Calendar days since the start, counting the start day. Only set while `running_unknown_terms`. - `used_days` integer, nullable, required: How many days were used between start and end, counting both. Only set when `stopped`. - `overdue_days` integer, nullable, required: How many days beyond the free days were used. 0 when the clock stopped in time. Only set when `stopped` and the free days are known. - `carrier` string, nullable, required: The carrier the terms belong to, as a label. - `active_clock` FreeTimeClock, required: One demurrage or detention clock for one container. Demurrage starts at the container's discharge and stops at gate out (or, without one, at the return of the empty container). Detention starts at gate out and stops at the return of the empty container. Days are counted in the local calendar of the port. This object has no `id`. - `object` 'free_time_clock', required: Always `free_time_clock`. - `kind` 'demurrage' | 'detention', required: Which charge this clock measures. - `container_number` string, nullable, required: The container the clock is for. Null when tracking events carry no container number. - `state` 'not_started' | 'running' | 'running_unknown_terms' | 'stopped' | 'end_not_reported' | 'return_not_reported', required: `not_started` means the clock has nothing to count from yet; `running` means it is counting against known free days; `running_unknown_terms` means it is counting but the free days are unknown (only `elapsed_days` is filled); `stopped` means it has ended (see `ended_on`, `used_days`, `overdue_days`); `end_not_reported` (demurrage) and `return_not_reported` (detention) mean the clock gave up waiting for the ending event because the container was archived or received in the warehouse, or 30 days passed without it. - `free_days` integer, nullable, required: The number of free days that apply. Null when unknown. - `free_days_source` 'shipment' | 'notice' | 'carrier' | 'null', nullable, required: Where `free_days` comes from, in order of authority. `shipment` means set on the shipment itself; `notice` means read from the latest arrival notice; `carrier` means the organization's negotiated terms for this carrier. Null when `free_days` is unknown. - `free_days_basis` 'calendar' | 'working' | 'null', nullable, required: How days are counted. `calendar` counts every day; `working` skips weekends and the country's public holidays. Null when there are no known terms. - `started_on` string, date, nullable, required: The port-local day the clock started (the discharge day for demurrage, the gate-out day for detention). Null while `not_started`. - `ended_on` string, date, nullable, required: The port-local day the clock ended. Null unless `stopped`. - `last_free_day` string, date, nullable, required: The last day that is still free. Null unless `running`. - `days_left` integer, nullable, required: Free days remaining after today, counted on `free_days_basis`. 0 means today is the last free day. Negative once overdue (at least -1). Null unless `running`. - `elapsed_days` integer, nullable, required: Calendar days since the start, counting the start day. Only set while `running_unknown_terms`. - `used_days` integer, nullable, required: How many days were used between start and end, counting both. Only set when `stopped`. - `overdue_days` integer, nullable, required: How many days beyond the free days were used. 0 when the clock stopped in time. Only set when `stopped` and the free days are known. - `carrier` string, nullable, required: The carrier the terms belong to, as a label. ## Other responses - `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400. - `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header. - `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one. - `404`: No such object in this organization (`resource_missing`). This is also the answer for an id of another organization, an id with the wrong prefix, or a malformed id, so the API never confirms that an object exists elsewhere. - `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced. --- [API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)