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. stripe.reporting.reportTypes.retrieve( 'balance.summary.1', function(err, reportType) { // asynchronously called } );
    // 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. reportType, _ := 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.summary.1" \ -d "parameters[interval_start]"=1522540800 \ -d "parameters[interval_end]"=1525132800 # Timestamps are for 2018-04-01 00:00 UTC and 2018-05-01 00:00 UTC. # Note that a live-mode API key is required.
    # Note that a live-mode API key is required. Stripe::Reporting::ReportRun.list({ report_type: 'balance_change_from_activity.summary.1', parameters: { interval_start: '1522540800', interval_end: '1525132800', }, })
    // Note that a live-mode API key is required. \Stripe\Reporting\ReportRun::all([ 'report_type' => 'balance_change_from_activity.summary.1', 'parameters' => [ 'interval_start' => '1522540800', 'interval_end' => '1525132800', ], ]);
    # Note that a live-mode API key is required. stripe.reporting.ReportRun.list( report_type='balance_change_from_activity.summary.1', parameters={ 'interval_start': '1522540800', 'interval_end': '1525132800', }, )
    // Note that a live-mode API key is required. stripe.reporting.reportRuns.list( { report_type: 'balance_change_from_activity.summary.1', parameters: { interval_start: '1522540800', interval_end: '1525132800', }, }, function(err, reportRuns) { // asynchronously called } );
    // Note that a live-mode API key is required. Map<String, Object> parametersParams = new HashMap<>(); params.put("interval_start", "1522540800"); params.put("interval_end", "1525132800"); Map<String, Object> params = new HashMap<>(); params.put("report_type", "balance_change_from_activity.summary.1"); params.put("parameters", parametersParams); ReportRunCollection reports = ReportRun.list(params);
    // Note that a live-mode API key is required. params := &stripe.ReportRunListParams{ ReportType: stripe.String("balance_change_from_activity.summary.1"), Parameters: &stripe.ReportRunParameters{ IntervalStart: stripe.Int64("1522540800"), IntervalEnd: stripe.Int64("1525132800"), }, } reports, _ := reportrun.List(params)
    // Note that a live-mode API key is required. var options = new ReportRunListOptions { ReportType = "balance_change_from_activity.summary.1", Parameters = ParametersOptions { IntervalStart = "1522540800", IntervalEnd = "1525132800", }, }; var service = new ReportRunService(); service.List(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.summary.1", parameters: { interval_start: 1522540800, # 2018-04-01 00:00 interval_end: 1525132800, # 2018-05-01 00:00 }, created: 1525421700, # 2018-05-04 08:15 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: "card_payments_fees.summary.1", parameters: { interval_start: 1522540800, # 2018-04-01 00:00 interval_end: 1525132800, # 2018-05-01 00:00 }, created: 1525421700, # 2018-05-04 08:15 status: "succeeded", succeeded_at: 1525421760, # 2018-05-04 08:16 result: { id: "file_xs8vrJzC", object: "file", url: "https://files.stripe.com/v1/files/file_xs8vrJzC/contents", created: 1525421760, # 2018-05-04 08:16 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

    Prerequite: 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.
    • 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.summary.1
    • interval_start

    • interval_end

    • currency

    • columns

    balance_change_from_activity.summary.1
    • interval_start

    • interval_end

    • currency

    • columns

    payouts.summary.1
    • interval_start

    • interval_end

    • currency

    • columns

    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

    payouts.itemized.1
    • interval_start

    • interval_end

    • currency

    • reporting_category

    • columns

    payouts.itemized.2
    • interval_start

    • interval_end

    • currency

    • reporting_category

    • columns

    For users on automatic payout plans

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

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

    • currency

    • columns

    payout_reconciliation.by_id.summary.1
    • payout

    • columns

    payout_reconciliation.summary.1
    • interval_start

    • interval_end

    • currency

    • columns

    ending_balance_reconciliation.itemized.1
    • interval_end

    • currency

    • reporting_category

    • columns

    ending_balance_reconciliation.itemized.2
    • interval_end

    • currency

    • reporting_category

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

    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.summary.1
    • interval_start

    • interval_end

    • currency

    • columns

    • connected_account

    connected_account_balance_change_from_activity.summary.1
    • interval_start

    • interval_end

    • currency

    • columns

    • connected_account

    connected_account_payouts.summary.1
    • interval_start

    • interval_end

    • currency

    • columns

    • connected_account

    connected_account_balance_change_from_activity.itemized.1
    • interval_start

    • interval_end

    • currency

    • reporting_category

    • columns

    • connected_account

    connected_account_balance_change_from_activity.itemized.2
    • interval_start

    • interval_end

    • currency

    • reporting_category

    • columns

    • connected_account

    connected_account_payouts.itemized.1
    • interval_start

    • interval_end

    • currency

    • reporting_category

    • columns

    • connected_account

    connected_account_payouts.itemized.2
    • interval_start

    • interval_end

    • currency

    • reporting_category

    • columns

    • connected_account

    connected_account_ending_balance_reconciliation.itemized.1
    • interval_end

    • currency

    • reporting_category

    • columns

    • connected_account

    connected_account_ending_balance_reconciliation.itemized.2
    • interval_end

    • currency

    • reporting_category

    • columns

    • connected_account

    connected_account_ending_balance_reconciliation.summary.1
    • interval_end

    • currency

    • columns

    • connected_account

    connected_account_payout_reconciliation.by_id.summary.1
    • connected_account

    • payout

    • columns

    connected_account_payout_reconciliation.summary.1
    • interval_start

    • interval_end

    • currency

    • columns

    • connected_account

    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.itemized.1
    • interval_start

    • interval_end

    • currency

    • reporting_category

    • columns

    • connected_account

    connected_account_payout_reconciliation.itemized.2
    • interval_start

    • interval_end

    • currency

    • reporting_category

    • columns

    • connected_account

    connected_account_payout_reconciliation.itemized.3
    • interval_start

    • interval_end

    • currency

    • reporting_category

    • columns

    • connected_account

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page