Track a shipment

This guide is handwritten MDX in the same Starlight project as the generated reference. It explains the workflow; the generated pages describe each method and field.

Look up the shipment

Call GetShipment with your shipment identifier. For this local example, use shp_123.

{
  "shipmentId": "shp_123",
  "includeEvents": true
}

The generated GetShipmentRequest lists the complete request contract. Its include_events field has explicit presence, so an omitted value remains distinguishable from an explicit false.

Read the current state

The response contains a Shipment. Check its status before starting any application action that depends on delivery. This example is a documentation fixture, and has no authorization or payment behavior.

The weight_mg field is a 64-bit integer in Protobuf and a decimal string in ProtoJSON. The id field uses the explicit JSON name shipmentId. Both representations come from the schema.

Subscribe to progress

Use WatchShipment to receive a stream of ShipmentEvent messages. The example server emits an in-transit event followed by a delivery event and then completes.

Use a generated client to handle framing, errors, and cancellation. See the Connect protocol guide for the distinction between decoded JSON messages and a complete stream on the wire.

Run the example

From the repository:

npm run example:server

Then copy a request from the generated method reference. The source comments on the service and GetShipment link back to this application guide.