Skip to content
/
Return list of reports

Reports API (v2)

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
https://api.goshippo.com

Reports

Use the Reports API to retrieve reports that have been scheduled or requested on demand. At the moment, only scheduled reports are supported.

  1. Use /v2/reports/{report_type_uuid}/runs to list the available reports.
  2. Use /v2/reports/{report_type_uuid}/runs/{report_run_uuid}/download to download the csv file of a report instance.
Operations

Return list of reports

Request

Returns a list of reports that can be downloaded.
A report type is a report that can be executed on a schedule and/or on demand. If you have requested Shippo a custom report, you will receive the report type UUID that represents that report type. With this report type UUID, you can call this endpoint to list all the available runs of your report.

Security
APIKeyHeader
Path
report_type_uuidstring(uuid)(Report Type UUID)required

UUID of the report type

Query
statusstring(ReportStatus)

Filters report runs by their current status. This is an optional parameter, but it's recommended setting it to SUCCEEDED if your integration doesn't handle the other statuses

Enum"QUEUED""PROCESSING""SUCCEEDED""FAILED"
modestring(ReportInstanceMode)

Filters results for only one report mode. (only scheduled reports are supported currently)

Enum"ON_DEMAND""SCHEDULED"
pagestring(Page)

Link to the next page

Example: page=bmV4dDs5MTsyMDI0LTA4LTA3VDE0OjQ1OjA4LjkyNzg1MSswMDowMA==
limitinteger(Limit)>= 1

The upper limit to the number of results returned

Default 10
curl -i -X GET \
'https://api.goshippo.com/v2/reports/{report_type_uuid}/runs?status=QUEUED&mode=ON_DEMAND&page=bmV4dDs5MTsyMDI0LTA4LTA3VDE0OjQ1OjA4LjkyNzg1MSswMDowMA==&limit=10' \
-H 'Authorization:  ShippoToken <API_TOKEN>'

Responses

Successful Response

Bodyapplication/json
resourcesArray of objects(Resources)
page_infoobject(PageInfo)

Link to the next page and previous page

Response
application/json
{
  "resources": [
    { … }
  ],
  "page_info": {
    "next": "bmV4dDs5MTsyMDI0LTA4LTA3VDE0OjQ1OjA4LjkyNzg1MSswMDowMA==",
    "prev": "cHJldjs5MjsyMDI0LTA5LTA1VDEzOjQwOjE1Ljk2NjY1NCswMDowMA=="
  }
}

Download report

Request

Returns a redirect URL to download the report file.
After processing the response from /runs endpoint, use the same report_type_uuid and the object_id of the report you want to retrieve.
A successful response returns a 302 status code. Your client should automatically follow the redirected link to download the file. Some clients, such as Swagger UI, can include the authorization header when following the redirected link. This will cause the request to fail with a 400 Bad Request response. To avoid this issue, ensure that the authorization header is removed when the client follows the redirected URL.

Security
APIKeyHeader
Path
report_type_uuidstring(uuid)(Report Type Uuid)required

UUID of the report type

report_run_uuidstring(uuid)(Report Run UUID)required

UUID of the report instance (object_id returned by /runs)

curl -i -X GET \
'https://api.goshippo.com/v2/reports/{report_type_uuid}/runs/{report_run_uuid}/download' \
-H 'Authorization: ShippoToken <API_TOKEN>'

Responses

Redirect to download URL

Headers
Locationstring(uri)

An URI to perform a HTTP GET to download the file content. It is RFC-7231 compliant: https://datatracker.ietf.org/doc/html/rfc7231#section-6.4.3

Example: {"signed_url":{"value":"https://s3.amazonaws.com/your-bucket/your-file","summary":"Redirect URI to download the file."}}
Response
No content