Reporting API Quickstart

Reporting API turns your Shippo account data into downloadable CSV or Parquet files. Reports run asynchronously, so you create a run, poll until it finishes, then download the file. All endpoints live under https://api.goshippo.com/v2/reporting. Pass Authorization: ShippoToken <API_TOKEN> on every request. See the Authentication guide for token setup. All timestamps are integer UTC epoch seconds.

1. Discover a report type

A report type is a predefined report identified by a versioned key like invoice.v1. List the catalog:

curl https://api.goshippo.com/v2/reporting/reports \
  -H "Authorization: ShippoToken <API_TOKEN>"

This abbreviated response shows one report type and three of its available columns:

{
  "items": [
    {
      "report_type": "invoice.v1",
      "name": "invoice",
      "category": "invoices",
      "description": "One row per Invoice Item for invoice reconciliation, with optional label, shipment, order-reference, insurance, refund, and address context.",
      "available_columns": [
        { "name": "invoice_object_id", "display_name": "invoice_object_id", "is_default": true },
        { "name": "invoice_number", "display_name": "invoice_number", "is_default": true },
        { "name": "invoice_total_amount", "display_name": "invoice_total_amount", "is_default": true }
      ],
      "data_availability": {
        "status": "ready",
        "start": 1704067200,
        "end": 1719360000,
        "updated": 1719360000
      }
    }
  ]
}

Two fields drive how you build a run:

The available_columns field lists the column names you can request. Submit each column’s name. Omit columns on create and you get the report’s default set.
The data_availability field tells you the window you can query. When status is ready, your interval must fall inside the start and end window, and updated shows when those bounds were last checked (UTC epoch seconds). When status is pending, a create request returns 404 data-unavailable.

To inspect a single report type, call GET /v2/reporting/reports/{report_type}.

2. Create a run

A run is one async execution of a report type over a time interval. Set interval to {start, end} in epoch seconds.

end must be strictly greater than start, or you get a 422.
A run can span up to 92 days. Going past a report type’s limit returns 400 invalid-parameter.

curl https://api.goshippo.com/v2/reporting/runs \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "invoice.v1",
    "interval": { "start": 1704067200, "end": 1706745600 },
    "columns": ["invoice_object_id", "invoice_number", "invoice_total_amount"],
    "output_format": "csv_gzip",
    "idempotency_key": "invoices-jan-2024-001"
  }'

{
  "id": "3f1c9a7e-4d2b-4e8a-9c1f-2b6d8e0a5c11",
  "report_type": "invoice.v1",
  "interval": { "start": 1704067200, "end": 1706745600 },
  "columns": ["invoice_object_id", "invoice_number", "invoice_total_amount"],
  "output_format": "csv_gzip",
  "created": 1706745601,
  "status": "QUEUED"
}

You get 201 Created with status: QUEUED. Keep the id; you need it to poll and download.

output_format accepts csv, csv_gzip (the default), or parquet.
columns is optional. If you include it, it can’t be empty.
Unknown body fields are rejected with 422.

Safe retries with idempotency_key. This field is optional: a string of 1 to 128 characters that you choose. Send a new key, or none at all, and you get 201 Created with a brand-new run. Retry with the same key and the same request body, and you get the original run back as 200 OK instead of a duplicate. Reuse a key with a different body and you get a 409 with the idempotency-conflict type. Without a key, every create makes a new run, so set one whenever a retry might fire twice.

3. Poll until the run finishes

curl https://api.goshippo.com/v2/reporting/runs/3f1c9a7e-4d2b-4e8a-9c1f-2b6d8e0a5c11 \
  -H "Authorization: ShippoToken <API_TOKEN>"

A run moves through these states:

`status`	Terminal	Meaning
`QUEUED`	No	Queued; not started.
`PROCESSING`	No	Generating the report.
`SUCCEEDED`	Yes	Done. `result.download` contains the URL.
`FAILED`	Yes	Could not complete. `error.code` says why.

Poll until the run reaches SUCCEEDED or FAILED.

A run with status: FAILED comes back as HTTP 200 with status: FAILED, not an HTTP error. Read error.code to handle it.

On failure, error.code is one of:

`error.code`	Meaning
`invalid_run_request`	The run request is invalid.
`run_timeout`	The run exceeded its processing time limit.
`run_processing_failed`	Data processing failed.
`run_failed`	The run could not be completed.
`service_unavailable`	The service was temporarily unavailable.

4. Download the file

On SUCCEEDED, result.download takes one of two shapes:

{ "status": "available", "url": "...", "expires": <epoch_s> } means the file is ready. Send a GET request to url; a Shippo Authorization header is not required.
{ "status": "unavailable" } means a signed URL is not currently available. Fetch the run again to obtain a new URL.

curl -o invoices.csv.gz \
  "https://<download-host>/<opaque-path>?<signature>"

The URL is time-limited. Read its expires field for the exact cutoff. Fetch the run again to obtain a new URL and expiry.

List your runs

curl "https://api.goshippo.com/v2/reporting/runs?limit=20" \
  -H "Authorization: ShippoToken <API_TOKEN>"

Runs come back newest-first. limit defaults to 50 and ranges from 1 to 500. List responses don’t include signed download URLs. GET a succeeded run by id to mint one.

Error reference

Reporting API 4xx and 5xx responses use application/problem+json, except authentication failures, which use 401 application/json with a detail field. Match problem responses on the last path segment of type, not its full URL.

`type` segment	HTTP	When
—	401	Token missing or unverified; handle by HTTP status.
`invalid-column`	400	A requested column is not in `available_columns`.
`invalid-parameter`	400	Bad interval or duplicate requested column.
`report-type-not-found`	404	No such report type key.
`data-unavailable`	404	Interval outside the ready window.
`run-not-found`	404	No run with that id.
`idempotency-conflict`	409	Reused an `idempotency_key` with a different request body.
`validation-error`	422	Malformed body or unexpected field.
`service-unavailable`	503	Temporary; retry.

Overview

Get started

AI & agents

Guides

Concepts

1. Discover a report type

2. Create a run

3. Poll until the run finishes

4. Download the file

List your runs

Error reference

Next steps

Reporting API reference

Authentication

​1. Discover a report type

​2. Create a run

​3. Poll until the run finishes

​4. Download the file

​List your runs

​Error reference

​Next steps

Reporting API reference

Authentication

1. Discover a report type

2. Create a run

3. Poll until the run finishes

4. Download the file

List your runs

Error reference

Next steps