Reports
Financial reports
Report API

API access to reports

Access Stripe's reports for finance/accounting tasks via API.

The financial reports pages provide downloadable reports for a variety of finance/accounting tasks. These reports are also available via API, so that on a schedule of your choosing—or on an ad-hoc basis—you can automatically receive and ingest these report files into your internal accounting pipeline.

Read on for:

Report types

Of the reports available from the Dashboard financial reports pages:

See the Reports reference for a complete list of available report types.

Data availability

Stripe prepares data for your reports on a daily basis, with each day’s data defined by activity that takes place between 12:00am UTC and 11:59pm UTC. For reports available via API, each day’s data will be available within 12 hours of the day’s end.

To programmatically determine the time range of data available for a given report type, retrieve the ReportType object of interest. For example, the Balance Summary report has the ID balance.summary.1, so we can retrieve the object as follows:

curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \ -u sk_live_123456: # Note that a live-mode API key is required.
# Note that a live-mode API key is required. Stripe::Reporting::ReportType.retrieve('balance.summary.1')
// Note that a live-mode API key is required. \Stripe\Reporting\ReportType::retrieve('balance.summary.1');
# Note that a live-mode API key is required. stripe.reporting.ReportType.retrieve('balance.summary.1')
// Note that a live-mode API key is required. const reportType = await stripe.reporting.reportTypes.retrieve('balance.summary.1');
// Note that a live-mode API key is required. ReportType reportType = ReportType.retrieve("balance.summary.1");
// Note that a live-mode API key is required. r, _ := reporttype.Get("balance.summary.1", nil)
// Note that a live-mode API key is required. var service = new ReportTypeService(); service.Get("balance.summary.1");

In the example response below, the fields data_available_start and data_available_end reflect the full range of valid times for this report type. However, you’ll most often be running reports for a smaller interval within that range:

