update_shipment_status

Manually set a shipment status.

This is an administrative override tool. It is different from workflow actions like mark_ready_to_ship or cancel_shipment — it bypasses lifecycle logic and directly mutates the status.

Parameters

Name	Type	Required	Description
tenantId	string	Yes	The tenant.
shipment_id	string	Yes	Carriyo shipment ID or partner_shipment_reference.
new_status	string	Yes	Target status. Not every status is allowed from every current shipment state.
update_reason_code	string	No	Optional reason code when the tenant uses reason-code validation.
suppress_communication	boolean	No	Suppress customer communication triggered by this manual update.
update_date	string	No	ISO 8601 date-time to record as the effective status update time.

When this is the right tool

Rare. Examples:

• Reconciliation after a manual physical event the system never observed (carrier collected without callback, customer received without scan).
• Recovery from a state the lifecycle can't reach normally — e.g. marking a shipment delivered when the carrier doesn't return a delivery confirmation.
• One-off corrections of bad data.

If you find yourself reaching for this tool more than once a week, something is wrong with the lifecycle or carrier integration.

Example agent prompts

"The customer confirms they received SHP-12345 even though our tracking didn't pick it up. Mark it delivered."

update_shipment_status(
  tenantId="…",
  shipment_id="SHP-12345",
  new_status="delivered",
  update_reason_code="customer_confirmed"
)

Related tools

• mark_ready_to_ship — the proper way to mark ready-to-ship.
• cancel_shipment — the proper way to cancel.
• reprocess_shipment — the proper way to retry an errored shipment.

Notes

• Audit trail captures every override. Patterns of misuse are easy to spot in Integration Monitor.
• Customer-facing agents should not have this tool enabled. Restrict via the agent client (see Limits & security → tool-catalog restriction).