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.

Type Date used Description
INVOICES Creation date Invoice line items, with one row per line item. Covers invoice content, such as billed products and amounts, not payment details.
SUBSCRIPTIONS Creation date Subscriptions, with one row per subscription line item.
TAX_TRANSACTIONAL Processing date Tax line items, with one row per tax line item.
INVOICE_PAYMENTS Creation date Invoice payments, with one row per payment. Covers payment amount and method, not invoice line item details.
TAX_SUMMARY Processing date Tax totals, with one row per legal entity, tax jurisdiction, tax rate, tax currency, and processing currency combination.

Account and channel scope

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.

API 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

Status Description
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.
id string 100

Description

Unique report identifier.

Example

rprt_01K8F3ZQ8X9YBCDEFGHJKMNPQR

report_type string 64

Description

Report type.

  • INVOICES
  • SUBSCRIPTIONS
  • TAX_TRANSACTIONAL
  • INVOICE_PAYMENTS
  • TAX_SUMMARY

Example

INVOICES

status string 64

Description

Current report status.

  • PROCESSING
  • SUCCEEDED
  • FAILED
  • EXPIRED

Example

PROCESSING

created_at string 30

Description

Date and time when the report was created.

Example

2026-01-01T00:00:00.000000Z

updated_at string 30

Description

Date and time when the report was last updated.

Example

2026-01-01T00:10:00.000000Z

parameters.channel_ids array

Description

Channels the report is limited to. Absent when the report covers the entire account.

Example

["chn_01JYWX6Z5A8P32B6NVH1G9876A"]

parameters.date_from string 30

Description

Start date and time for the report data range. The value is inclusive.

Example

2026-01-01T00:00:00.000000Z

parameters.date_to string 30

Description

End date and time for the report data range. The value is exclusive.

Example

2026-02-01T00:00:00.000000Z

Example 
{
  "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

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