{ id: "balance.summary.1", name: "Balance summary", version: "1", object: "reporting.report_type", data_available_start: 1519862400, # 2018-03-01 00:00 data_available_end: 1517356800, # 2018-05-04 00:00 updated: 1517382720, # 2018-05-04 07:12 }

New data notifications

As soon as a report type has new data available, Stripe publishes a reporting.report_type.updated event with the updated ReportType object. In order to access these events, you must have a webhook configured that explicitly selects to receive reporting.report_type.updated events; webhooks that listen for ‘all events’ will not receive them. Once you receive such an event, you can then request report runs accordingly. For details, see our recommended integration pattern.

Creating and accessing report runs

The ReportRun API object represents an instance of a ReportType generated with specific parameters. (Required and optional parameters for each report type are documented in the Reports reference.) For example, you can create a Balance Change From Activity Summary report for April 2018 as follows:

curl https://api.stripe.com/v1/reporting/report_runs \ -u sk_live_123456: \ -d report_type="balance_change_from_activity.itemized.3" \ -d "parameters[interval_start]"=1577865600 \ -d "parameters[interval_end]"=1580544000 \ -d "parameters[timezone]"="America/Los_Angeles" # Timestamps are for 2020-01-01 00:00 PST and 2020-02-01 00:00 PST. # Note that a live-mode API key is required.
# Note that a live-mode API key is required. Stripe::Reporting::ReportRun.create({ report_type: 'balance_change_from_activity.itemized.3', parameters: { interval_start: '1577865600', interval_end: '1580544000', timezone: 'America/Los_Angeles', }, })
// Note that a live-mode API key is required. \Stripe\Reporting\ReportRun::create([ 'report_type' => 'balance_change_from_activity.itemized.3', 'parameters' => [ 'interval_start' => '1577865600', 'interval_end' => '1580544000', 'timezone' => 'America/Los_Angeles', ], ]);
# Note that a live-mode API key is required. stripe.reporting.ReportRun.create( report_type='balance_change_from_activity.itemized.3', parameters={ 'interval_start': '1577865600', 'interval_end': '1580544000', 'timezone': 'America/Los_Angeles', }, )
// Note that a live-mode API key is required. const reportRun = await stripe.reporting.reportRuns.create({ report_type: 'balance_change_from_activity.itemized.3', parameters: { interval_start: '1577865600', interval_end: '1580544000', timezone: 'America/Los_Angeles', }, });
// Note that a live-mode API key is required. ReportRunCreateParams params = ReportRunCreateParams.builder() .setParameters( ReportRunCreateParams.Parameters.builder() .setIntervalStart(1577865600L) .setIntervalEnd(1580544000L) .setTimezone(ReportRunCreateParams.Parameters.Timezone.AMERICA_LOS_ANGELES) .build()) .setReportType("balance_change_from_activity.itemized.3") .build(); ReportRun report = ReportRun.create(params);
// Note that a live-mode API key is required. params := &stripe.ReportRunParams{ ReportType: stripe.String("balance_change_from_activity.itemized.3"), Parameters: &stripe.ReportRunParametersParams{ IntervalStart: stripe.Int64(1577865600), IntervalEnd: stripe.Int64(1580544000), Timezone: stripe.String("America/Los_Angeles"), }, } r, _ := reportrun.New(params)
// Note that a live-mode API key is required. var options = new ReportRunCreateOptions { ReportType = "balance_change_from_activity.itemized.3", Parameters = new ReportRunParametersOptions { IntervalStart = new DateTime(2020, 1, 1), IntervalEnd = new DateTime(2020, 2, 1), Timezone = "America/Los_Angeles", }, }; var service = new ReportRunService(); var reportRun = service.Create(options);

When first created, the object will appear with status="pending":

{ id: "frr_123", object: "reporting.report_run", livemode: true, report_type: "balance_change_from_activity.itemized.3", parameters: { interval_start: 1577865600, # 2020-01-01 00:00 PST interval_end: 1580544000, # 2020-02-01 00:00 PST timezone: "America/Los_Angeles", }, created: 1580832900, # 2020-02-04 08:15 PST status: "pending", result: nil, }

When the run completes, Stripe will update the object: it will have a status of succeeded, and will have a nested result object, containing a URL from which you can access the file with your API key. For example, if you were to retrieve the above report run after it completes, the response would be:

{ id: "frr_123", object: "reporting.report_run", livemode: true, report_type: "balance_change_from_activity.itemized.3", parameters: { interval_start: 1577865600, # 2020-01-01 00:00 PST interval_end: 1580544000, # 2020-02-01 00:00 PST timezone: "America/Los_Angeles", }, created: 1580832900, # 2020-02-04 08:15 PST status: "succeeded", succeeded_at: 1580832960, # 2020-02-04 08:16 PST result: { id: "file_xs8vrJzC", object: "file", url: "https://files.stripe.com/v1/files/file_xs8vrJzC/contents", created: 1580832960, # 2020-02-04 08:16 PST purpose: "report_run", size: 53075, type: "csv" }, }

To retrieve the file contents, use your API key to access the file specified by result.url:

curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: # Note that a live-mode API key is required.

Notification of report run completion

Most runs complete within a few minutes. However, some runs could take longer—depending on the size of your total data set, and on the time range your report covers.

When a requested report run completes, Stripe sends one of two webhooks:

  • A reporting.report_run.succeeded webhook will be sent if the run completes successfully.
  • A reporting.report_run.failed webhook will be sent if the run fails. (This should be rare, but we recommend that integrations be prepared to handle this case in the same spirit as catching a 500 response.)

In both cases, the webhook payload will include the updated ReportRun object, which will have status succeeded or failed, respectively.

Recommended integration pattern for automated reporting

Prerequisite: configure a webhook that explicitly selects to receive reporting.report_type.updated events; webhooks that listen for ‘all events’ will not receive them.

  1. A reporting.report_type.updated webhook will be sent as soon as a new day’s data is available for a given report type. The payload will include the updated ReportType object. You will typically receive 10–20 webhooks each day, one for each report type. (Different users are eligible for different reports.)
  2. Upon receiving the reporting.report_type.updated webhook, for the desired report type and range of data availability, create a report run. The response will contain a new ReportRun object, initialized with status=pending.
  3. When the run completes, a reporting.report_run.succeeded webhook will be sent. This webhook will include the nested field result.url. (As mentioned above, in the rare case of a failure, we will send a reporting.report_run.failed event instead.)
  4. Access the file contents at result.url, using your API key.

Reports reference

This section lists the report types available via API. To see the results schema and example data, visit the Dashboard pages linked in the descriptions below.

About run parameters

The tables below include the required and optional run parameters to be provided when creating a report run. Note that:

  • Creating a run for nearly all of the report types requires providing the run parameters interval_start and interval_end. Provide these parameters as Unix timestamps.
  • The corresponding report type resource will have data_available_start and data_available_end fields. The API will return an invalid request error (status code 400) if the following constraints are not met:
    • If the timestamps interval_start and interval_end are provided, they must be between data_available_start and data_available_end (inclusive).
    • If interval_start is provided, it must be before (and not equal to) interval_end.
  • To download a report in a time zone, you must create a ReportRun object for one of the ReportType that have a timezone parameter and supply the desired TZ database time zone name. The timezone parameter is optional and will default to UTC if not supplied. A list of possible time zone values is maintained at the IANA Time Zone Database.
  • The optional parameters currency and report_category will filter results to just those rows matching the provided values.
  • By default, reports are run with the default set of columns. For most report types, you can customize the selection and ordering of columns in the output by including the optional columns parameter with a list of column names. Supported columns for each report type can be found in the reporting schemas documentation.

For all users

These reports are also available for download from the Dashboard financial reports pages.

Report type Required run parameters Optional run parameters
balance_change_from_activity.itemized.1
  • interval_start

  • interval_end

  • currency

  • reporting_category

  • columns

balance_change_from_activity.itemized.2
  • interval_start

  • interval_end

  • currency

  • reporting_category

  • columns

balance_change_from_activity.itemized.3
  • interval_start

  • interval_end

  • timezone

  • currency

  • reporting_category

  • columns

balance_change_from_activity.summary.1
  • interval_start

  • interval_end

  • currency

  • columns

payouts.itemized.1
  • interval_start

  • interval_end

  • currency

  • reporting_category

  • columns

payouts.itemized.2
  • interval_start

  • interval_end

  • currency

  • reporting_category

  • columns

payouts.itemized.3
  • interval_start

  • interval_end

  • timezone

  • currency

  • reporting_category

  • columns

payouts.summary.1
  • interval_start

  • interval_end

  • currency

  • columns

balance.summary.1
  • interval_start

  • interval_end

  • timezone

  • currency

  • columns

For users on automatic payout plans

These reports are also available for download from the Dashboard Payout reconciliation page.

Report type Required run parameters Optional run parameters
ending_balance_reconciliation.itemized.1
  • interval_end

  • currency

  • reporting_category

  • columns

ending_balance_reconciliation.itemized.2
  • interval_end

  • currency

  • reporting_category

  • columns

ending_balance_reconciliation.itemized.3
  • interval_end

  • currency

  • reporting_category

  • timezone

  • columns

ending_balance_reconciliation.summary.1
  • interval_end

  • currency

  • columns

ending_balance_reconciliation.itemized.4
  • interval_end

  • currency

  • reporting_category

  • timezone

  • columns

payout_reconciliation.by_id.itemized.1
  • payout

  • reporting_category

  • columns

payout_reconciliation.by_id.itemized.2
  • payout

  • reporting_category

  • columns

payout_reconciliation.by_id.itemized.3
  • payout

  • reporting_category

  • columns

payout_reconciliation.by_id.itemized.4
  • payout

  • reporting_category

  • timezone

  • columns

payout_reconciliation.by_id.summary.1
  • payout

  • columns

payout_reconciliation.itemized.1
  • interval_start

  • interval_end

  • currency

  • reporting_category

  • columns

payout_reconciliation.itemized.2
  • interval_start

  • interval_end

  • currency

  • reporting_category

  • columns

payout_reconciliation.itemized.3
  • interval_start

  • interval_end

  • currency

  • reporting_category

  • columns

payout_reconciliation.itemized.4
  • interval_start

  • interval_end

  • timezone

  • currency

  • reporting_category

  • columns

payout_reconciliation.summary.1
  • interval_start

  • interval_end

  • currency

  • columns

payout_reconciliation.itemized.5
  • interval_start

  • interval_end

  • timezone

  • currency

  • reporting_category

  • columns

For Connect platforms with Custom or Express accounts

These reports are also available for download from the Dashboard financial reports pages. (From the dropdown options, be sure to choose connected accounts rather than platform account.)

Report type Required run parameters Optional run parameters
connected_account_balance_change_from_activity.itemized.1
  • interval_start

  • interval_end

  • connected_account

  • currency

  • reporting_category

  • columns

connected_account_balance_change_from_activity.itemized.2
  • interval_start

  • interval_end

  • connected_account

  • currency

  • reporting_category

  • columns

connected_account_balance_change_from_activity.itemized.3
  • interval_start

  • interval_end

  • connected_account

  • timezone

  • currency

  • reporting_category

  • columns

connected_account_balance_change_from_activity.summary.1
  • interval_start

  • interval_end

  • currency

  • connected_account

  • columns

connected_account_payouts.itemized.1
  • interval_start

  • interval_end

  • connected_account

  • currency

  • reporting_category

  • columns

connected_account_payouts.itemized.2
  • interval_start

  • interval_end

  • connected_account

  • currency

  • reporting_category

  • columns

connected_account_payouts.itemized.3
  • interval_start

  • interval_end

  • connected_account

  • timezone

  • currency

  • reporting_category

  • columns

connected_account_payouts.summary.1
  • interval_start

  • interval_end

  • currency

  • connected_account

  • columns

connected_account_balance.summary.1
  • interval_start

  • interval_end

  • timezone

  • currency

  • connected_account

  • columns

connected_account_ending_balance_reconciliation.itemized.1
  • interval_end

  • connected_account

  • currency

  • reporting_category

  • columns

connected_account_ending_balance_reconciliation.itemized.2
  • interval_end

  • connected_account

  • currency

  • reporting_category

  • columns

connected_account_ending_balance_reconciliation.itemized.3
  • interval_end

  • connected_account

  • currency

  • reporting_category

  • timezone

  • columns

connected_account_ending_balance_reconciliation.summary.1
  • interval_end

  • connected_account

  • currency

  • columns

connected_account_ending_balance_reconciliation.itemized.4
  • interval_end

  • connected_account

  • currency

  • reporting_category

  • timezone

  • columns

connected_account_payout_reconciliation.itemized.5
  • interval_start

  • interval_end

  • connected_account

  • timezone

  • currency

  • reporting_category

  • columns

connected_account_payout_reconciliation.by_id.itemized.1
  • connected_account

  • payout

  • reporting_category

  • columns

connected_account_payout_reconciliation.by_id.itemized.2
  • connected_account

  • payout

  • reporting_category

  • columns

connected_account_payout_reconciliation.by_id.itemized.3
  • connected_account

  • payout

  • reporting_category

  • columns

connected_account_payout_reconciliation.by_id.itemized.4
  • connected_account

  • payout

  • timezone

  • reporting_category

  • columns

connected_account_payout_reconciliation.by_id.summary.1
  • connected_account

  • payout

  • columns

connected_account_payout_reconciliation.itemized.1
  • interval_start

  • interval_end

  • connected_account

  • currency

  • reporting_category

  • columns

connected_account_payout_reconciliation.itemized.2
  • interval_start

  • interval_end

  • connected_account

  • currency

  • reporting_category

  • columns

connected_account_payout_reconciliation.itemized.3
  • interval_start

  • interval_end

  • connected_account

  • currency

  • reporting_category

  • columns

connected_account_payout_reconciliation.itemized.4
  • interval_start

  • interval_end

  • connected_account

  • timezone

  • currency

  • reporting_category

  • columns

connected_account_payout_reconciliation.summary.1
  • interval_start

  • interval_end

  • currency

  • connected_account

  • columns

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.