Container Delay Costs

Container Delay Costs tracks one container per operational record, with a shared shipment reference for containers travelling together. It calculates separate terminal-storage (demurrage) and empty-return (detention) estimates, records approved free-day extensions, and reconciles existing native vendor-bill lines.

Installation and edition

Install corvus_container_delay_costs on Odoo 20 with the standard mail and account addons available. Update the Apps list, find Container Delay Costs, and install it. No external service, API key, hardware or scheduled job is required. The app appears as Container Costs.

Tested on Odoo 20 Enterprise: installation with and without demonstration data, focused workflow and access checks, and HTML report rendering. Community has not been qualified; the use of standard Community dependencies alone is not a compatibility claim. No other major version is supported by this package.

Optional demonstration data provides fictional shipments and provider references. It does not create or post vendor bills. Installation without demo still provides a shipment sequence, a dedicated activity type and two illustrative rate schedules for the installation company.

Roles and company access

An administrator assigns a Container Delay Costs role on each user's access rights:

Role	Permitted work
Coordinator	Create and update shipments, start tracking, refresh estimates, schedule deadline activities, request extensions, read costs and print summaries.
Manager	Coordinator work, tariff configuration, extension approval/rejection/revocation, bill allocation, closing, cancelling and reopening shipments, deleting drafts.

Allocating a vendor-bill line also requires native Accounting access to that line. The app does not grant additional Accounting rights. A coordinator can read the allocated cost summary for permitted shipments; native invoice selection still respects Accounting permissions. Users without an app role have no access to its records. All schedules, shipments, extensions and allocations are restricted to allowed companies. Assign a coordinator who can access the shipment company.

Configure rate schedules

Open Container Costs → Rate Schedules as a manager. Review the supplied illustrative terminal and return schedules before operational use. They are examples, not published carrier tariffs. Create separate schedules for each company and currency.

1. Name the agreement and tariff version.
2. Choose Demurrage / terminal storage or Detention / container return.
3. Enter free days and select the day-counting convention.
4. Add consecutive chargeable-day tiers beginning at day 1. The next tier begins immediately after the previous tier ends. Set the final tier's last day to 0 for no upper limit.
5. Enter each tier's daily rate in the schedule currency. Zero-cost tiers are allowed; negative rates are not.
6. Record the provider agreement and assumptions in Contract Notes.

Tier days count after all standard and approved extra free days. For example, with two free days, chargeable days 1–2 at 10 and day 3 onward at 25, the first three chargeable days cost 45.

A schedule becomes fixed when any linked shipment leaves Draft, including a subsequently cancelled shipment. Duplicate the schedule to create a new tariff version. You can archive a used schedule while retaining history. Draft shipments may be changed to a different schedule; tracking shipments keep the original company, currency, timezone and tariffs.

Understand dates and free time

Terminal storage runs from Discharge to Pickup. Container return runs from Pickup to Empty Return. Pickup is both one clock's end and the next clock's start; each schedule applies its own convention.

Movement timestamps are entered and displayed in the current user's Odoo timezone. The app converts each timestamp to a calendar date in the shipment's Timezone, which should be the agreed port/site timezone. The read-only local dates show exactly what the estimate uses. Daylight-saving changes are handled by that timezone; charges are calendar-day based, not elapsed 24-hour blocks.

• Exclude start day; include end day: elapsed days equal end date minus start date. A same-day movement counts zero days.
• Include start and end days: a same-day movement counts one day.

Subtract the schedule's free days and approved extensions, with a minimum of zero chargeable days. Expiry is the last free local date, inclusive. With zero free days and an included start day, expiry is the day before the start date; the start date is already chargeable.

An open clock ends at the explicit Estimate Cutoff (as_of_date). The estimate does not advance in the background. Select Refresh to Today to move this cutoff to today's date in the shipment timezone. You can enter a later planning date, but the cutoff cannot precede an entered pickup or return date. An actual pickup or return stops its clock, even if the cutoff is later. A cutoff before discharge produces zero cost for that unstarted period.

Worked shipment

Using the supplied illustrative schedules (terminal: five free days, first three chargeable days at 35, then 60; return: three free days, first four chargeable days at 45, then 75), both excluding the start day:

1. Create a shipment for container HBLC 410251-4, shipment BL-HB-2026-042, at North Quay Terminal. Choose the company, currency, provider, coordinator and Europe/London timezone.
2. Select the terminal and return schedules. Enter discharge on 25 October 2026 and an estimate cutoff of 10 November 2026.
3. Select Start Tracking. Discharge is required; schedules must have complete consecutive tiers. A native activity is assigned for the next open free-time deadline.
4. Enter pickup on 2 November. Eight elapsed terminal days minus five free days gives three charged days, costing 105.
5. Create a detention extension request for two days, using a provider reference and a meaningful reason. A manager opens it and selects Approve. Pending requests do not affect cost.
6. At 10 November, the return clock has eight elapsed days, minus three standard and two extra free days. Three chargeable days cost 135. The shipment estimate is 240, before tax, in the schedule currency.
7. Enter the actual empty return when known, with a cutoff on or after that date. The return clock stops and its deadline activity is removed.
8. Allocate a posted vendor-bill line when available, then select Close Shipment as a manager. Closing requires empty return, no pending extension requests and no unposted allocated bill lines. A shipment may close while vendor billing is still awaited; the report states when there are no allocated lines.

