# Refund unused Pirate Ship labels

> Duplicate and cancelled-order labels found in Pirate Ship and refunded before the carrier scans them, instead of waiting 28 days for Auto-Refund.

Source: https://cotlet.dev/integrations/pirate-ship-api-mcp-server/refund-unused-labels

A customer cancels after the label is printed, or a batch gets bought twice after a browser hang. The money sits in that label until someone opens it on the Ship page, and nobody remembers which ones by Friday.

Cotlet does it in your own Pirate Ship account with list\_shipments, get\_shipment, refund\_label and get\_account\_balance, called by your AI agent, an n8n workflow or a script.

[Request access](https://cotlet.dev/app/signup?app=pirate-ship) [All Pirate Ship tools](https://cotlet.dev/integrations/pirate-ship-api-mcp-server)

Hosted · nothing to install or maintain

Official options

## Can Pirate Ship do this on its own?

Pirate Ship has no API for refunds (checked 12 Oct 2026). Its own Auto-Refund feature requests a refund for every unused USPS and UPS label 28 days after purchase, so forgotten labels are not lost. The gap is time: an unprinted USPS label refunds instantly when you ask on day one, while Auto-Refund holds the money for four weeks and printed USPS labels can wait up to 28 days more for approval.

By hand

## How you do it in Pirate Ship today

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.

With an agent

## How to refund unused Pirate Ship labels

Prompt

```
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.

### What you get back

Example data

```
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.
```

### Other ways to ask

- Every Friday, refund UPS labels that are more than 7 days old and still unscanned, and tell me which orders need a new label.
- Refund the whole batch b\_7Q4K2M except the three labels already scanned.
- List every pending refund older than two weeks with its order number, without refunding anything new.

Before you automate it

## What Pirate Ship allows, and what to know first

- 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?](https://support.pirateship.com/en/articles/1068139-can-i-get-a-refund-if-i-make-a-mistake-or-don-t-need-a-label-anymore) · [How do auto-refunds work?](https://support.pirateship.com/en/articles/3535545-how-do-auto-refunds-work) · [Why can't I refund my label?](https://support.pirateship.com/en/articles/3397134-why-can-t-i-refund-my-label) · [How do I cancel a refund request?](https://support.pirateship.com/en/articles/4140680-how-do-i-cancel-a-refund-request) · [Can I get my account balance refunded to my payment method?](https://support.pirateship.com/en/articles/1068149-can-i-get-my-account-balance-refunded-to-my-payment-method) · [How does the eBay integration work?](https://support.pirateship.com/en/articles/1199665-how-does-the-ebay-integration-work)

REST

## Call refund\_label from a script

curl

```
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"}'
```

Example response

```
{
"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.

[Schedule it in n8n, Make, Zapier or cron](https://cotlet.dev/integrations/pirate-ship-api-mcp-server#automations)

Tools

## Pirate Ship tools this automation uses

__Cotlet Pirate Ship tools used to refund unused Pirate Ship labels__
| Tool | Parameters |
| --------------------- | -------------------------------------- |
| list\_shipments | search, status, service, since, cursor |
| get\_shipment | shipment\_id |
| refund\_label | shipment\_id |
| get\_account\_balance | none |

[All 14 Pirate Ship tools with descriptions](https://cotlet.dev/integrations/pirate-ship-api-mcp-server#tools)

## Frequently asked questions

### Does refunding an eBay order's label put the order back in the Import grid?

No. Pirate Ship cannot set an eBay order back to Unshipped, so after a refund the order no longer appears on the Import page. If it still has to ship, create a single label and copy the tracking number into eBay by hand.

### Can the agent send the refunded money back to my card?

No. Cotlet has no tool for Refund Credit. Approved refunds stay in your Account Balance and pay for your next labels, or you click Refund Credit on the Reports page yourself.

## More Pirate Ship automations

- [Buy Pirate Ship shipping labels in bulk](https://cotlet.dev/integrations/pirate-ship-api-mcp-server/buy-shipping-labels-in-bulk)
- [Create a Pirate Ship SCAN Form and book a pickup](https://cotlet.dev/integrations/pirate-ship-api-mcp-server/scan-form-and-pickup)
- [Pirate Ship API and MCP server: every tool](https://cotlet.dev/integrations/pirate-ship-api-mcp-server)
- [All use cases](https://cotlet.dev/use-cases)

## Give your agent access to Pirate Ship.

Free 7-day trial with 5,000 credits, no card needed. Cotlet is independent and not affiliated with Pirate Ship.

[Request access](https://cotlet.dev/app/signup?app=pirate-ship)