edit_draft_shipment

Patch a draft shipment before it is confirmed for booking.

Only draft shipments can be edited through this tool. Once a shipment is confirmed (booked with a carrier), edits go through different tools (reprocess_shipment, reassign_shipment, or status override).

Parameters

Name	Type	Required	Description
tenantId	string	Yes	The tenant.
shipment_id	string	Yes	Carriyo shipment ID or partner_shipment_reference.
carrier_account, references, payment, pickup, dropoff, items, parcels, freight, ...	mixed	Yes	One or more shipment fields to patch.

Patch fields

Pass only the fields you want to change at the top level of the tool arguments. The server merges them with the existing draft. Common patches:

• Address corrections: { "dropoff": { "address1": "…", "city": "…" } }
• Parcel updates: { "parcels": [...] } (replaces the array)
• Reference changes: { "partner_shipment_reference": "…" }
• Carrier choice: { "carrier_account": { "carrier_id": "…" } }

For nested objects, the merge depth depends on the field. Test once to confirm whether deep-merging or array-replacing applies for the field you're patching.

Example agent prompts

"Wait, the postcode should be 11564 not 11546."

edit_draft_shipment(
  tenantId="…",
  shipment_id="<draft id>",
  dropoff={ "postcode": "11564" }
)

"Make it 3 boxes instead of 2."

edit_draft_shipment(
  tenantId="…",
  shipment_id="<draft id>",
  parcels=[{ "quantity": 3, "weight": 1.5 }]
)

Related tools

• create_shipment (with draft=true) — produces the draft this tool edits.
• confirm_shipment — book the draft once it's right.
• get_shipment — fetch the current draft state to inspect before patching.

Notes

• Only drafts. If the shipment has been confirmed, this tool will fail. Use the right tool for the lifecycle stage instead.
• The agent should typically call get_shipment before edit_draft_shipment if it's been a while since the draft was created — the user may have already changed something through another channel.