Cancel Label

mailhub_cancel_label

Cancel a Label that has been bought, voiding it with the carrier and returning the Order to Packed — because the Label was wrong, or because the Order itself has to be cancelled.

Permission and safety

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

Confirmation is enforced by the server.

Input

Field	Type	Required	Notes
labelId	string	Yes	The Label's UUID
confirm	boolean	No	Defaults to false; the operation is refused unless the value is the boolean true

The Label identifier appears on the Order — see mailhub_list_orders and mailhub_get_order.

Example input

{
  "labelId": "44444444-4444-4444-4444-444444444444",
  "confirm": true
}

Output

There is no data payload. A successful call means Mailhub accepted and completed the cancellation; the Order's new state is visible through mailhub_get_order.

Rules and common tool-specific errors

Mailhub voids the Label with the carrier, clears the Shipment's tracking and carrier selection, and moves the Order back to Packed so it can be re-rated, bought again, or cancelled.

Cancelling is not a refund

Cancelling a Label does not automatically return funds to the wallet, and the original purchase still counts toward the account's rolling 24-hour agent spend limit for that window. Do not tell anyone their money is back on the strength of a successful cancellation.

• Cancelling the same Label twice is safe. An already-cancelled Label is not sent to the carrier again; the call simply succeeds.
• Whether a Label can be voided at all is the carrier's rule, not Mailhub's. A carrier that refuses the void is reported as such.
• A cancelled Label can no longer be downloaded. Buy a new one if the Shipment still needs a Label.

Common tool-specific errors

Code	What it means	Retrying
MCP_CONFIRMATION_REQUIRED	The call did not carry confirm: true	Yes, confirming
MCP_INVALID_UUID	labelId is not a UUID	No — fix the value
MCP_WRITE_RATE_LIMITED	Too many changing calls for the account just now	Yes, shortly

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

Next

• Working with Labels — the two-step sequence for cancelling an Order that has a Label.
• mailhub_buy_label — buy a replacement Label.
• Confirmations & Spend Safety — why a cancellation is not a refund.