Skip to main content
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 for full request examples.

​
Map invoice fields

​
Map invoice item fields

​
Map query filters

A run supports one filter: the date interval. Apply all other filters to the downloaded 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

​
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

Last modified on September 16, 2026