In addition to the CSV statements you can export via the Revolut Business Dashboard, you can generate custom CSV reports using the Merchant API: Report runs operations. Unlike the default statements, creating custom reports offers you more flexibility in determining what data you wish to incorporate. This allows you to have more control over your analytics.
This tutorial walks you through the process of:
Additionally, if you use the metadata
object in your order management system, we provide you with examples of how you can include your custom metadata parameters in your reports.
When it comes to getting the data from your reports in CSV format, you have three options:
CLI with manual copying: You'll employ the CLI to make the necessary API calls in this method. Once you receive the results, you need to copy and paste them into a text file manually.
API client tool with manual copying: Another approach is to utilise an API client tool like Postman. This tool streamlines API calls. After retrieving the results, you need to copy and paste them into a text file manually.
Custom implementation with frontend and backend: For a more tailored solution, you can create your own implementation. This involves developing a basic frontend for data input. On the backend, you'll handle API calls and facilitate the direct download of the report file.
Each option provides a different level of automation and control, allowing you to choose the approach that best aligns with your preferences and requirements.
Before you start this tutorial, ensure that you have completed the following steps:
You can generate a custom CSV report using the Merchant API: Create a new report run operation. Several parameters help you customise your reports. There are two main categories:
filter
object lets you define which transactions to include in your reportoptions
object lets you define how you want to present your results: columns to include, timezone to use for timestampsSome available parameters are not covered in this guide. For a complete list, see: Merchant API: Create a new report run.
When you know what and how you wish to include in your custom report, create the corresponding request body as a JSON object.
For example, suppose you want to generate a report about failed and declined EUR
payments in the first half of 2023. Furthermore, you want to include each transaction and order ID, the payment method, the amount, the currency, the respective order states and descriptions, and the last time the orders were updated.
To do this, pass the following JSON as the body of the request:
{
"filter": {
"from": "2023-01-01T00:00:00Z",
"to": "2023-07-01T00:00:00Z",
"entity_types": [
"payment"
],
"entity_states": [
"failed",
"declined"
],
"currency": "EUR"
},
"format": "csv",
"type": "custom_report",
"options": {
"columns": [
"transaction_id",
"order_id",
"payment_method",
"amount",
"currency",
"state",
"updated_date"
]
}
}
The response of the request contains the report_run_id
. Save this ID, as you will need it to check the report run's status.
After initiating your custom report run, use the report_run_id
from the response to repeatedly send a request to the Retrieve report run details endpoint. You can track the report run's status
changes.
You should continue to check the report run state until the response contains a final state. Depending on the received state, you need to do the following:
Report run state | Description |
---|---|
processing | Continue polling. |
completed | You can stop polling. The report run was successfully finished. Your custom report is ready at the file_url . Continue with Step 3. |
failed | You can stop polling. The report run failed due to some error. Check your request body for any errors and try again from Step 1. |
expired | The report run expired, and the CSV file cannot be downloaded anymore. If you wish to recreate the same report, use the same request body and repeat the process from Step 1. |
When your report run transitions to completed
state, the response of the Retrieve report run details call will contain the file_url
where the generated CSV file is available for you to download.
Here is an example CSV report generated based on the custom report defined in Step 1:
Download the example CSVAs downloading the report file requires authorisation, you cannot download the report by simply opening the file_url
in a browser.
For all options detailed in the Get data from the report section, all steps so far are the same. Depending on your chosen approach, you need to do the following to save your reports as CSV files.
To save your report as a CSV file with CLI, follow these steps:
After the report run transitions to completed
state, call the Download report file endpoint. The response will contain the raw CSV data.
Alternatively, you can make an authorised GET
call to the file_url
retrieved from a completed
report run object.
Select and copy the data from the response.
Open a new text file and paste the data into the file.
Save the text file in CSV format.
Similar to the previous option, this method involves manually copying the results. The only difference is that now you are using an API client tool to extract the data. To save your report as a CSV file with an API client tool, follow these steps:
After the report run transitions to completed
state, call the Download report file endpoint. The response will contain the raw CSV data.
Alternatively, you can make an authorised GET
call to the file_url
retrieved from a completed
report run object.
Select and copy the data from the response.
Open a new text file and paste the data into the file.
Save the text file in CSV format.
Compared to the other options, with this more advanced solution, you'll have a customised solution to handle the entire process, including retrieving and saving the report data. Here's how the process works in this case:
You interact with the frontend to initiate the report run request. (Step 1.)
The frontend sends a request containing the request's body to the backend. (Step 1.)
The backend makes the API call to the Merchant API to retrieve the report data. (Step 1.)
Poll the report run status until it reaches a final state. (Step 2.)
After the report run transitions to completed
state, call the Download report file endpoint. The response will contain the raw CSV data.
Alternatively, you can make an authorised GET
call to the file_url
retrieved from a completed
report run object.
The backend sends the report data to the frontend.
Optionally, the frontend displays the data.
You can download the data as a CSV file directly from the frontend.
Regardless of the option you choose, the main goal of Step 3. remains the same - retrieving and saving the report data as a CSV file.
If you use custom metadata
on your orders, you can include them in your report file as additional columns. To do this, you can add them to the options.columns
array the following way:
{
...
"options": {
"columns": [
...,
"metadata.custom_attribute_1",
"metadata.custom_attribute_2"
]
}
}