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

Refund object

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_f85f150c71c748649ec06d319a26e54c",
  "object": "Refund",
  "created_at": "2024-01-24T00:07:22Z",
  "updated_at": "2024-01-24T00:07:22Z",
  "tracking_code": "9405500207552011812764",
  "confirmation_number": null,
  "status": "submitted",
  "carrier": "USPS",
  "shipment_id": "shp_c3b0a61f204b4593a1ed98a3026dc4dc"
}

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_f85f150c71c748649ec06d319a26e54c",
4    "object": "Refund",
5    "created_at": "2024-01-24T00:07:22Z",
6    "updated_at": "2024-01-24T00:07:22Z",
7    "tracking_code": "9405500207552011812764",
8    "confirmation_number": null,
9    "status": "submitted",
10    "carrier": "USPS",
11    "shipment_id": "shp_c3b0a61f204b4593a1ed98a3026dc4dc"
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_f85f150c71c748649ec06d319a26e54c",
5      "object": "Refund",
6      "created_at": "2024-01-24T00:07:22Z",
7      "updated_at": "2024-01-24T00:07:22Z",
8      "tracking_code": "9405500207552011812764",
9      "confirmation_number": null,
10      "status": "submitted",
11      "carrier": "USPS",
12      "shipment_id": "shp_c3b0a61f204b4593a1ed98a3026dc4dc"
13    }
14  ],
15  "has_more": true
16}

Retrieve a Refund

Retrieve a Refund by its id.

Request Parameters

i.e. rfnd_abc1234

The ID of the refund to retrieve

GET /refunds/:id

1curl -X GET https://api.easypost.com/v2/refunds/rfnd_... \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "id": "rfnd_f85f150c71c748649ec06d319a26e54c",
3  "object": "Refund",
4  "created_at": "2024-01-24T00:07:22Z",
5  "updated_at": "2024-01-24T00:07:22Z",
6  "tracking_code": "9405500207552011812764",
7  "confirmation_number": null,
8  "status": "submitted",
9  "carrier": "USPS",
10  "shipment_id": "shp_c3b0a61f204b4593a1ed98a3026dc4dc"
11}