# Report

A `Report` contains a CSV that is a log of all the objects created within a certain time frame.

`Reports` can be generated using the `Reports` endpoint.
You can create and view `Reports` created between any time frame defined between the `start_date` and `end_date`.

The `Report` API can be categorized into several types.
These types determine which EasyPost Object to produce a `Report` for, and should be passed as either the `type` in our client libraries or at the end of the URL.

#### Report Types

- `cash_flow`
- `insurance`
- `payment_log`
- `refund`
- `shipment`
- `shipment_invoice`
- `tracker`

---

## Report object

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique, begins with one of the following prefixes: "cfrep_" (Cash Flow Report) "insrep_" (Insurance Report) "plrep_" (Payment Log Report) "refrep_" (Refund Report) "shprep_" (Shipment Report) "shpinvrep_" (Shipment Invoice Report) "trkrep_" (Tracker Report) |
| object | string | Possible values: "CashFlowReport" "InsuranceReport" "PaymentLogReport" "RefundReport" "ShipmentReport" "ShipmentInvoiceReport" "TrackerReport" |
| mode | string | "test" or "production" |
| status | string | Possible values: "new" "available" "failed" "empty" null |
| start_date | string | A date string in YYYY-MM-DD form, e.g.: "2016-02-02" |
| end_date | string | A date string in YYYY-MM-DD form, e.g.: "2016-02-03" |
| include_children | boolean | Set true if you would like to include Insurances , Refunds , Shipments , ShipmentInvoices, or Trackers created by child users. |
| url | string | A URL that contains a link to the Report. Expires 30 seconds after retrieving this object. |
| url_expires_at | datetime | Time at which the URL expires |
| send_email | boolean | Set true if you would like to send an email containing the Report. |
| created_at | datetime | When the Report was created |
| updated_at | datetime | When the Report was last updated |

Example Object:

```json
{
  "columns": null,
  "created_at": "2025-05-09T20:40:02Z",
  "end_date": "2022-10-01",
  "id": "shprep_846a44b4d34e47afb14a1783d463d02d",
  "include_children": null,
  "mode": "test",
  "object": "ShipmentReport",
  "start_date": "2022-10-01",
  "status": "new",
  "updated_at": null,
  "url": null,
  "url_expires_at": null,
  "utc_offset": null
}
```

---

## Create a Report

### Example: POST /reports/:type

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/reports/payment_log \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "start_date": "2022-10-01",
    "end_date": "2022-10-31"
  }'
```

#### Go

```go
package example

import (
	"fmt"

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

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

	reportOptions := &easypost.Report{
		StartDate: "2022-10-01",
		EndDate:   "2022-10-31",
	}

	report, _ := client.CreateReport(
		"payment_log",
		reportOptions,
	)

	fmt.Println(report)
}
```

#### Java

```java
package reports;

import com.easypost.exception.EasyPostException;
import com.easypost.model.Report;
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("type", "payment_log");
        params.put("start_date", "2022-10-01");
        params.put("end_date", "2022-10-31");

        Report report = client.report.create(params);

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

#### 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.Report.Create parameters = new()
            {
                Type = "payment_log",
                StartDate = "2022-10-01",
                EndDate = "2022-10-31"
            };

            EasyPost.Models.API.Report report = await client.Report.Create(parameters);

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const report = await client.Report.create({
    type: 'payment_log',
    start_date: '2022-10-01',
    end_date: '2022-10-31',
  });

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

#### PHP

```php
<?php

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

$report = $client->report->create([
    'type' => 'payment_log',
    'start_date' => '2022-10-01',
    'end_date' => '2022-10-31',
]);

echo $report;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

report = client.report.create(
    type="payment_log",
    start_date="2022-10-01",
    end_date="2022-10-31",
)

print(report)
```

#### Ruby

```ruby
require 'easypost'

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

report = client.report.create(
  type: 'payment_log',
  start_date: '2022-10-01',
  end_date: '2022-10-31',
)

puts report
```

To create a `Report`, provide a `start_date` and `end_date` that are less than 31 days apart along with any other optional parameter that you would like to specify.
A detailed list of attributes are provided below.

The expiry on a URL is 1 hour.
The default status on each new `Report` is "new".
It changes to "available" if the CSV file is created successfully, "failed" when CSV creation is unsuccessful, or "empty" if the report does not include any data for the specified date range.
Additionally, null could also be a status.

When a `Report`'s status changes, an `Event` will be sent to registered `Webhook` URLs.
See our Webhooks Guide for help on `Event` handling.

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

---

## Retrieve all Reports

### Example: GET /reports/:type

#### cURL

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

#### Go

```go
package example

import (
	"fmt"

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

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

	report, _ := client.GetReport("<REPORT_TYPE>", "<REPORT_ID>")

	fmt.Println(report)
}
```

#### Java

```java
package reports;

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

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

        Report report = client.report.retrieve("<REPORT_ID>");

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

#### 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.Report report = await client.Report.Retrieve("plrep_...");

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const report = await client.Report.retrieve('<REPORT_ID>');

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

#### PHP

```php
<?php

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

$report = $client->report->retrieve('<REPORT_ID>');

echo $report;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

report = client.report.retrieve("<REPORT_ID>")

print(report)
```

#### Ruby

```ruby
require 'easypost'

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

report = client.report.retrieve('<REPORT_ID>')

puts report
```

A list of all `Report` 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 Report

### Example: GET /reports/:id

#### cURL

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

#### Go

```go
package example

import (
	"fmt"

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

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

	report, _ := client.GetReport("<REPORT_TYPE>", "<REPORT_ID>")

	fmt.Println(report)
}
```

#### Java

```java
package reports;

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

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

        Report report = client.report.retrieve("<REPORT_ID>");

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

#### 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.Report report = await client.Report.Retrieve("plrep_...");

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const report = await client.Report.retrieve('<REPORT_ID>');

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

#### PHP

```php
<?php

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

$report = $client->report->retrieve('<REPORT_ID>');

echo $report;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

report = client.report.retrieve("<REPORT_ID>")

print(report)
```

#### Ruby

```ruby
require 'easypost'

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

report = client.report.retrieve('<REPORT_ID>')

puts report
```

Retrieve a `Report` by its `id`. See object definition for possible _id_ prefixes.