Identify the Shippo Transaction object_id for the label to be voided
POST to https://api.goshippo.com/refunds/ with the transaction field set to the Transaction object_id
Check the response status field; a value of QUEUED means the refund request has been submitted to the carrier for approval
Poll GET https://api.goshippo.com/refunds/{refund_id}/ or listen for a refund.updated webhook event to confirm the refund is APPROVED or REJECTED
Reconcile approved refund amounts against your billing records; note that Shippo's per-label fee may not be refunded, only the carrier postage
Ensure the refund request is submitted within 90 days of label purchase, as requests after that window are rejected by carriers
Known gotchas
USPS no longer automatically refunds unused labels; you must explicitly create a refund request — labels not used and not refunded will be charged in full
Some carriers (e.g. FedEx, UPS) require the label to have never been scanned into their network; a label that was accepted and then returned may be denied a refund
Refund approval is asynchronous and carrier-dependent; building logic that treats a QUEUED refund as approved will cause accounting discrepancies when the carrier ultimately rejects it
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