Extension decisions and corrections

Open Free-Day Extensions, create a request and enter the clock, positive number of extra days, provider reference and reason. Attach the supporting provider document in the shipment chatter. Several approved requests add together.

Managers can approve or reject pending requests. Approved requests retain the approver and timestamp; they cannot be edited or deleted. To correct an approval, reopen the shipment if needed, Revoke Approval, and create a corrected request. Revocation removes those days from the estimate while preserving approval history. Pending requests can be corrected or deleted while the shipment is tracking. Start tracking before creating extension requests. Repeated decisions on an already decided request are rejected.

Actual vendor costs

Post and manage vendor bills through native Accounting using your normal accounting controls. This app never creates or posts a financial document.

In Actual Vendor Costs, a manager selects an existing posted vendor-bill or vendor-credit-note product line, chooses the affected clock and enters an operational explanation. The document must have the same company and currency as the shipment. The app allocates the whole untaxed line once across all shipments. Split a multi-container expense into distinct native bill lines before allocation; partial line allocation and currency conversion are not supported.

Vendor credits contribute a negative amount. Taxes are excluded. Variance is posted allocated actual cost minus the estimate; a negative variance may mean billing is incomplete. It is not automatically a saving.

If Accounting resets or cancels a linked bill, its allocation remains visible but contributes zero. A warning identifies the unposted allocation and closing is blocked. Reposting the native bill restores its actual value. To correct a link, reopen the shipment if closed, remove the wrong allocation and create the correct one. Linked native bill lines cannot be deleted until the allocation is removed. Native financial amounts remain authoritative, even after the operational shipment has closed. Remove the allocation before changing a linked bill's company, currency or document type, or a linked line's bill, currency or type.

Deadlines, lists and reports

Shipments offers reference, container, provider and coordinator searches; status, awaiting-pickup, awaiting-return and bill-review filters; and groups for shipment reference, coordinator, status, currency and company. Monetary list columns intentionally have no mixed-currency grand total.

Deadlines shows the last free day of the current open clock. Select a calendar entry to open the shipment. Calendar dragging and quick creation are disabled because deadlines come from milestones, tariffs and approved extensions. Start, milestone/date changes and extension decisions update the app's dedicated activity. Update Deadline Activity recreates a manually removed reminder without creating duplicates. There is no automatic email campaign or carrier notification.

Use Print → Container Cost Summary from a shipment to print local milestone dates, counting conventions, free days, approved extensions, estimates, posted allocated native costs and variance. Multi-select printing produces a separate summary for each container; group the list by shipment reference to find containers belonging to the same consignment. The report is an operational estimate, not a carrier invoice or legally certified tariff calculation.

PDF output requires a working native Odoo PDF renderer configured by your administrator. HTML report rendering has been verified; PDF rendering has not been qualified because the test environment had no available PDF engine.

Close, cancel and reopen

Only managers close, cancel or reopen shipments. Cancelling is allowed for draft or tracking records without bill allocations. It retains operational history and removes the deadline reminder. Reopening returns a record to Tracking if discharge exists, otherwise Draft. Closed and cancelled records are protected against business-detail changes. Only draft shipments may be deleted.

Upgrade preservation and troubleshooting

Back up your database before an ordinary module upgrade. Normal sequences, activity type and illustrative schedules are configured to preserve user-edited reference values during upgrades. Demo data is optional and is not recreated on ordinary upgrades. Used tariff versions remain retained through their shipment references.

Symptom	Action
Cannot start tracking	Enter discharge and check that both schedules match the clock, company and currency, with consecutive tiers and an open-ended final tier.
Unexpected charged day	Compare the read-only local date, port/site timezone, selected day convention, free days, extension approval state and cutoff.
Estimate has not increased	Select Refresh to Today; no background accrual job runs.
No return deadline	Enter actual pickup; detention has not begun before pickup. Completed returns have no open deadline.
Cannot change a tariff	Duplicate a schedule already used by a non-draft shipment.
Cannot select a bill	Check native Accounting permission, posting state, company, currency and product-line type. A previously allocated line cannot be allocated again.
Bill review warning	Repost the linked document through Accounting or remove the allocation while the shipment is tracking.
Cannot close	Record empty return, resolve pending extensions and remove or repost unposted allocations.
Missing records	Check the app role, allowed companies, current list filters and archived schedules.
PDF unavailable	Ask your administrator to confirm that a working native Odoo PDF renderer is installed and available.

Scope and support

There is no carrier API, automatic bill creation, automatic posting, port calendar/holiday exclusion, partial-day rounding, tax engine, exchange-rate conversion, partial bill-line allocation, route optimization or legal tariff certification. Cost calculation uses one fixed timezone and one currency per container record.

Publisher: Corvus Nexus Technologies LTD. Website: https://corvusnexus.com. Support: support@corvusnexus.com. Include your Odoo version, app version, relevant cutoff/convention and a fictional or redacted example; never send passwords.

Availability

This guide covers the Odoo 20 package. Older-version packages are not part of this release.

Browse the Corvus Odoo Apps catalogue.