get_shipment

Get a single shipment by ID. Supports select (json-mask syntax) to return only the fields the agent needs.

This is the most frequently called read tool. Agents typically use it as the entry point for any flow that operates on a specific shipment — diagnose, edit, cancel, reschedule, label.

Parameters

Name	Type	Required	Description
tenantId	string	Yes	The tenant the shipment belongs to. Resolve this via get_accessible_tenants first.
shipment_id	string	Yes	The shipment's Carriyo ID.
select	string	No	json-mask syntax to return only the fields you need (e.g. "shipment_id,status,tracking_no,dropoff(address1,city)"). Reduces payload size in chat contexts.

Returns

The full shipment record:

• Identifiers — shipment_id, tracking_no, carrier, carrier_account_name.
• Lifecycle — status, status timestamps.
• Parties — pickup, dropoff, merchant, customer.
• Logistics — parcels[], items[], dimensions, weight, service level.
• Money — payment (currency, amounts).
• Promised vs actual — promised pickup / delivery dates, actual dates.

Shipment payloads are large. Best practice: list one shipment without select once to learn the structure, then use select on subsequent calls to fetch only what the agent needs.

Example agent prompt

"Look up shipment SHP-12345 and tell me where it is."

The agent will resolve the tenant via get_accessible_tenants, call get_shipment(tenantId="…", shipment_id="SHP-12345", select="status,tracking_no,carrier,dropoff(city,country)"), and reply in plain English.

A more elaborate prompt:

"Pull SHP-12345 with full details and tell me what's gone wrong."

Drop the select so the agent has the full record (payment, items, logistics) to reason over.

Related tools

• get_shipment_list — when you don't know the ID and need to search. Requires a date range.
• get_shipment_activity — Carriyo-internal activity timeline (creation, status changes, rule assignments, notifications).
• list_shipment_system_logs — carrier-side diagnostic logs for the same shipment.

Common chains

• Diagnose a stuck shipment — get_shipment → get_shipment_activity → list_shipment_system_logs. See Diagnose a stuck shipment.
• Reschedule — get_shipment → schedule_delivery.
• Reassign carrier — get_shipment → reassign_shipment.
• Why did it route this way? — get_shipment → (find ruleset id) → get_automation_ruleset → list_automation_rules.