There are two ways to setup a report, either via the dashboard or via the API.

​
Using Dashboard

  1. Go to Reports in the top bar
  2. Choose the type of report you want to generate
  3. Follow the creation steps
  4. Check the report’s executions in “Generated” tab
  5. Download report

​
Using API

​
1. Create a report

Use the POST {url}/reports/ API to create a report. 
{
  "name": "Successful captures",
  "spec": {
    "params": {
      "fields": ["id", "captured_at", "amount"],
      "sort": [
        {
          "field": "created_at",
          "order": "asc"
        }
      ],
      "filters": {
        "status": ["capture_succeeded"]
      }
    }
  }
}

​
2. Check report’s executions (optional)

Next, you can list all the executions for a report. 
{
  "items": [
    {
      "type": "report-execution",
      "id": "0848ef01-f44a-4564-abdb-52a1344bac63",
      "created_at": "2022-10-28T10:15:36.571232+00:00",
      "updated_at": "2022-10-28T10:15:36.611495+00:00",
      "status": "dispatched",
      "context": {
        "reference_timestamp": "2022-10-28T10:15:36.571232+00:00",
        "reference_timezone": "Etc/UTC"
      },
      "report": {
        "type": "report",
        "id": "71aa8d49-5ec7-43aa-b13c-9b16fdae0f9b",
        "name": "Successful captures"
      }
    }
  ],
  "limit": 20,
  "next_cursor": null,
  "previous_cursor": null
}

​
3. Generate report’s execution URL

To download the file for an execution, check the status of the execution is succeeded, and then request the download URL. 
{
  "url": "https://url/to/report/file",
  "expires_at": "2022-10-28T10:21:33.345947+00:00"
}
The report can be downloaded from the url until it expires at expires_at.

​
Webhooks & error handling

When a report is generated, it will trigger a report-execution.succeeded webhook event. If the generation fails for some reason, a report-execution.failed will be sent. This event is triggered when a report fails to generate due to an unexpected internal technical issue. We will not retry the report generation and instead recommend the following steps to resolve the issue.
  • One-off reports: A new one-off report must be created.
  • Scheduled reports: As the report will not run for the failed period, we recommend creating a new one-off report for the same period to download the data.
If you receive this event frequently or you are not able to create a one-off report, please contact our support team with the details of the report.