Skip to main content

The Report API

The report API is at the center of automating your reconciliation flow for both you and your sellers. The steps towards automation are roughly as follows:

  1. Rootline sends a payout to you and your sellers;
  2. For each payout a settlement report is created;
  3. Listen to the report.created webhook and accept and process the webhook when it comes in;
  4. Check for which account the report is sent and parse the report;
  5. Process the content of the report and reconcile the payments and their associated fees.

The report.created webhook contains a download_url which you can use to retrieve the report.

Webhook​

The report.created webhook will be sent for every report that is generated in Rootline.
Example webhook:

{
    "object": "event",
    "webhook_endpoint_id": "webh_59rz4zUN69BvGY8cpo7lqn",
    "event_type": "report.created",
    "event_time": "2024-12-16T13:58:13.494312Z",
    "livemode": false,
    "api_version": "2024-04-23",
    "report": {
        "id": "report_4BUGXp9cPlcfYE3v8vQx7v",
        "object": "report",
        "report_type": "settlement_report",
        "file_name": "settlement_report_2024-12-16T13:56:52.630Z_report_4BUGXp9cPlcfYE3v8vQx7v.csv",
        "generated_at": "2024-12-16T13:56:52.630Z",
        "download_url": "report-api.staging.rootline.com/reports/report_4BUGXp9cPlcfYE3v8vQx7v/download",
        "sha256": "a69DFkTLl+GZkk6wwgmIG2uetGPS7SiCiI8m9HqcXJw=",
        "version": "2024-04-23",
        "input_parameters": {
            "end_time": "2024-12-01",
            "account_id": "acc_SqVpnKhpr8TxS0Y7S99bI",
            "start_time": "2024-11-25"
        }
    }
}

Retrieve report information​

You can retrieve the report's information by making GET call to the report API.

Endpoint: https://report-api.staging.rootline.com/v1/reports/report_4BUGXp9cPlcfYE3v8vQx7v

Response:

{
    "id": "report_4BUGXp9cPlcfYE3v8vQx7v",
    "object": "report",
    "report_type": "settlement_report",
    "file_name": "SettlementReport_2024-12-16T13:56:52.630Z_report_4BUGXp9cPlcfYE3v8vQx7v.csv",
    "generated_at": "2024-12-16T13:56:52.630Z",
    "download_url": "https://report-api.staging.rootline.com/v1/reports/report_4BUGXp9cPlcfYE3v8vQx7v/download",
    "sha256": "a69DFkTLl+GZkk6wwgmIG2uetGPS7SiCiI8m9HqcXJw=",
    "version": "2024-04-23",
    "input_parameters": {
        "end_time": "2024-12-01",
        "account_id": "acc_SqVpnKhpr8TxS0Y7S99bI",
        "start_time": "2024-11-25"
    }
}

Downloading the report​

To download the report your API user needs to have the ReportRole.

When you receive the report.createdwebhook first store and accept the webhook. In a separate process download the report using the download_url.

wget --header="x-api-key: YOUR_API_KEY" --header="Rootline-Version: 2024-04-23" -O report.file_name report.download_url

Replace report.file_name and report.download_url with the values received from the API / webhook.

The above commands will save the report in the execution directory.

Verify the checksum​

The report.created webhook contains the sha256 checksum of the report.
Once the report is downloaded you can verify the checksum by:

  1. Calculating the SHA-256 hash of the report;
  2. Output the hash in raw bytes;
  3. Create a base64 encoding of the binary hash and match this with the report.sha256 value from the API / webhook.

Example command using OpenSSL:

openssl dgst -sha256 -binary settlement_report_2024-12-16T13:56:52.630Z_report_4BUGXp9cPlcfYE3v8vQx7v.csv | openssl enc -base64
a69DFkTLl+GZkk6wwgmIG2uetGPS7SiCiI8m9HqcXJw=