Update Order Status

mailhub_update_order_status

Move one Order to another fulfillment status, when that status change is what someone actually asked for — recording fulfillment progress, cancelling an Order that will not ship, or marking one returned.

Do not use it as preparation for something else. Rating and buying a Label never require a status change first.

Permission and safety


Changes data	Yes
Confirmation	Required — `confirm: true`
Spends funds	No
Permission	Update access to Orders

Confirmation is enforced by the server, and one call changes exactly one Order.

Input

Field	Type	Required	Notes
`orderId`	string	Yes	The Order's UUID
`newStatus`	string	Yes	The target status, by name — see the list below
`reason`	string	No	Recorded on the Order's status history; up to 500 characters
`confirm`	boolean	No	Defaults to `false`; the operation is refused unless the value is the boolean `true`

Statuses you can set

Created, OnHold, Cancelled, Fulfilled, Processing, Picked, Packed, Returned.

Anything else is refused with MCP_INVALID_VALUE, and the refusal lists the names above. Order Statuses carries the full set of twelve statuses, the transitions each one allows, and why the other four are not settable. In particular, Requested, LabelCreated, Error, and Draft are not settable here.

Example input

{
  "orderId": "11111111-1111-1111-1111-111111111111",
  "newStatus": "Packed",
  "reason": "Packed on the morning run",
  "confirm": true
}

Output

The updated Order state, carrying both the status name and its numeric code, so you can see which status was actually applied rather than only that a change went through.

Rules and common tool-specific errors

Mailhub checks that the move is legal from the Order's current status and applies it, recording the change — and your reason, if you gave one — on the Order's status history.

Not every move is legal from every status, and several are irreversible. An illegal move is refused, and where Mailhub can say so, the refusal names the statuses the Order can actually move to next — read it rather than guessing.
An Order that was put on hold resumes to the status it was held from, not to an arbitrary one.

Common tool-specific errors

Code	What it means	Retrying
`MCP_CONFIRMATION_REQUIRED`	The call did not carry `confirm: true`	Yes, confirming
`MCP_INVALID_VALUE`	`newStatus` is not one of the settable names	No — use a listed name
`MCP_INVALID_UUID`	`orderId` is not a UUID	No — fix the value
`Order.StatusTransitionNotAllowed`	Mailhub refused the status change	No — read the message and pick a target the Order accepts

Every refused status change arrives under that one code. The message says which case it is, and there is no per-case code to branch on:

The message says	What to do
The Order is already in that status	Nothing — carry on from where it is
The transition is not allowed, naming the reachable statuses	Pick one of those
`LabelCreated` is set when a Label is purchased	Buy a Label instead — that is what sets it
An Order with a purchased Label returns to `Packed` only by cancelling it	Cancel the Label
The Order cannot be cancelled directly while it holds a Label	Cancel the Label first, then cancel the Order
A draft Order's status cannot be set directly	Leave `Draft` alone
The Order was put on hold from a named status	Resume it to that status

Every code above, plus the access and shared failures this table does not cover, is listed in Errors & Troubleshooting.

Order Statuses — the transition rules behind every refusal on this page.
mailhub_cancel_label — required before cancelling an Order that has a Label.
Confirmations & Spend Safety — confirmation and the write-rate guard.

Permission and safety​

Input​

Statuses you can set​

Example input​

Output​

Rules and common tool-specific errors​

Common tool-specific errors​

Next​