---
api: 'Merchant API'
---

# Create a report run

Start generating a report of all transactions that match the filter and options specified in the request body.

Use the returned `report_run_id` and the [Retrieve report run details](/docs/api/merchant#retrieve-report-run) operation to check the status of the generation.

After generation is done, use the [Download report file](/docs/api/merchant#download-report-file) operation to retrieve the CSV. The `file_url` in the completed report run object is the request URL for that endpoint and requires the same authorisation as any other Merchant API request. 

### Report types

The table below helps to choose the right report type for your use case:

| Report type | What it covers |
| ----------- | -------------- |
| `custom_report` | Settled and processing transactions with configurable columns |
| `settlement_report` | All settled transactions, with a configurable set of columns |
| `payments_report` | All payments including failed and declined ones |
| `payout_statement_report` | All transactions contributing to a specific payout |
| `icpp_fee_breakdown_report` | IC++ fees per transaction for a specific IC++ charge |

### IDs across report types

Each report type uses a different primary ID, depending on which system the data comes from:

| ID column | System | Report types |
| --------- | ------ | ------------ |
| `payment_id`, `id` | **Acquiring system** - identifies a payment attempt | `payments_report`, `icpp_fee_breakdown_report` |
| `transaction_id` | **Core ledger** - identifies the settlement entry created when a payment is captured | `settlement_report`, `payout_statement_report`, `custom_report` |
| `order_id` | **Both systems** - bridges the acquiring and ledger perspectives | `settlement_report`, `payments_report`, `payout_statement_report`, `custom_report` |

## Endpoint

POST `/api/report-runs`

## Request body

### Attributes

## Returns

### 201

Report run created, report started generating

#### Response attributes

- `report_run_id` (string)
    Unique ID used for accessing report details. Use this to check report generation status.
- `status` (enum)
    Current status of the report run.
    
    | Value | Description |
    | ----- | ----------- |
    | `processing` | Report generation is still in progress. |
    | `completed` | Report generation finished successfully and the file is available to download for 24 hours via `file_url`. |
    | `failed` | Report generation failed and no report file is available. |
    | `expired` | Report generation previously completed, but the 24-hour file availability window has elapsed and the file can no longer be downloaded. |
    Possible enum values:

    - `processing`
    - `completed`
    - `failed`
    - `expired`
- `file_url` (string, optional)
    Use this link to download the report file. Available only when `status` is `completed`, and only for 24 hours after report generation finishes.

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |