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

[mintlify]

Summary

Clarify which tracking fields live on the shipment resource versus the container resource, addressing a recurring source of confusion in developer questions about ETA and milestone fields.

Changes

• Added a "Which object holds which field?" reference table to the List Shipments and Containers guide, mapping common fields (pod_eta_at, pod_original_eta_at, destination_eta_at, pod_full_out_at, pickup_lfd, etc.) to the correct endpoint.
• Documented how to embed the shipment record when fetching a container using ?include=shipment.
• Expanded the "Extracting common fields from included" table in Webhook Payloads to cover container milestone fields and shipment ETA fields, with a callout linking back to the field-placement reference.

Context

Multiple recent developer questions asked why pod_eta_at / pod_original_eta_at / destination_eta_at were missing from GET /containers responses, and where to find container milestone fields like pod_full_out_at in webhook payloads. The docs described these fields in scattered places but did not offer a single reference of which object owns which field.

Greptile Summary

This PR clarifies where common tracking fields live in the docs. The main changes are:

• A shipment-versus-container field reference table.
• Guidance for using include=shipment on container requests.
• Expanded webhook included extraction guidance for ETA and milestone fields.

Confidence Score: 4/5

The documentation update is close, but the ref_numbers lookup path needs a fix before merging.

• ref_numbers is documented as a shipment field in the guide.
• The webhook table tells consumers to read ref_numbers from the shipment object.
• Existing schema context places ref_numbers on container attributes, so both rows can lead integrations to the wrong object.

docs/api-docs/getting-started/list-shipments-and-containers.mdx; docs/api-docs/webhooks/payloads.mdx

Important Files Changed

Filename	Overview
docs/api-docs/getting-started/list-shipments-and-containers.mdx	Adds the field-placement guide and container include example, with one row pointing ref_numbers at the wrong resource.
docs/api-docs/webhooks/payloads.mdx	Expands webhook extraction guidance, with ref_numbers documented under the wrong included object.

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
docs/api-docs/getting-started/list-shipments-and-containers.mdx:38
**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}` |
```

### Issue 2 of 2
docs/api-docs/webhooks/payloads.mdx:123
**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` |
```

_{Reviews (1): Last reviewed commit: "docs: clarify shipment vs. container fie..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Building	Preview, Comment	Jul 13, 2026 4:10pm

[greptile-apps]

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.

[greptile-apps]

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.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
terminal49	🟢 Ready	View Preview	Jul 13, 2026, 4:29 PM