Fill gaps from assistant conversations: estimated events and invalidation

docs/api-docs/api-reference/containers/get-a-containers-raw-events.mdx

@@ -20,8 +20,20 @@ The response includes an `original_event` field with the raw carrier event name,
 |---|---|---|
 | Status | Deprecated | Recommended |
 | Source | Carrier feed, mostly as-is | Vetted and normalized across carriers |
-| Includes estimated future events | Yes | No |
+| Estimated events | Any event type can be estimated, flagged by `attributes.estimated` | Only three normalized `estimated.*` event types (see below) |
 | Includes `original_event` | Yes | No |
 | Data quality | More events, less consistent normalization | Fewer events, higher confidence |
 
-Use `transport_events` for past milestones. Use `raw_events` only when you need the carrier's original event name or estimated future events that are not yet delivered as transport events.
+Use `transport_events` for past milestones. Use `raw_events` only when you need the carrier's original event name or estimated events that have no `transport_events` equivalent.
+
+## Estimated events
+
+In `raw_events`, any event type can carry an estimated timestamp. The `attributes.estimated` boolean is `true` when the timestamp is an estimate, so estimated feeder, rail, and transshipment events appear here.
+
+In `transport_events`, estimates are separate event types, and only three exist:
+
+- `container.transport.estimated.vessel_departed`
+- `container.transport.estimated.vessel_arrived`
+- `container.transport.estimated.arrived_at_inland_destination`
+
+There are no estimated equivalents for feeder, rail, or transshipment events in `transport_events`. If you need estimated timestamps for those milestones, `raw_events` is currently the only endpoint that provides them.

docs/api-docs/api-reference/containers/get-a-containers-transport-events.mdx

@@ -20,6 +20,16 @@ The `attributes.event` field is one of a fixed set of normalized event names cov
 
 The `attributes.data_source` field indicates where the event originated: `shipping_line`, `terminal`, or `ais`.
 
+### Estimated event types
+
+Three estimated event types can appear in the response:
+
+- `container.transport.estimated.vessel_departed`
+- `container.transport.estimated.vessel_arrived`
+- `container.transport.estimated.arrived_at_inland_destination`
+
+These are the only estimated events in `transport_events`. Feeder, rail, and transshipment events exist only as actual milestones here. For estimated timestamps on those event types, use the deprecated [raw events endpoint](/api-docs/api-reference/containers/get-a-containers-raw-events), which flags estimates with an `attributes.estimated` boolean on any event type.
+
 ## Null locations and timezones
 
 Some events may have a `null` `location_locode` and `timezone` — most commonly on estimated events. See [Event Timestamps](/api-docs/in-depth-guides/event-timestamps) for details on how to interpret those timestamps.

docs/api-docs/webhooks/event-catalog.mdx

@@ -94,6 +94,10 @@ These events fire when an estimated departure or arrival time changes.
 | `container.transport.estimated.vessel_arrived` | ETA changed for vessel arrival at the port of discharge (container level). |
 | `container.transport.estimated.arrived_at_inland_destination` | ETA changed for the inland destination. Fires only for shipments with an inland rail leg. See the [Rail integration guide](/api-docs/in-depth-guides/rail-integration-guide). |
 
+<Note>
+These are the only estimated event types. There are no estimated equivalents for feeder, rail, or transshipment events. If you need estimated timestamps for those milestones, use the deprecated [raw events endpoint](/api-docs/api-reference/containers/get-a-containers-raw-events), which flags estimates with an `attributes.estimated` boolean on any event type.
+</Note>
+
 ## Container update events
 
 These events fire when container attributes change.

docs/api-docs/webhooks/payloads.mdx

@@ -171,6 +171,12 @@ Resolve the IDs through the `terminal` resources serialized in `included`.
 The `container_updated_event` also has a `terminal` relationship that indicates where the data came from. Currently this is always the POD terminal; in the future it may be the final destination terminal or an off-dock location.
 </Note>
 
+### Milestone fields reverting to null
+
+Container milestone timestamps such as `pod_full_out_at` are derived from transport events. Terminal49 vets incoming events and can mark an event as invalid after publishing it, for example when a carrier or terminal retracts or corrects the data. When the source event is invalidated, the derived container field reverts, often back to `null`, and the change appears in a `container.updated` changeset as `[previous_value, null]`.
+
+To investigate why a field reverted, DataSync customers can query the [`transport_events` table](/datasync/table-properties/transport-events), which records `invalidated_at`, `invalidation_reason`, and `previous_version_id` for each event. These invalidation fields are not exposed on the API's transport events endpoint. If the invalidation reason is unclear, contact Terminal49 support with the affected container numbers.
+
 ## Related
 
 - [Event Catalog](/api-docs/webhooks/event-catalog) — canonical event names