Docs
Sign in

cancel_shipment

Updated May 19, 20261 min read

Cancel a shipment. Optionally pass an update reason code to record why.

Parameters

NameTypeRequiredDescription
tenantIdstringYesThe tenant.
shipment_idstringYesCarriyo shipment ID or partner_shipment_reference.
update_reason_codestringNoReason code to record with the cancellation.

Reason codes

update_reason_code is one of the tenant's configured reason codes — the same set you'd use in the Dashboard. Examples typically include codes for customer cancelled, order edit, out of stock, etc.

The agent can omit the reason code in low-stakes cancels, but for ops or returns workflows the reason is usually load-bearing — downstream reports (report_exception_history, report_return_analytics) often slice by it.

Example agent prompts

"The customer changed their mind. Cancel SHP-12345."

cancel_shipment(
  tenantId="…",
  shipment_id="SHP-12345",
  update_reason_code="customer_cancelled"
)

"Just cancel the booking — no need to record a reason."

cancel_shipment(
  tenantId="…",
  shipment_id="SHP-12345"
)

What happens on cancel

  • The shipment moves to a CANCELLED status.
  • If the carrier was already booked, Carriyo notifies them (best effort — some carriers can't always cancel after pickup).
  • The label is invalidated.
  • reprocess_shipment — if you need to re-create a cancelled shipment with edits, use reprocess instead of cancel-then-create.
  • get_shipment — confirm current status before cancelling.
Cancellation isn't always free

Many carriers charge a cancellation fee if cancellation comes after a certain stage (label printed, picked up, etc.). The MCP cancel goes through regardless, but the cost is real. In customer-facing agents, surface this risk before firing.