API Docs

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
Endpoints
POST
/reports/:type
GET
/reports/:type
GET
/reports/:id

Report object

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
Report Object
{
  "id": "shprep_4a6f6e7e1b8a4794b5395008c89625be",
  "object": "ShipmentReport",
  "created_at": "2024-01-24T00:07:24Z",
  "updated_at": "2024-01-24T00:07:24Z",
  "start_date": "2022-10-01",
  "end_date": "2022-10-01",
  "mode": "test",
  "status": "new",
  "url": null,
  "url_expires_at": null,
  "include_children": false
}

Create a 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 30 seconds. 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.

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

Request Parameters

start_date
i.e. 2016-11-02
Required
end_date
i.e. 2016-12-02
Required
include_children
i.e. false
Optional, defaults to false
send_email
i.e. true
Optional, defaults to false
columns
i.e. ["shipment_id", "usps_zone"]
Optional, can use to specify the exact columns you want in your report
additional_columns
i.e. ["usps_zone"]
Optional, can use to request additional columns (if any) outside of the defaults
POST /reports/:type
1curl -X POST https://api.easypost.com/v2/reports/payment_log \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "start_date": "2022-10-01",
6    "end_date": "2022-10-31"
7  }'
Response
1{
2  "id": "shprep_4a6f6e7e1b8a4794b5395008c89625be",
3  "object": "ShipmentReport",
4  "created_at": "2024-01-24T00:07:24Z",
5  "updated_at": "2024-01-24T00:07:24Z",
6  "start_date": "2022-10-01",
7  "end_date": "2022-10-01",
8  "mode": "test",
9  "status": "new",
10  "url": null,
11  "url_expires_at": null,
12  "include_children": false
13}

Retrieve all Reports

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.

Request Parameters

before_id
i.e. shprep_...
Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.
after_id
i.e. shprep_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
page_size
i.e. 30
The number of records to return on each page. The maximum value is 100, and default is 20.
GET /reports/:type
1curl -X GET "https://api.easypost.com/v2/reports/payment_log?page_size=5" \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "reports": [
3    {
4      "id": "shprep_82ee56b0b96247528187f3f9b4fa1360",
5      "object": "ShipmentReport",
6      "created_at": "2024-01-24T00:07:24Z",
7      "updated_at": "2024-01-24T00:07:24Z",
8      "start_date": "2022-10-01",
9      "end_date": "2022-10-01",
10      "mode": "test",
11      "status": "empty",
12      "url": null,
13      "url_expires_at": null,
14      "include_children": false
15    }
16  ],
17  "has_more": true
18}

Retrieve a Report

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

GET /reports/:id
1curl -X GET https://api.easypost.com/v2/reports/plrep_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "shprep_82ee56b0b96247528187f3f9b4fa1360",
3  "object": "ShipmentReport",
4  "created_at": "2024-01-24T00:07:24Z",
5  "updated_at": "2024-01-24T00:07:24Z",
6  "start_date": "2022-10-01",
7  "end_date": "2022-10-01",
8  "mode": "test",
9  "status": "new",
10  "url": null,
11  "url_expires_at": null,
12  "include_children": false
13}