Order Statuses

A status refusal is not a failure of the connection or of permissions — it is Mailhub declining a move that would leave the Order and its Label describing different realities.

Exact values, and what you see on screen

Requests use the machine values in this page's tables — OnHold, LabelCreated, and the rest, spelled exactly as shown. Messages and the Mailhub application may render the same statuses as display text such as "On Hold" and "Label Created". Send the machine value; read either.

Status reference

An Order is in exactly one of twelve statuses. Each has a numeric code that travels with it, so a response usually carries both the name and the code.

Code	Status	What it means	Settable through MCP
0	Created	The Order exists and is ready to move through fulfillment	Yes
1	Requested	The Order has been submitted into the workflow	No
2	OnHold	Fulfillment is paused	Yes
3	Cancelled	The Order is cancelled	Yes
4	Fulfilled	Fulfillment is complete and the parcel has been handed over	Yes
5	Processing	Fulfillment work is under way	Yes
6	Picked	The items have been picked	Yes
7	Packed	The items have been packed	Yes
8	LabelCreated	A shipping Label has been bought for the Order	No — buying a Label is what sets it
9	Returned	The Order came back	Yes
10	Error	A technical state Mailhub sets itself	No
11	Draft	A work-in-progress Order in the Mailhub application	No

The codes are deliberately not renumbered to match the settable subset. They are a wire contract: the same number always means the same status.

Statuses you can set with MCP

mailhub_update_order_status accepts exactly these eight names:

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

Four statuses are never accepted by that tool:

Status	Why not
Requested	Nothing moves an Order into it on request
LabelCreated	Reached by buying a Label, not by asking for the status
Error	Technical, and set by Mailhub
Draft	A state of the application's Order wizard; MCP does not list or set it

Asking for any other value is refused, and the refusal lists the eight names above.

Valid transitions

Which move is legal depends on where the Order is now. This table is what an MCP user can ask for; Mailhub performs other changes itself as a consequence of operations such as buying or cancelling a Label.

Current status	You may move it to
Requested	Created, Cancelled
Created	Processing, Picked, Packed, OnHold, Cancelled
Processing	Picked, Packed, OnHold, Cancelled
Picked	Packed, OnHold, Cancelled
Packed	Cancelled
OnHold	The status it was held from, or Cancelled
LabelCreated	Fulfilled
Fulfilled	Returned
Cancelled	Nothing — the Order is closed
Returned	Nothing
Error	Nothing; Mailhub owns this state
Draft	Nothing through MCP

Fulfillment moves forward, and several steps are one-way. Cancelled and Returned are ends, not pauses.

Working with OnHold

Putting an Order on hold is easy to undo, but not to redirect.

An Order resumes to where it was held from

Resuming is not a free choice of status. Mailhub expects the Order to go back to the status it held before the hold — Created, Processing, or Picked, whichever it was. Asking for a different status is refused, and where Mailhub has the held-from status recorded, the refusal names the status to resume to. Read it rather than guessing.

An Order on hold can always be cancelled instead of resumed.

Buying a Label for an Order on hold is refused, and the refusal happens before any wallet activity — no funds are held or spent by the attempt. Resume the Order first, then buy.

Rating and buying need no status change

Neither has a status prerequisite

You do not need to move the Order to Packed, or to any other status, before asking for Rates or buying a Label. Both work from the Order as it stands. Older material that described a Packed prerequisite is not correct.

Buying is what moves the Order on: the purchase itself sets LabelCreated, which is why that status is not one you set. See mailhub_get_shipment_rates and mailhub_buy_label.

Buying a Label is	Order status
Allowed	Created, Processing, Picked, Packed, and Draft Orders in the application
Refused	Cancelled, OnHold, Fulfilled, Returned, and an Order that already has an active Label

Draft appears there only because it is not a blocker when it happens. A Draft belongs to the Mailhub application's Order wizard: MCP does not list Drafts and cannot set that status, so it is never a step you take deliberately.

An Order in LabelCreated moves on to Fulfilled when the parcel is handed to the carrier.

Cancelling an Order that already has a Label

An Order holding an active Label cannot be cancelled directly. Cancelling it while a bought Label stayed live with the carrier would leave the Order and the carrier describing different things — so Mailhub asks for the Label to be voided first.

Cancel the Label with mailhub_cancel_label, which returns the Order to Packed, then cancel the Order from there. Working with Labels walks the sequence through with the rest of the Label lifecycle.

Cancelling a Label is not a refund

A successful Label cancellation returns the Order to Packed. It does not automatically return funds to the wallet, and the original purchase still counts against the account's rolling 24-hour agent spend limit for that window.

Common refusals

What you asked for	What happens	What to do
The status the Order is already in	Refused as already in that status — it is not replayed as a no-op	Nothing; the Order is where you wanted it
A move the current status does not allow	Refused, and where Mailhub can say so the message names the statuses the Order can reach	Pick one of the named statuses
LabelCreated	Refused — it is not a settable status	Buy a Label instead
Cancelled for an Order with an active Label	Refused	Cancel the Label, then cancel the Order from Packed
A resume from OnHold to some other status	Refused	Resume to the status the Order was held from

The message on a refusal is the useful part: it usually names either what is blocking the change or what to ask for instead. Each tool page lists the refusals you are most likely to meet with that tool, and Errors & Troubleshooting carries the full catalog with each code's retry guidance.

Next

Apply a change with mailhub_update_order_status — the tool this page governs.

• Buying, waiting for, and cancelling a Label: Working with Labels.
• Reading a refusal: Errors & Troubleshooting.