Discover available reports

The Reporting API catalog tells you what you can run before you run it. Each report type entry includes:

a stable key (for example invoice.v1)
a name and description
the columns it can return
the date range its data covers

Read the catalog first, then use those values to create a run. See the authentication guide for token setup.

List available report types

GET /v2/reporting/reports returns the full active catalog as a single items array. There’s no pagination. Discovery returns only active report types. The version is part of the report_type key (for example invoice.v1).

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": 1672531200,
        "end": 1706745600,
        "updated": 1706748000
      }
    }
  ]
}

Use the report_type value (for example invoice.v1) as the key when you create a run.

Get one report type

GET /v2/reporting/reports/{report_type} returns a single catalog entry. It has the same shape as one items entry above. An unknown key returns 404 (problem type report-type-not-found).

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

Columns

available_columns lists every column the report type can return.

Field	Use
`name`	The slug you pass in the `columns` array when you create a run.
`display_name`	The catalog-provided display label. Don’t submit it as a column name.
`is_default`	Whether the column is included when you omit `columns` from a create-run request.

Pass a columns array to select a subset. Each column you pass must be one of the report type’s available_columns. Omit the array to get the default set. Column order in the output file matches the order you submit.

Available date range

data_availability describes the window you can query. All timestamps are integer UTC epoch seconds. The date-range interval is the only filter on a run.

`status`	Meaning
`ready`	Data is queryable between `start` and `end`. `updated` is when those bounds were last checked.
`pending`	The window is still being computed. No interval is valid yet.

Reporting API data is refreshed periodically throughout the day, so recent invoice activity may not appear immediately. Interval rules when you create a run:

end must be strictly greater than start. Otherwise you get 422 (problem type validation-error).
The max span is 92 days. Exceeding it returns 400 (problem type invalid-parameter). Split larger ranges into multiple runs.
The interval must fall inside the ready window. An out-of-window or pending request returns 404 (problem type data-unavailable).

Here’s a January 2024 run against the window above (start 2023-01-01, end 2024-02-01):

{ "interval": { "start": 1704067200, "end": 1706745600 } }

Next steps

Create and poll a report run

Submit a run, poll until it reaches SUCCEEDED, and download the signed file.

Reporting API reference

Full request and response schemas for every endpoint.

Overview

Get started

AI & agents

Guides

Concepts

List available report types

Get one report type

Columns

Available date range

Next steps

Create and poll a report run

Reporting API reference

​List available report types

​Get one report type

​Columns

​Available date range

​Next steps

Create and poll a report run

Reporting API reference

List available report types

Get one report type

Columns

Available date range

Next steps