`create_shipment`

Updated May 29, 20262 min read

Create a shipment, optionally as a draft.

The starting point for any "I want to ship this" flow. Reliable inputs usually include merchant, references, payment, pickup, dropoff, and items.

Parameters

Name	Type	Required	Description
`tenantId`	string	Yes	The tenant to create the shipment in.
`draft`	boolean	No	`true` creates a draft (editable, not booked). `false` (or omitted) creates and confirms in one call.
`references`	object	Yes	Shipment references. Must include `partner_order_reference`; `partner_shipment_reference` is strongly recommended.
`payment`	object	Yes	Payment payload. Must include `total_amount` and `currency`.
`pickup`	object	Yes	Pickup address or saved-location reference.
`dropoff`	object	Yes	Delivery address or saved-location reference.
`items`	array	Yes	Shipment line items.
`merchant`	string	Usually	Merchant ID. Required unless the tenant has exactly one active merchant.
`parcels` / `freight`	array / object	Usually	Package details. Use one of these for reliable booking.

Shipment fields

The shape of a shipment is large. Common fields the agent should populate:

merchant — required for routing. Resolve from get_merchants.
partner_shipment_reference — your external reference (order id, customer reference). Strongly recommended; idempotency depends on it.
pickup — { location_id } if pulling from a configured location, or a full address.
dropoff — full delivery address with contact info.
parcels — [{ quantity, weight, length, width, height }].
items — line items with descriptions, quantities, prices.
payment — { currency, payment_on_delivery? } for COD.
delivery_type — resolve from get_delivery_types.
order_type — resolve from get_order_types.
attributes — custom attributes if the merchant uses them (get_custom_attributes).

For the canonical full schema, list one shipment with get_shipment and inspect the shape — easier than enumerating every optional field here.

`draft=true` vs `draft=false`

Mode	Behaviour	Use when
`draft=true`	Creates an editable shipment record. No carrier booking.	The agent wants a chance to review before booking, or an OMS that creates ahead of fulfillment.
`draft=false` (default)	Creates and confirms in one call — the carrier is booked.	The agent has full information and is ready to commit.

Example agent prompts

"Create a shipment from our Dubai warehouse to Sara at 25 Maple Street, Riyadh — 2 boxes, AED 350 COD."

The agent resolves merchant + delivery type, builds the shipment fields, and calls create_shipment(...) with draft=false.

"Save this as a draft so I can review the rate before booking."

Same call with draft=true. Follow up with confirm_shipment once the user is happy.

get_shipping_rates — quote rates before creating, so the agent can pick the cheapest / fastest carrier for the user.
edit_draft_shipment — patch a draft before confirming.
confirm_shipment — book a draft.

Common chain

Quote and create from natural language — the canonical multi-tool flow that wraps this tool.

Confirm before booking

draft=false books a carrier and incurs real fees. In any agent that creates on behalf of a non-trusted user, require an explicit confirmation before calling with draft=false — or use draft=true

confirm_shipment so there's a clear booking moment.

create_shipment