Appearance
⚓ Time Charter Calculation
DirectPort automatically calculates time charter costs for your voyages based on daily rental rates defined in contracts. This guide explains how to set up contracts correctly, how the calculation works under the hood, and what to watch out for.
Prerequisites
- A voyage with a vessel assigned
- A contract of type Time Charter linked to the voyage
- Cargo must be Dry or Liquid base type
📋 How It Works — The Big Picture
Time charter cost is calculated using a simple formula:
Total Cost = Net Days x Daily Rate
Where:
- Net Days = Gross Days - Off-Hire Days
- Gross Days = time between the end of the current voyage and the start of the charter period (or end of the previous voyage)
- Off-Hire Days = periods where the vessel was out of service
The system runs this calculation automatically whenever the last stop's terminal operation is completed. Results flow directly into the Financial module.
📝 Contract Setup
Before any calculation can happen, you need a properly configured contract.
1. Create a Time Charter contract
Navigate to the Contracts section and create a new contract. Set the contract type to Time Charter.
Critical Fields
The following must be set on the contract for the calculation to qualify:
- Contract Type =
TIME_CHARTER - Vessel linked under Contract Vessels
2. Link the vessel
Under the contract, go to the Vessels tab and add the vessel that will operate under this charter. Set the Actual Delivery Date — this is the date the vessel was officially handed over to the charterer.
Why Actual Delivery Date matters
This date serves as a fallback reference point when there is no previous voyage to measure from. For the very first voyage under a new contract, this is the start of the billing period.
3. Assign the contract to a voyage
On the voyage, under Charter Party Terms, link the contract for either the Transport side, the Customer side, or both. Then set:
- Base Freight Cost Type =
Daily Rent - Base Freight Cost = the agreed daily rate (e.g. 10,000 EUR/day)
You can configure this independently for transport and customer parties — the system calculates each side separately.
⚓ What Triggers the Calculation?
The calculation runs automatically via a database trigger when:
- A terminal operation's Transfer End At (dry cargo) or Documents On Board At (liquid cargo) is updated
- The operation belongs to the last stop of the voyage
INFO
Operations on intermediate stops do not trigger calculation — only the final stop matters. This ensures all cargo handling is complete before costs are tallied.
📅 The Calculation in Detail
Step 1 — Determine the End Timestamp
The system looks at the last stop of the voyage (highest order) and picks the latest timestamp from its terminal operations:
| Cargo Type | Timestamp Used |
|---|---|
| 📦 Dry | Transfer End At — when physical cargo transfer completed |
| 💧 Liquid | Documents On Board At — when documentation was finalized |
If the last stop has multiple operations, the latest (most recent) timestamp is used.
No timestamp? No calculation.
If the last stop has no terminal operations, or the relevant timestamp field is empty, the calculation is skipped entirely. Make sure operations are completed before expecting results.
Step 2 — Find the Reference Date (Start of Period)
The reference date marks the beginning of the billing period. The system uses a 3-level fallback:
🥇 Priority 1: Previous voyage's last stop
The end timestamp of the most recent completed voyage for the same vessel under the same contract. This creates seamless back-to-back billing with no gaps or overlaps.
🥈 Priority 2: Contract vessel delivery date
The
Actual Delivery Atdate from the Contract Vessels record. Used for the first voyage under a new charter.
🥉 Priority 3: First stop ATA
The Actual Time of Arrival at the voyage's first stop. A last-resort fallback.
WARNING
If none of the three reference dates can be determined, the calculation for that party is skipped. Check your contract setup and voyage data.
Step 3 — Calculate Gross Days
Gross Days = (End Timestamp - Reference Date) / 24 hoursThis gives the total elapsed time in days (with decimal precision). If the result is zero or negative, the party is skipped.
Step 4 — Deduct Off-Hire Periods
The system queries Vessel Schedule Events marked as off-hire for the vessel within the billing window:
- Only events overlapping the
[Reference Date, End Timestamp]window are considered - Events are clamped to the window — if an off-hire started before the reference date or ends after the end timestamp, only the overlapping portion counts
- Ongoing off-hire events (no end date) are clamped to the end timestamp
Example: Off-hire clamping
A vessel has an off-hire event from Feb 8 to Feb 16. The billing window is Feb 10 to Feb 20.
Only the overlapping period counts: Feb 10 to Feb 16 = 6 days deducted.
Step 5 — Compute Final Cost
Net Days = Gross Days - Off-Hire Days
Total = Net Days x Daily RateThe total is rounded to 2 decimal places and saved to the voyage.
💰 Where Do Results Go?
Depending on the party, the calculated total is stored on the voyage:
| Party | Voyage Field |
|---|---|
| Transport | Total Base Freight Cost |
| Customer | Customer Total Base Freight Cost |
A database trigger then automatically syncs these values to a Financial Item of type transport-base-freight-time-charter, making it available for invoicing in the Financial module.
🔧 Worked Example
Let's walk through a real scenario:
Vessel: MV Rhine Express Contract: Time Charter, Daily Rate = EUR 10,000/dayCurrent voyage last stop: Transfer End At = Feb 20, 15:00Previous voyage last stop: Transfer End At = Feb 10, 12:00Off-hire event: Feb 14 09:00 to Feb 15 18:00 (33 hours)
Calculation:
| Step | Value |
|---|---|
| End Timestamp | Feb 20, 15:00 |
| Reference Date | Feb 10, 12:00 (from previous voyage) |
| Gross Days | 10.125 days |
| Off-Hire Days | 1.375 days (33h / 24h) |
| Net Days | 8.75 days |
| Total | 8.75 x 10,000 = EUR 87,500.00 |
✅ Best Practices
- Always set Actual Delivery Date on contract vessels — without it, the first voyage has no reference point
- Complete terminal operations on the last stop to trigger calculation — intermediate stops alone won't do it
- Record off-hire events in the Vessel Schedule before the voyage ends for accurate deductions
- Check both sides — transport and customer can have independent contracts with different daily rates
- Review financial items after calculation to verify the cost line appears correctly
Back-to-back voyages
For vessels operating continuously under a charter, each voyage automatically picks up where the previous one left off. No manual period entry needed — the system chains them together seamlessly.
❗ Troubleshooting
| Symptom | Likely Cause |
|---|---|
| No calculation runs | Last stop has no terminal operation timestamps |
| Cost shows as zero | Reference date is the same as (or after) end timestamp |
| Off-hire not deducted | Off-hire event doesn't overlap the billing window, or is marked as deleted |
| Only one party calculated | The other party's contract is missing, not type TIME_CHARTER, or cost type is not DAILY_RENT |
| Wrong reference date | Previous voyage's operations aren't completed, or contract vessel has no delivery date |
Common Mistake
If the voyage's cargo product doesn't resolve to a Dry or Liquid base type, the voyage is excluded from time charter calculation entirely. Make sure your cargo products are properly linked to cargo types.