API Docs

Refund

The Refund object represents a refunded shipment, and includes details about the related Shipment and tracking code.

USPS shipping labels can be refunded if requested within 30 days of generation. The processing time is at least 15 days, after which the funds will return to your EasyPost balance. EasyPost fees will also be refunded. To qualify, a shipment must not have been scanned by the USPS.

UPS and FedEx shipping labels may be refunded within 90 days of creation.

Endpoints
POST
/refunds
GET
/refunds
GET
/refunds/:id

Refund object

id
string
Unique, begins with "rfnd_"
object
string
"Refund"
tracking_code
string
The tracking code of the related Shipment
confirmation_number
string
The confirmation number for the refund request to the carrier
status
string

The status of the refund request, reported by the carrier. Possibe values:

  • "submitted"
  • "refunded"
  • "rejected"
carrier
string
The carrier the refund request was submitted to
shipment_id
string
The ID of the related Shipment being refunded
created_at
datetime
When the Refund was created
updated_at
datetime
When the Refund was last updated
Refund Object
{
  "id": "rfnd_92d852c508204fc3a34e62977eaa6c50",
  "object": "Refund",
  "created_at": "2025-05-09T20:40:01Z",
  "updated_at": "2025-05-09T20:40:01Z",
  "tracking_code": "9405500208303109884137",
  "confirmation_number": null,
  "status": "submitted",
  "carrier": "USPS",
  "shipment_id": "shp_744d6715c6794d8c8cd0874c368878ba"
}

Create a Refund

This endpoint is intended to be used to bulk-process multiple refunds; as a result, this endpoint will return a list of Refund objects.

To refund a single shipment, use the Refund a Shipment endpoint instead.

A Refund object is immutable once created. All information must be provided during creation; it cannot be modified later.

Request Parameters

carrier
i.e. USPS
The carrier to request a refund from
tracking_codes
i.e. ["EZ10000001"]
A list of tracking codes to request refunds for. Even for a single tracking code, it needs to be submitted as a list.
POST /refunds
1curl -X POST https://api.easypost.com/v2/refunds \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "refund": {
6      "carrier": "USPS",
7      "tracking_codes": [
8        "EZ1000000001"
9      ]
10    }
11  }'
Response
1[
2  {
3    "id": "rfnd_92d852c508204fc3a34e62977eaa6c50",
4    "object": "Refund",
5    "created_at": "2025-05-09T20:40:01Z",
6    "updated_at": "2025-05-09T20:40:01Z",
7    "tracking_code": "9405500208303109884137",
8    "confirmation_number": null,
9    "status": "submitted",
10    "carrier": "USPS",
11    "shipment_id": "shp_744d6715c6794d8c8cd0874c368878ba"
12  }
13]

Retrieve all Refunds

A list of all Refund objects associated with the given API Key can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

before_id
i.e. rfnd_...
Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.
after_id
i.e. rfnd_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
start_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created after this timestamp. Defaults to 1 month ago, or 1 month before a passed end_datetime.
end_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime.
page_size
i.e. 20
The number of records to return on each page. The maximum value is 100, and default is 20.
GET /refunds
1curl -X GET "https://api.easypost.com/v2/refunds?page_size=5" \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "refunds": [
3    {
4      "id": "rfnd_92d852c508204fc3a34e62977eaa6c50",
5      "object": "Refund",
6      "created_at": "2025-05-09T20:40:01Z",
7      "updated_at": "2025-05-09T20:40:01Z",
8      "tracking_code": "9405500208303109884137",
9      "confirmation_number": null,
10      "status": "submitted",
11      "carrier": "USPS",
12      "shipment_id": "shp_744d6715c6794d8c8cd0874c368878ba"
13    }
14  ],
15  "has_more": false
16}

Retrieve a Refund

Retrieve a Refund by its id.

GET /refunds/:id
1curl -X GET https://api.easypost.com/v2/refunds/rfnd_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "rfnd_92d852c508204fc3a34e62977eaa6c50",
3  "object": "Refund",
4  "created_at": "2025-05-09T20:40:01Z",
5  "updated_at": "2025-05-09T20:40:01Z",
6  "tracking_code": "9405500208303109884137",
7  "confirmation_number": null,
8  "status": "submitted",
9  "carrier": "USPS",
10  "shipment_id": "shp_744d6715c6794d8c8cd0874c368878ba"
11}