Identify the label_id of the label to void from your label purchase response or by querying GET /v1/labels with your order reference filter
Call PUT /v1/labels/:label_id/void; check the response approved field: true means the carrier accepted the void, false means the void was rejected (commonly because the label has already been scanned into the carrier network)
If the void is rejected, check the message field for the rejection reason; common reasons include carrier cutoff exceeded, package already inducted, or carrier does not support API void
For USPS labels, the postage refund is credited back to your postage balance within 2-5 business days after void; for FedEx and UPS, the refund timeline depends on carrier contract terms and may take 1-2 billing cycles
Store the void response with the original label ID, void timestamp, approved status, and rejection reason; update the shipment status in your OMS to VOIDED or VOID_REJECTED accordingly
For void-rejected labels that were never physically used, file a manual postage refund request directly with the carrier or through your carrier account representative with the label ID and proof of non-use
Known gotchas
UPS and FedEx have a same-day void window before end-of-day carrier pickup; labels for shipments already tendered to the driver cannot be voided via API even if no tracking scan has occurred yet, because the carrier considers the shipment inducted at tender
USPS SCAN form (manifest) closure finalizes all labels in that manifest for that day; attempting to void a USPS label after the manifest has been submitted will return approved true in the ShipEngine API but the refund may be denied by USPS during their reconciliation process
International labels from DHL Express and FedEx International cannot be voided via the ShipEngine void endpoint after the shipment has been transmitted to the carrier's booking system, even if the package has not physically moved; void must be initiated through the carrier's own cancellation API
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp