diff --git a/docs/api-docs/in-depth-guides/rail-integration-guide.mdx b/docs/api-docs/in-depth-guides/rail-integration-guide.mdx index 9e4649f4..6241356e 100644 --- a/docs/api-docs/in-depth-guides/rail-integration-guide.mdx +++ b/docs/api-docs/in-depth-guides/rail-integration-guide.mdx @@ -134,20 +134,39 @@ Integrate these notifications by subscribing to the webhooks and handling the in #### Rail container attributes -The following are new attributes that are specific to rail container tracking. +The following attributes are specific to rail container tracking and live on the [container object](/api-docs/api-reference/containers/get-a-container). - **pod_rail_loaded_at**: Time when the container is loaded onto a railcar at the POD. - **pod_rail_departed_at**: Time when the container departs from the POD. -- **ind_eta_at**: Estimated Time of Arrival at the inland destination. -- **ind_ata_at**: Actual Time of Arrival at the inland destination. +- **ind_eta_at**: Estimated Time of Arrival at the inland destination, sourced from the rail carrier. +- **ind_ata_at**: Actual Time of Arrival at the inland destination, sourced from the rail carrier. - **ind_rail_unloaded_at**: Time when the container is unloaded from rail at the inland destination. -- **ind_facility_lfd_on**: Last Free Day for demurrage charges at the inland destination terminal. +- **ind_facility_lfd_on**: **Deprecated.** Last Free Day for demurrage charges at the inland destination terminal. Use `import_deadlines.pickup_lfd_rail` instead (timezone: `final_destination_timezone`). - **pod_rail_carrier_scac**: SCAC code of the rail carrier that picks up the container from the POD (this could be different than the rail carrier that delivers to the inland destination). - **ind_rail_carrier_scac**: SCAC code of the rail carrier that delivers the container to the inland destination. -{/* TODO: Look at the other container attributes that could be fed via rail but are currently shipping-line-only. Such as :current_issues, :pickup_appointment_at, :availability_known, :available_for_pickup */} +##### Inland destination ETA/ATA: rail carrier vs. shipping line + +For an inland (rail) move, two pairs of arrival fields exist and can differ: + +| Field | Lives on | Source | Notes | +|---|---|---|---| +| `ind_eta_at` / `ind_ata_at` | container | Rail carrier | Estimated and actual arrival at the inland destination, reported directly by the rail carrier. | +| `destination_eta_at` / `destination_ata_at` | shipment | Shipping line (SSL) | Estimated and actual arrival at the shipment's destination as reported by the ocean carrier. For inland moves, this is the SSL's view of the inland destination. | + +Use `ind_*` when you want the rail carrier's view (typically more granular and updated more frequently for inland legs). Use `destination_*` when you want the SSL-reported view on the shipment. The corresponding timezone for `ind_*` fields is `final_destination_timezone` (on the container); for `destination_*` fields it is `destination_timezone` (on the shipment). + +##### Rail Last Free Day (LFD) -These attributes can be found on [container objects](/api-docs/api-reference/containers/get-a-container). +The container's top-level `pickup_lfd` attribute is a coalesced value derived from the `import_deadlines` object, in this order of preference: + +1. `import_deadlines.pickup_lfd_line` — LFD as reported by the shipping line (preferred). +2. `import_deadlines.pickup_lfd_terminal` — LFD from the POD terminal (timezone: `pod_timezone`). +3. `import_deadlines.pickup_lfd_rail` — LFD from the rail carrier at the inland destination (timezone: `final_destination_timezone`). + +For rail moves, subscribe to the `container.pickup_lfd_rail.changed` webhook to be notified when the rail carrier updates the inland LFD. The legacy `ind_facility_lfd_on` field is deprecated — read `import_deadlines.pickup_lfd_rail` instead. + +{/* TODO: Look at the other container attributes that could be fed via rail but are currently shipping-line-only. Such as :current_issues, :pickup_appointment_at, :availability_known, :available_for_pickup */} ## Integration methods diff --git a/docs/openapi.json b/docs/openapi.json index e6015163..fdd3a787 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -10680,36 +10680,43 @@ "pol_etd_at": { "type": "string", "format": "date-time", + "description": "Estimated Time of Departure from the Port of Lading, as reported by the shipping line. Carrier dependent; may be null.", "nullable": true }, "pol_atd_at": { "type": "string", "format": "date-time", + "description": "Actual Time of Departure from the Port of Lading. Populated after the vessel has departed the origin port.", "nullable": true }, "pod_eta_at": { "type": "string", "format": "date-time", + "description": "Estimated Time of Arrival at the Port of Discharge.", "nullable": true }, "pod_original_eta_at": { "type": "string", "format": "date-time", + "description": "Initial Estimated Time of Arrival at the Port of Discharge, as first reported by the shipping line.", "nullable": true }, "pod_ata_at": { "type": "string", "format": "date-time", + "description": "Actual Time of Arrival at the Port of Discharge.", "nullable": true }, "destination_eta_at": { "type": "string", "format": "date-time", + "description": "Estimated Time of Arrival at the shipment's destination, as reported by the shipping line. For inland (rail) moves, see also the container-level `ind_eta_at`, which is reported by the rail carrier. Corresponding timezone is `destination_timezone`.", "nullable": true }, "destination_ata_at": { "type": "string", "format": "date-time", + "description": "Actual Time of Arrival at the shipment's destination, as reported by the shipping line. For inland (rail) moves, see also the container-level `ind_ata_at`, which is reported by the rail carrier. Corresponding timezone is `destination_timezone`.", "nullable": true }, "pol_timezone": { @@ -11178,16 +11185,19 @@ "ind_eta_at": { "type": "string", "format": "date-time", + "description": "Estimated Time of Arrival at the inland destination, as reported by the rail carrier. For the shipping-line view at the shipment's destination, see `destination_eta_at` on the shipment. Corresponding timezone is `final_destination_timezone`.", "nullable": true }, "ind_ata_at": { "type": "string", "format": "date-time", + "description": "Actual Time of Arrival at the inland destination, as reported by the rail carrier. For the shipping-line view at the shipment's destination, see `destination_ata_at` on the shipment. Corresponding timezone is `final_destination_timezone`.", "nullable": true }, "ind_rail_unloaded_at": { "type": "string", "format": "date-time", + "description": "Time when the container is unloaded from rail at the inland destination.", "nullable": true }, "ind_facility_lfd_on": { @@ -11210,13 +11220,13 @@ "pickup_lfd_rail": { "type": "string", "format": "date-time", - "description": "The last free day for pickup before demmurage accrues. Corresponding timezone is final_destination_timezone.", + "description": "The last free day for pickup at the inland destination, as reported by the rail carrier. Corresponding timezone is final_destination_timezone. Subscribe to `container.pickup_lfd_rail.changed` to be notified of updates.", "nullable": true }, "pickup_lfd_line": { "type": "string", "format": "date-time", - "description": "The last free day as reported by the line. Corresponding timezone is final_destination_timezone or pod_timezone.", + "description": "The last free day as reported by the shipping line (carrier dependent). Corresponding timezone is final_destination_timezone or pod_timezone. Preferred source for the coalesced top-level `pickup_lfd` field.", "nullable": true } },