> ## 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.

# Migrate from the Invoice API

> Map each Invoice API field to a Reporting API invoice.v1 column.

The Invoice API returns JSON objects from `/invoices` and `/invoice-items`.
Reporting API returns a file.
Each file row is one invoice item.
The row also contains the invoice, the transaction, and the label context.

The report type key contains the version.
This guide maps to `invoice.v1`.
A new report version gets a new key.

## Get invoice data from Reporting API

1. Create a run with `POST /v2/reporting/runs`. Set `report_type` to `invoice.v1`.
2. Poll `GET /v2/reporting/runs/{run_id}` until `status` is terminal.
3. Download the file from `result.download.url`.

Select your columns in the run request.
Call `GET /v2/reporting/reports/invoice.v1` to list all columns.
See the [Quickstart](/reporting-api/quickstart) for full request examples.

## Map invoice fields

| Invoice API (`/invoices`) | `invoice.v1` column           | Type          |
| ------------------------- | ----------------------------- | ------------- |
| `object_id`               | `invoice_object_id`           | string        |
| `shippo_account`          | `payer_shippo_account_id`     | string        |
| `invoice_number`          | `invoice_number`              | string        |
| `status`                  | `invoice_status`              | string        |
| `invoice_closed`          | `invoice_ready_for_charge_at` | timestamp     |
| `invoice_paid_date`       | `invoice_paid_at`             | timestamp     |
| `total_invoiced.amount`   | `invoice_total_amount`        | decimal(12,2) |
| `total_invoiced.currency` | `invoice_currency`            | string        |
| `total_charged.amount`    | `invoice_charged_amount`      | decimal(12,2) |

## Map invoice item fields

| Invoice API (`/invoice-items`) | `invoice.v1` column             | Type          |
| ------------------------------ | ------------------------------- | ------------- |
| `object_created`               | `invoice_item_created_at`       | timestamp     |
| `shippo_account`               | `shippo_account_id`             | string        |
| `type`                         | `invoice_item_type`             | string        |
| `description`                  | `invoice_item_description`      | string        |
| `amount`                       | `invoice_item_amount`           | decimal(12,2) |
| `currency`                     | `invoice_item_currency`         | string        |
| `charge_conversion.rate`       | `invoice_item_charge_fx_rate`   | decimal(15,6) |
| `charge_conversion.time`       | `invoice_ready_for_charge_at`   | timestamp     |
| `charge_conversion.amount`     | `invoice_item_charged_amount`   | decimal(12,2) |
| `charge_conversion.currency`   | `invoice_item_charged_currency` | string        |
| `invoice`                      | `invoice_object_id`             | string        |
| `transaction`                  | `transaction_object_id`         | string        |

## Map query filters

A run supports one filter: the date interval.
Apply all other filters to the downloaded file.

| Invoice API filter    | Reporting API method                               |
| --------------------- | -------------------------------------------------- |
| Date range            | Set `interval.start` and `interval.end` on the run |
| `?invoiceObjectId=`   | Filter the file on `invoice_object_id`             |
| `?invoiceNumber=`     | Filter the file on `invoice_number`                |
| `?shippoAccountId=`   | Filter the file on `shippo_account_id`             |
| `?type=`              | Filter the file on `invoice_item_type`             |
| `?page=`, `?results=` | Not needed. One run returns one complete file.     |

Refund and credit rows have negative `invoice_item_amount` and `invoice_item_charged_amount` values. Charges have positive values.
To find return labels, filter the file on `is_return`.

## Fields with no direct match

| Invoice API field             | Note                                                                                      |
| ----------------------------- | ----------------------------------------------------------------------------------------- |
| Invoice `object_created`      | No direct column. Use `invoice_ready_for_charge_at` for the reporting lifecycle boundary. |
| Invoice `object_updated`      | No direct column.                                                                         |
| Invoice item `object_updated` | No direct column.                                                                         |
| `next` / `previous`           | No pagination. The file is complete for the interval.                                     |

## Behavior differences

* The Invoice API returns all invoice statuses. `invoice.v1` excludes open and write-off invoices. Rows appear after the invoice is ready for charge.
* The Invoice API returns one object per invoice. `invoice.v1` returns one row per invoice item. Invoice fields repeat on each row. Group rows on `invoice_object_id` to rebuild an invoice.
* Reporting API data is refreshed periodically throughout the day, so recent invoice activity may not appear immediately.
* Amounts are decimal columns, not strings.
* One run covers up to 92 days. Create more runs for a longer period.

## Next steps

* [Quickstart](/reporting-api/quickstart): create, poll, and download your first report
* [Discover available reports](/reporting-api/discover-reports): read the `invoice.v1` column catalog
* [Errors and run failures](/reporting-api/errors): handle error responses


## Related topics

- [Migrating from Platform API to Shippo API](/platform-accounts/platform-api-migrate.md)
- [Address validation](/address-api/address-validate.md)
- [Reporting API overview](/reporting-api/overview.md)