Shipments tools

Updated May 21, 20262 min read

16 tools covering the full shipment lifecycle. Click a tool name for parameters, returns, and example agent prompts.

Server-published guardrails

Two rules every agent should follow when calling shipment tools:

Tenant safety. Call get_accessible_tenants first; validate any user-requested tenant against the result before invoking shipment tools.
get_shipment_list date range. creation_date_from and creation_date_to are required. Default to last 30 days; max range 90 days.

Create and edit

Tool	What it does
`create_shipment`	Create a shipment, optionally as draft (`draft=true`). Reliable inputs typically include merchant, references, payment, pickup, dropoff, items.
`edit_draft_shipment`	Patch a draft shipment before it is confirmed.
`confirm_shipment`	Confirm a draft or errored shipment for booking. Pass changes to update the shipment as part of the confirm.
`cancel_shipment`	Cancel a shipment. Optionally pass an update reason code.
`reprocess_shipment`	Reprocess a shipment in error / cancelled / returned status.
`reassign_shipment`	Reassign or retry an unshipped or errored shipment.

Status and lifecycle

Tool	What it does
`mark_ready_to_ship`	Move a shipment into the ready-to-ship workflow. Business action — not a status patch.
`update_shipment_status`	Manually set a shipment status. Administrative override; discouraged for normal flows.

Pickup, delivery, and labels

Tool	What it does
`schedule_collection`	Set or revise the shipment collection schedule.
`schedule_delivery`	Set or revise the shipment delivery schedule.
`update_customer_promise_date`	Revise the customer-promise date — what the customer sees in tracking, distinct from the carrier delivery schedule.
`refresh_label`	Refresh the shipping label.

Read

Tool	What it does
`get_shipment`	Get a single shipment by ID. Supports `select` (json-mask) to trim the response.
`get_shipment_list`	List shipments. Requires `creation_date_from` / `creation_date_to`; max 90-day range. Supports `select` and a long set of filters.
`get_shipment_activity`	Activity timeline (creation, status changes, rule assignments, notifications, customer feedback).

Rates and quoting

Tool	What it does
`get_shipping_rates`	Carrier rate quotes for a shipment-like payload. Works from raw order data without needing an existing shipment.

Notes

Many tools accept select (json-mask syntax) to return only the fields the agent needs. Useful for keeping responses small in chat contexts.
get_shipment_list payloads are large — list a single shipment first to learn the structure, then filter with select.
For diagnostic context on a stuck shipment, pair these tools with the System logs family.