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