Identify the shipment ID for the label you wish to void; it is the 'id' field on the shipment object returned at creation or purchase time.
POST /v2/shipments/{shipment_id}/refund with an empty body (no payload required); the response updates the shipment 'refund_status' field.
Possible 'refund_status' values include 'submitted', 'refunded', 'rejected', and 'not_applicable'; 'submitted' means the request is pending carrier approval.
Poll GET /v2/shipments/{shipment_id} periodically to check if 'refund_status' has progressed to 'refunded' — this can take days depending on the carrier.
If 'refund_status' is 'rejected', the carrier declined the refund (e.g., the label was already scanned); do not retry automatically without investigating the reason.
Known gotchas
Labels that have been scanned by the carrier cannot be voided; only unscanned labels (never dropped off) are eligible for postage refunds.
Refund timelines vary by carrier — USPS refunds may take weeks while FedEx and UPS are typically faster; EasyPost credits the refund to your account balance, not back to the original payment method.
EasyPost insurance purchased alongside the label is not automatically refunded when voiding; insurance must be handled separately.
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