Skip to content

Draft improvements from assistant conversations: shipment vs. container field placement #298

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mintlify merged 1 commit into from
Jul 13, 2026
Merged

Draft improvements from assistant conversations: shipment vs. container field placement #298

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions docs/api-docs/getting-started/list-shipments-and-containers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,41 @@ After Terminal49 accepts a tracking request, it starts collecting available data

Use these endpoints for on-demand lookups. For ongoing status monitoring, use webhooks instead of polling.

## Which object holds which field?

Tracking data is split across two resources. If you query the wrong endpoint you will not see the field you expect — for example, `pod_eta_at` is **not** returned by `GET /containers` because it lives on the shipment.

| Field | Object | Endpoint |
| --- | --- | --- |
| `pod_eta_at` — current ETA at the port of discharge | `shipment` | `GET /shipments/{id}` |
| `pod_original_eta_at` — first ETA reported by the carrier | `shipment` | `GET /shipments/{id}` |
| `destination_eta_at` — ETA at the final destination (carrier view) | `shipment` | `GET /shipments/{id}` |
| `pod_ata_at` — actual arrival at the port of discharge | `shipment` | `GET /shipments/{id}` |
| `bill_of_lading_number` | `shipment` | `GET /shipments/{id}` |
| `port_of_lading_name` / `port_of_discharge_name` | `shipment` | `GET /shipments/{id}` |
| `shipping_line_scac` / `shipping_line_name` | `shipment` | `GET /shipments/{id}` |
| `ref_numbers` | `shipment` | `GET /shipments/{id}` |

@greptile-apps greptile-apps Bot Jul 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Reference Numbers On Wrong Resource

When a developer follows this row to fetch ref_numbers, they will query the shipment endpoint even though the schema places ref_numbers on container attributes. That leaves the documented lookup path returning no reference numbers for the field this table is meant to locate.

Suggested change
| `ref_numbers` | `shipment` | `GET /shipments/{id}` |
| `ref_numbers` | `container` | `GET /containers/{id}` |
Prompt To Fix With AI 
This is a comment left during a code review.
Path: docs/api-docs/getting-started/list-shipments-and-containers.mdx
Line: 38

Comment:
**Reference Numbers On Wrong Resource**

When a developer follows this row to fetch `ref_numbers`, they will query the shipment endpoint even though the schema places `ref_numbers` on container attributes. That leaves the documented lookup path returning no reference numbers for the field this table is meant to locate.

```suggestion
| `ref_numbers` | `container` | `GET /containers/{id}` |
```

How can I resolve this? If you propose a fix, please make it concise.

Fix in Codex

| `number` — container number | `container` | `GET /containers/{id}` |
| `pod_arrived_at` / `pod_discharged_at` | `container` | `GET /containers/{id}` |
| `pod_full_out_at` — gated out of the port terminal | `container` | `GET /containers/{id}` |
| `empty_terminated_at` — empty returned | `container` | `GET /containers/{id}` |
| `pickup_lfd` — last free day | `container` | `GET /containers/{id}` |
| `holds_at_pod_terminal` / `fees_at_pod_terminal` | `container` | `GET /containers/{id}` |
| `available_for_pickup` / `availability_known` | `container` | `GET /containers/{id}` |
| `ind_eta_at` / `ind_ata_at` — rail carrier ETA/ATA at inland destination | `container` | `GET /containers/{id}` (see [Rail integration guide](/api-docs/in-depth-guides/rail-integration-guide)) |

### Fetching shipment fields alongside a container

If you already have a container ID (or are filtering by container number) and want the shipment ETA fields in the same response, use the `include` query parameter to embed the related shipment:

```bash
curl "https://api.terminal49.com/v2/containers/{id}?include=shipment" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Token YOUR_API_KEY"
```

The shipment record — including `pod_eta_at`, `pod_original_eta_at`, and `destination_eta_at` — is returned in the top-level `included` array. See [Include related resources](/api-docs/in-depth-guides/including-resources) for the full syntax.

## Authentication

As in the previous steps, every request sends your API key in the `Authorization` header:
Expand Down
9 changes: 9 additions & 0 deletions docs/api-docs/webhooks/payloads.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,11 +115,20 @@ For events that do include the related records, the fields most integrations pul
| --- | --- |
| Event timestamp | Object with `type: "transport_event"` → `attributes.timestamp` |
| Estimated timestamp (ETA events) | Object with `type: "estimated_event"` or `type: "transport_event"` → `attributes.timestamp` (or `attributes.estimated_timestamp` on legacy `estimated_event` payloads) |
| Container ID | Object with `type: "container"` → `id` |
| Container number | Object with `type: "container"` → `attributes.number` |
| `pod_full_out_at`, `pod_arrived_at`, `pod_discharged_at`, `empty_terminated_at`, `pickup_lfd`, `available_for_pickup` | Object with `type: "container"` → `attributes.<field>` |
| Shipment ID | Object with `type: "shipment"` → `id` |
| Bill of lading number | Object with `type: "shipment"` → `attributes.bill_of_lading_number` |
| Reference numbers (`ref_numbers`) | Object with `type: "shipment"` → `attributes.ref_numbers` |

@greptile-apps greptile-apps Bot Jul 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Reference Numbers Read From Shipment

When webhook consumers use this extraction table, they will read ref_numbers from the included shipment object. The schema places ref_numbers on container attributes, so integrations built from this row can miss reference numbers that are present on the container.

Suggested change
| Reference numbers (`ref_numbers`) | Object with `type: "shipment"` → `attributes.ref_numbers` |
| Reference numbers (`ref_numbers`) | Object with `type: "container"` → `attributes.ref_numbers` |
Prompt To Fix With AI 
This is a comment left during a code review.
Path: docs/api-docs/webhooks/payloads.mdx
Line: 123

Comment:
**Reference Numbers Read From Shipment**

When webhook consumers use this extraction table, they will read `ref_numbers` from the included shipment object. The schema places `ref_numbers` on container attributes, so integrations built from this row can miss reference numbers that are present on the container.

```suggestion
| Reference numbers (`ref_numbers`) | Object with `type: "container"` → `attributes.ref_numbers` |
```

How can I resolve this? If you propose a fix, please make it concise.

Fix in Codex

| `pod_eta_at`, `pod_original_eta_at`, `destination_eta_at`, `pod_ata_at` | Object with `type: "shipment"` → `attributes.<field>` |
| Voyage number | Object with `type: "transport_event"` → `attributes.voyage_number` |
| Location UN/LOCODE | Object with `type: "transport_event"` → `attributes.location_locode` |

<Tip>
ETA fields (`pod_eta_at`, `pod_original_eta_at`, `destination_eta_at`) and identifiers like `bill_of_lading_number` live on the **shipment**, not the container. If you only see container fields in a payload, look for the object with `type: "shipment"` in `included`. For a full mapping, see [Which object holds which field?](/api-docs/getting-started/list-shipments-and-containers#which-object-holds-which-field).
</Tip>

## Container update changesets

For `container.updated` events, the event resource includes a `changeset` object. Each key is a changed field. The value is a two-item array: `[previous_value, current_value]`.
Expand Down
Loading