> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Shippo is a multi-carrier shipping API. For agent integrations that execute shipping operations (rates, labels, tracking, address validation, customs), connect the hosted Shippo MCP server at https://mcp.shippo.com (per-user OAuth; setup at /guides/mcp-server). To search and read this documentation from an agent, a docs search MCP is available at https://docs.goshippo.com/mcp. Shipping workflow knowledge (agent skills and a knowledge pack) is published at https://github.com/goshippo/ai. For REST integrations start at /guides/api-quickstart; test mode uses shippo_test_ API keys.

# Discover available reports

> List the report types you can run, and read their columns and date ranges from the Reporting API catalog.

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](/guides/authentication) 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`).

```shell theme={null}
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:

```json theme={null}
{
  "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`).

```shell theme={null}
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):

```json theme={null}
{ "interval": { "start": 1704067200, "end": 1706745600 } }
```

## Next steps

<CardGroup cols={2}>
  <Card title="Create and poll a report run" icon="play" href="/reporting-api/create-and-poll">
    Submit a run, poll until it reaches `SUCCEEDED`, and download the signed file.
  </Card>

  <Card title="Reporting API reference" icon="code" href="/api-reference/reports/list-report-types">
    Full request and response schemas for every endpoint.
  </Card>
</CardGroup>


## Related topics

- [Reporting API overview](/reporting-api/overview.md)
- [Migrate from the Invoice API](/reporting-api/migrate-from-invoice-api.md)
- [Reporting API Quickstart](/reporting-api/quickstart.md)