Orders tools

11 tools for the top-level order entity. Fulfillment-order operations (splits, merges, location moves, scheduling, fulfilling, shipping) are in the separate Fulfillment orders family.

Reads

Tool	What it returns
get_order	One order by Carriyo order_id or partner_order_reference.
list_orders	Orders with paging, sorting, search, merchant filters, and hold filters.
list_order_hold_rules	The rules that put new orders on hold automatically.
get_order_hold_rule	One order hold rule, with its conditions and hold action.

Writes

Tool	What it does
create_order	Create a new order.
edit_order	Patch root order fields. To change items, use the fulfillment-order tools.
cancel_order	Cancel an order and all its fulfillment orders.
hold_order	Put an order on hold for review, with an assignee, priority and SLA.
release_order_hold	Release the hold on an order and on its held fulfillment orders.
fulfill_order	Fulfill every pending item on the order, one shipment per fulfillment order.
unfulfill_order	Reverse every fulfillment on the order and cancel its shipments.

Working the on-hold queue

An order is put on hold by a person, or automatically by an order hold rule when it is created. While an order is on hold, every update is rejected except cancel_order and release_order_hold.

Tool sequence: list_orders with status on_hold, sorted by on_hold_details.sla_timestamp → read on_hold_details on each order (who holds it, why, and the rule_id for an automatic hold) → get_order_hold_rule to see the rule that fired → release_order_hold or cancel_order.

Limits to plan for:

• An active hold cannot be changed. To change its assignee, priority or notes, release the hold and call hold_order again; the new hold is recorded as a MANUAL hold, and the earlier one moves to on_hold_details.history.
• An order cannot be edited while it is on hold. Release it first, then call edit_order.
• release_order_hold only works when the order itself is on hold. When only one fulfillment order is held, use release_fulfillment_order_hold.
• get_order_hold_rule returns 404 for a rule that has since been deleted.

Order hold rules are read-only over MCP — editing them stays in the Dashboard.

Related families

• Fulfillment orders. The operational actions: split, merge, fulfill, ship, cancel items, change location / delivery method, schedule.
• Shipments. Once a fulfillment order ships, the resulting shipment is the unit of carrier interaction.