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

---

## Refund object

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique, begins with "rfnd_" |
| object | string | "Refund" |
| 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 |

Example Object:

```json
[
  {
    "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

### Example: POST /refunds

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/refunds \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "refund": {
      "carrier": "USPS",
      "tracking_codes": [
        "EZ1000000001"
      ]
    }
  }'
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func create() {
	client := easypost.New("EASYPOST_API_KEY")

	refunds, _ := client.CreateRefund(
		map[string]interface{}{
			"carrier":        "USPS",
			"tracking_codes": []string{"EZ1000000001"},
		},
	)

	fmt.Println(refunds)
}
```

#### Java

```java
package refunds;

import com.easypost.exception.EasyPostException;
import com.easypost.model.Refund;
import com.easypost.service.EasyPostClient;

import java.util.HashMap;

public class Create {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        HashMap<String, Object> params = new HashMap<String, Object>();
        params.put("carrier", toAddressMap);
        params.put("tracking_codes", Arrays.asList(new String[] { "EZ1000000001" }));

        List<Refund> refunds = client.refund.create(params);

        System.out.println(refunds);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.Refund.Create parameters = new()
            {
                Carrier = "USPS",
                TrackingCodes = new List<string> { "EZ1000000001" }
            };

            List<EasyPost.Models.API.Refund> refunds = await client.Refund.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(refunds, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const refund = await client.Refund.create({
    carrier: 'USPS',
    tracking_codes: ['EZ1000000001'],
  });

  console.log(refund);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$refunds = $client->refund->create([
    'carrier' => 'USPS',
    'tracking_codes' => ['EZ1000000001'],
]);

echo $refunds;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

refunds = client.refund.create(
    carrier="USPS",
    tracking_codes=["EZ1000000001"],
)

print(refunds)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

refunds = client.refund.create(
  carrier: 'USPS',
  tracking_codes: ['EZ1000000001'],
)

puts refunds
```

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.

[Note: This object is immutable after creation. Review the rendered documentation for details.]

---

## Retrieve all Refunds

### Example: GET /refunds

#### cURL

```shell
curl -X GET "https://api.easypost.com/v2/refunds?page_size=5" \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func list() {
	client := easypost.New("EASYPOST_API_KEY")

	refunds, _ := client.ListRefunds(
		&easypost.ListOptions{
			PageSize: 5,
		},
	)

	fmt.Println(refunds)
}
```

#### Java

```java
package refunds;

import com.easypost.exception.EasyPostException;
import com.easypost.model.RefundCollection;
import com.easypost.service.EasyPostClient;

import java.util.HashMap;

public class All {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        HashMap<String, Object> params = new HashMap<>();
        params.put("page_size", 5);

        RefundCollection refunds = client.refund.all(params);

        System.out.println(refunds);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.Refund.All parameters = new()
            {
                PageSize = 5
            };

            EasyPost.Models.API.RefundCollection refundCollection = await client.Refund.All(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(refundCollection, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const refunds = await client.Refund.all({
    page_size: 5,
  });

  console.log(refunds);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$refunds = $client->refund->all([
    'page_size' => 5,
]);

echo $refunds;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

refunds = client.refund.all(
    page_size=5,
)

print(refunds)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

refunds = client.refund.all(
  page_size: 5,
)

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

---

## Retrieve a Refund

### Example: GET /refunds/:id

#### cURL

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

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func retrieve() {
	client := easypost.New("EASYPOST_API_KEY")

	refund, _ := client.GetRefund("shp_...")

	fmt.Println(refund)
}
```

#### Java

```java
package refunds;

import com.easypost.exception.EasyPostException;
import com.easypost.model.Refund;
import com.easypost.service.EasyPostClient;

public class Retrieve {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        Refund refund = client.refund.retrieve("rfnd_...");

        System.out.println(refund);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Models.API.Refund refund = await client.Refund.Retrieve("rfnd_...");

            Console.WriteLine(JsonConvert.SerializeObject(refund, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const refund = await client.Refund.retrieve('rfnd_...');

  console.log(refund);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$refund = $client->refund->retrieve('rfnd_...');

echo $refund;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

refund = client.refund.retrieve("rfnd_...")

print(refund)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

refund = client.refund.retrieve('rfnd_...')

puts refund
```

Retrieve a `Refund` by its `id`.