B/L Date Stamp

Key point

bill of lading dates

One moment has a different calendar date in each place. A bill of lading carries the local one, so the date is a reading of the place and not of the timestamp.

A system stamps an event with a moment: 2024-06-16T01:00:00Z. The bill of lading needs a date. Which date depends on where the event happened, because the same moment is still the 15th in New York and already the 16th in UTC.

Type the moment, choose the event and pick the place. The tool calls bolTimestamp for the place and again for UTC, and the two plates show both dates. The lanes below put each calendar on one time axis, as real local days, and one line cuts all of them at the moment. In each lane the lit day is the date the library gave. Drag the slider to move the moment through 15-minute steps, and watch the date change where a lane crosses its midnight.

1. Set the moment and the place

A box is loaded at 21:00 in New York. In UTC the clock has already reached the next day, but the bill of lading carries the local date. Shanghai is added as a second calendar.

A box is loaded at 21:00 in New York. In UTC the clock has already reached the next day, but the bill of lading carries the local date. Shanghai is added as a second calendar.

A box is loaded at 07:00 in Shanghai. UTC is still on the day before, so reading the timestamp as UTC would date the bill a day early.

The clocks go back in Amsterdam on 27 October, so that local day lasts 25 hours and 02:30 happens twice. The moment is one of them, and the date is still the 27th.

Samoa moved across the date line at the end of 29 December 2011. Its calendar has no 30 December, so a moment on UTC's 30th is already the 31st there.

The place can be a UTC offset instead of a zone name. An offset never changes with the season, so the date follows from the offset alone.

The same moment with no place. Every bill of lading date is local, so without a zone the library has no date to give.

MomentLatest date allowed optional

Every bill of lading date is the local one, so the place is required. The other calendars show the same moment's date elsewhere. The latest date is yours: the tool only compares against it.

2. The date in each place

Shipped on board dateShipped on board dateReceived for shipment dateIssue date

no result

UTC dateno result

1

2

3

4

• the day with the date
• UTC, read naively
• the moment

Move the moment36 h earlier36 h later

3. What bolTimestamp returns

 

The rule. bolTimestamp(value, event, { timeZone }) reads the moment on the clock of the place and returns that clock’s date, as YYYY-MM-DD. The event is issue, received or shippedOnBoard, the three dates a bill of lading carries (issueDate, receivedForShipmentDate and shippedOnBoardDate in the DCSA standard). All three events give the same date for the same moment and place. The place is an IANA zone name or a UTC offset, and it is required: there is no UTC default, so a call with no place returns "".

The UTC lane is the naive read. It is drawn hollow and dashed. Reading the timestamp as UTC is what a system does when it forgets the place, and it dates the document a day late west of Greenwich and a day early east of it. Where the two plates differ, the tool says “one day later” or “one day earlier”, which are areDatesEqual and isAfterDate at work on the two dates.

A latest date. The optional latest date is yours. The tool does not know where it comes from. It asks isAfterDate whether each date falls after it, and the plates say “after the latest date” or “on or before the latest date”. A latest date that is not a date makes no comparison, and the plate says so.

When there is no date. A place the library cannot read, a value that is not a moment, an event outside the three and a missing place each return "", and the tool shows NO SIGNAL with one sentence saying which. The tool decides the sentence by asking the library about a known moment, not from a list of its own. A calendar you add in a lane that the library cannot read keeps its lane and says so.

const moment = "2024-06-16T01:00:00Z";

bolTimestamp(moment, "shippedOnBoard", { timeZone: "America/New_York" }); // "2024-06-15"
bolTimestamp(moment, "shippedOnBoard", { timeZone: "UTC" }); // "2024-06-16"
bolTimestamp("2024-06-14T23:00:00Z", "shippedOnBoard", { timeZone: "Asia/Shanghai" }); // "2024-06-15"
bolTimestamp("2011-12-30T10:00:00Z", "shippedOnBoard", { timeZone: "Pacific/Apia" }); // "2011-12-31"
bolTimestamp(moment, "shippedOnBoard"); // ""

areDatesEqual("2024-06-16", "2024-06-15"); // false
isAfterDate("2024-06-16", "2024-06-15"); // true

Worth trying: a moment at 07:00 in Shanghai — UTC is still on the 14th, and bolTimestamp returns "2024-06-15". Then the New York evening against a latest date of 15 June — the local date, "2024-06-15", is on or before it, and the UTC date, "2024-06-16", is after it. Samoa on the day its calendar skipped — the library returns "2011-12-31", and the lane has no 30 December. The same moment with no place — the result is NO SIGNAL, because the place is required. For four calendars at once, try one moment in New York, Shanghai, Auckland and Amsterdam — New York is the 15th and the other three are the 16th.

Reference: bolTimestamp gives the local date, isAfterDate and areDatesEqual compare two dates, and isValidDate checks the latest date. The rules are in Intermodal: B/L Dates and Multimodal ETA.