Date intervals

Every Reporting API run needs a report type and a date interval. The interval picks which rows you export. This page covers how to set an interval the API accepts, how to choose output columns, and how idempotency keys work.

Discover what a report type accepts

Read a report type’s metadata before you build a create-run request. It tells you the columns the report type can output and the data window you can request.

cURL

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

Auth uses the ShippoToken header; see the authentication guide. This abbreviated response shows one available column:

{
  "report_type": "invoice.v1",
  "available_columns": [
    { "name": "invoice_object_id", "display_name": "invoice_object_id", "is_default": true }
  ],
  "data_availability": { "status": "ready", "start": 1701388800, "end": 1719360000, "updated": 1719363600 }
}

available_columns[] lists the columns this report type can output. is_default marks the columns selected when you omit columns from a run.
data_availability shows the data window you can request. start and end bound the window in UTC epoch seconds, and updated is when those bounds were last checked. A status of pending means the report type isn’t runnable yet.

Choose your columns

columns is optional. Leave it out and you get the columns where is_default is true. To choose the output explicitly, send a list of column name values from available_columns[]. The result keeps those columns in the order you submit. A column name that is not listed in available_columns returns 400 invalid-column.

Set a date interval

interval is required. It’s two integer UTC epoch seconds, not milliseconds and not ISO strings.

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

end has to be strictly greater than start. Equal or inverted bounds return 422 validation-error.
The span can’t exceed 92 days. Over the limit returns 400 invalid-parameter, and the message gives you the exact cap. For a longer span, split it into multiple runs.
The interval has to fall inside data_availability. Outside the ready window returns 404 data-unavailable.

Create a run

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 }
  }'

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "report_type": "invoice.v1",
  "interval": { "start": 1704067200, "end": 1706745600 },
  "columns": ["invoice_object_id", "invoice_number", "invoice_total_amount"],
  "output_format": "csv_gzip",
  "status": "QUEUED",
  "created": 1706745601
}

A run starts as QUEUED, moves to PROCESSING, then ends as SUCCEEDED or FAILED. Poll GET /v2/reporting/runs/{run_id} until it reaches one of those terminal states. The returned download URL is time-limited; fetch the run again to obtain a new URL. output_format is optional. Pick csv, csv_gzip, or parquet. Leave it out and you get csv_gzip.

Retry safely with an idempotency key

idempotency_key is an optional string you supply, 1 to 128 characters. It lets you retry a create without risking a duplicate run.

What you send	Result
No key, or a new unused key	`201 Created` and a fresh run (`status: QUEUED`)
The same key with the identical request	`200 OK` and the run you already created
The same key with a different request	`409` `idempotency-conflict`

Without a key, every create makes a new run, so reuse the key if you want a retry to be safe. With the same key and the identical request, you can replay as many times as you need. On a 409, pick a new key or send the original request.

Errors

After authentication, Reporting API errors use application/problem+json. Match errors on the last path segment of type, not the full URI. Handle authentication failures by their 401 HTTP status.

HTTP	`type` ends with	Cause
`400`	`invalid-column`	A column name is not listed in `available_columns`
`400`	`invalid-parameter`	Interval exceeds the 92-day cap, or a column is requested more than once
`401`	—	Missing or invalid token; handle by HTTP status
`404`	`report-type-not-found`	Unknown `report_type`
`404`	`data-unavailable`	Interval outside the report type’s data window
`404`	`run-not-found`	Unknown `run_id`
`409`	`idempotency-conflict`	Reused `idempotency_key` with a different request body
`422`	`validation-error`	`end` ≤ `start`, an unknown field, or a malformed body
`503`	`service-unavailable`	Temporary outage; retry later

Match Reporting API errors on the last path segment of type (e.g. invalid-parameter), not the full URI. Authentication failures may instead be 401 application/json; handle them by HTTP status.

A run can also fail after it is queued. That comes back as 200 OK with status: FAILED and an error object whose code is one of invalid_run_request, run_failed, run_processing_failed, run_timeout, or service_unavailable.

Overview

Get started

AI & agents

Guides

Concepts

Discover what a report type accepts

Choose your columns

Set a date interval

Create a run

Retry safely with an idempotency key

Errors

Next steps

Create and poll a report run

Reporting API reference

​Discover what a report type accepts

​Choose your columns

​Set a date interval

​Create a run

​Retry safely with an idempotency key

​Errors

​Next steps

Create and poll a report run

Reporting API reference

Discover what a report type accepts

Choose your columns

Set a date interval

Create a run

Retry safely with an idempotency key

Errors

Next steps