Reporting API overview

The Reporting API turns your Shippo account data into downloadable CSV or Parquet files. Pick a report type, request a time interval, and Reporting API builds the file for you. The work happens asynchronously, so you create a run, poll until it’s ready, then download it. See the Authentication guide for token setup.

Report types

A report type is a predefined report identified by a versioned key ({name}.v{version}).

`report_type`	Covers
`invoice.v1`	Account invoices, charges, and refunds

Call GET /v2/reporting/reports to fetch the live catalog. It returns the currently active report types and their available columns. See Discover available reports.

Endpoints

Base URL: https://api.goshippo.com

Method	Path	Purpose
`GET`	`/v2/reporting/reports`	List active report types
`GET`	`/v2/reporting/reports/{report_type}`	Columns and data window
`POST`	`/v2/reporting/runs`	Create an async run
`GET`	`/v2/reporting/runs`	List your recent runs
`GET`	`/v2/reporting/runs/{run_id}`	Get or poll one run

An unknown run_id returns a 404.

Run states

Reporting API uses uppercase run statuses to match Shippo’s existing reports API lifecycle vocabulary.

`status`	Meaning	Terminal
`QUEUED`	Queued, not built yet	No
`PROCESSING`	Generating	No
`SUCCEEDED`	File ready, download URL attached	Yes
`FAILED`	Could not complete, `error` attached	Yes

A run with status: FAILED is HTTP 200 with status: FAILED, not an HTTP error. Read the error object to handle it.

There’s no webhook. Poll GET /v2/reporting/runs/{run_id} until the run reaches a terminal status.

Example flow

1. Create a run. Set interval.start and interval.end in UTC epoch seconds. end must be greater than start, otherwise you get a 422. A single run can span up to 92 days; a longer window returns 400 invalid-parameter.

cURL

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 },
    "output_format": "csv_gzip"
  }'

You get 201 Created with status: QUEUED.

Idempotency is opt-in. Send an optional idempotency_key, any string of 1 to 128 characters, to make retries safe. Reuse the same key with the same request and you get the existing run back as HTTP 200 instead of a duplicate. Reuse the same key with a different request and you get a 409 (idempotency-conflict). Skip the key and every create starts a new run, so there’s no automatic deduplication.

2. Poll until terminal.

cURL

curl https://api.goshippo.com/v2/reporting/runs/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: ShippoToken <API_TOKEN>"

Once the run reaches SUCCEEDED, the response includes result.download.url.

The download URL expires at result.download.expires, expressed as a UTC epoch second. If it expires, fetch the run again for a new URL.

3. Download. Send a GET request to result.download.url. A Shippo Authorization header is not required for this request.

cURL

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

See Download report files.

Errors

Reporting API errors use RFC 7807 application/problem+json, except authentication failures, which use 401 application/json with a detail field. Match problem responses on the trailing error-code segment of type, since its host can change. Common codes:

Code	HTTP	When
`invalid-column`	400	A requested column is not in the report type’s catalog
`invalid-parameter`	400	Bad interval or out-of-range window (over 92 days)
`validation-error`	422	Malformed request, such as `end` not greater than `start`
`idempotency-conflict`	409	Reused an `idempotency_key` with a different request
`service-unavailable`	503	Temporary outage; retry later

A run with status: FAILED comes back as HTTP 200 with status: FAILED, and its error object carries a failure code: invalid_run_request, run_failed, run_processing_failed, run_timeout, or service_unavailable. Other statuses you may see: 401, 404. See Errors and run failures.

Next steps

Quickstart: create, poll, and download your first report
Create and poll a run: retry details and polling patterns
API reference: full endpoint and schema reference

Overview

Get started

AI & agents

Guides

Concepts

Report types

Endpoints

Run states

Example flow

Errors

Next steps

​Report types

​Endpoints

​Run states

​Example flow

​Errors

​Next steps

Report types

Endpoints

Run states

Example flow

Errors

Next steps