Refund unused Pirate Ship labels

1. On the Ship page, click the label in the grid; if it was part of a batch, click the batch first.
2. Click the red Refund Label button on the label. Inside a batch, Pirate Ship lets you refund single labels or the whole batch at once.
3. Check Reports > View Refund History for Pending Refunds, since printed USPS labels stay pending while USPS confirms they were never scanned.
4. To get the money back on the card, click Refund Credit under Account Balance on the Reports page; otherwise Pirate Ship spends it on your next labels.
5. Spotting the duplicates and the cancelled orders is the slow part: the grid has no view of "bought twice" or "order cancelled in the store", so you compare lists by eye.

Find labels I bought twice for the same order and labels for the orders I cancelled this week, check none of them has been scanned, and refund them.

1. 01

   Build the list of suspects

   The agent calls list_shipments with since set 28 days back, the window in which Pirate Ship still accepts a refund. It flags two shipments to the same recipient with the same Order ID, and matches the cancelled orders you name, or that your store export shows, against the Order ID and recipient columns.

2. 02

   Keep the one label that will ship

   For a duplicate pair, the agent keeps the label already printed or already on a SCAN Form and proposes refunding the other one. When both look identical it asks you which one is taped to the box.

3. 03

   Skip what can no longer be refunded

   get_shipment shows the tracking status. A label with a carrier scan is treated as used and dropped from the list, and so is a return label, which is charged only if used. Anything past day 28 is left to Pirate Ship's Auto-Refund.

4. 04

   Ask before each refund, because it is final

   Pirate Ship cannot cancel a refund request, and a refunded label must never go on a parcel. The agent shows the list and calls refund_label only for the ones you approve, then reminds you to throw those printed labels away.

5. 05

   Report where the money is

   get_account_balance afterwards shows what landed in your Account Balance and what is still pending with USPS, so the run ends with the amount refunded and the amount still waiting.

Checked 212 labels bought since 14 Sep.
Duplicates: order #1061 to R. Patel (2 labels, kept the printed one), refunded s_84C001, $7.12, instant.
Cancelled orders: #1058 refunded (UPS Ground, $11.40, approval within about an hour); #1063 refunded (USPS, printed, pending).
Skipped: #1047, already scanned by USPS on 9 Oct.
Account Balance now $96.02, Pending Refunds $8.45.
Throw away the printed labels for #1061 (second copy) and #1063.

• Pirate Ship removes the Refund Label button once the Ship Date is more than 28 days old or USPS or UPS has scanned the package.
• A refund request in Pirate Ship cannot be cancelled. If the label is needed after all, the help center says to make a new one with Duplicate Shipment.
• UPS prefers labels used soon after purchase. Pirate Ship warns that a refunded or reused UPS label sends the parcel to a UPS Overgoods facility, where UPS holds packages that cannot be recovered.
• Pirate Ship credits approved refunds to the Account Balance, and Refund Credit on the Reports page can send it only to a payment method you have spent at least that amount through. Pirate Ship processes these refunds within 3 to 7 business days.
• Return labels in Pirate Ship cannot be refunded because they are charged only when used.

refund_label asks for your OK by default. To run it weekly without you, switch confirmation off for that tool in your dashboard.

Sources: Can I get a refund if I make a mistake or don't need a label anymore? · How do auto-refunds work? · Why can't I refund my label? · How do I cancel a refund request? · Can I get my account balance refunded to my payment method? · How does the eBay integration work?

curl https://cotlet.dev/api/v1/pirate-ship/refund_label \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shipment_id":"s_84C001"}'

{
  "shipment_id": "s_83F2A1",
  "carrier": "USPS",
  "status": "refunded",
  "amount_usd": 7.12,
  "credited_to": "Account Balance"
}

MCP: add https://cotlet.dev/mcp/v1 with the same key; the tool is pirate-ship_refund_label. Example data.

• Buy Pirate Ship shipping labels in bulk
• Create a Pirate Ship SCAN Form and book a pickup
• Pirate Ship API and MCP server: every tool
• All use cases