Create reports

Sign in Hub
Get help
Create reports
Create, track, and download API v2 CSV reports for invoices, subscriptions, and tax data by report type and date range with Bearer authentication

Use reports API v2 to export subscription, invoice, payment, and tax data as a CSV file.

Each report covers one report_type and one date range, with date_from inclusive and date_to exclusive. The table shows the date field each report type uses to select records.

TypeDate usedDescription
INVOICES Creation dateInvoice line items, with one row per line item. Covers invoice content, such as billed products and amounts, not payment details.
SUBSCRIPTIONS Creation dateSubscriptions, with one row per subscription line item.
TAX_TRANSACTIONAL Processing dateTax line items, with one row per tax line item.
INVOICE_PAYMENTS Creation dateInvoice payments, with one row per payment. Covers payment amount and method, not invoice line item details.
TAX_SUMMARY Processing dateTax totals, with one row per legal entity, tax jurisdiction, tax rate, tax currency, and processing currency combination.

Account and channel scope
anchor

The API credentials used to create the report determine its account and channel scope. By default, a report covers the entire account. If the credentials are limited to specific channels, the report includes a parameters.channel_ids array instead.

To create and download a report

  1. Use the create report API v2 request.
    • Set report_type to one of the report types listed above.
    • Pass date_from and date_to.
  2. Save the report id from the response. Processing is asynchronous and starts in PROCESSING status.
  3. Use one of the following requests to track report processing:
    • get report API v2 with the report id to check its status until status is no longer PROCESSING . The response includes the report only if the API key has access to it.
    • list reports API v2 with report_type to filter reports and check the status of multiple reports without specifying a single id.
  4. Use the download report API v2 request with the report id. A successful response returns a 303 redirect to a short-lived download URL in the Location header.
The download request can return the following status codes:

  • 303 - redirect to a short-lived download URL
  • 404 - report not found
  • 422 - report still processing, failed, or expired

Report statuses
anchor

StatusDescription
PROCESSING Report is being generated. Poll until it reaches another status.
SUCCEEDED Report is ready to download.
FAILED Report generation failed. Try creating the report again.
EXPIRED Report is no longer available 30 days after creation.
Reports expire 30 days after creation. Column layouts follow the reports API v2 schema. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "id": "rprt_01K8F3ZQ8X9YBCDEFGHJKMNPQR",
  "report_type": "INVOICES",
  "status": "PROCESSING",
  "created_at": "2026-01-01T00:00:00.000000Z",
  "updated_at": "2026-01-01T00:10:00.000000Z",
  "parameters": {
    "date_from": "2026-01-01T00:00:00.000000Z",
    "date_to": "2026-02-01T00:00:00.000000Z"
  }
}

Handle event
anchor

Report generated Webhook fires when a report finishes generating and is ready to download.

The event includes a unique event_id, event_type set to REPORT_GENERATED , the occurred_at timestamp, and data.report with the same fields as the report returned by create, get, and list reports.

Set up a Guide
Configure webhook endpoints to receive real-time event notifications for payment status changes, subscription updates, and refund outcomes webhook endpoint and verify event signatures. Use the event to start the next step automatically, such as downloading the report, loading the data into your own systems, or notifying your team.

Looking for help? Contact us
Stay informed with Changelog