> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloclever.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Settlement Reporting
> How Hello Clever settlement reports are generated, what each column in the file contains, and how to reconcile a report against your own ledger.
A settlement moves your available funds out of a [Payments Account](/platform-overview/clever-concepts/payments-accounts), either to one of your Treasury Accounts or to a named external bank account. Hello Clever reports on those settlements on a schedule: at each reporting frequency enabled on your account, it generates a **settlement report** covering the settlements in that period.
This is the same report that was previously emailed to you, retrieved through the API instead. You list the reports generated in a period, and each entry hands you a link to the file. A file never changes once generated, so the number you reconciled last month is the same number you will read next year.
## The reporting flow
After the end-of-day settlement run, a report is generated at 09:00 in your account's configured time zone — one per enabled frequency, per currency.
Call [Get Settlement Reports](/api/reporting/get-settlement-reports) with `from_date` and `to_date`. This returns metadata only: file name, the period covered, a `summary` object with the period's totals, and `file_url`. No file content is transferred.
`file_url` is the file. Issue a plain `GET` against it and the response is the CSV. The link is pre-signed, so it carries no `app-id` or `secret-key`, and there is no second API call to make.
```bash Fetch a report file theme={null}
# 1. list the reports generated in the period
curl "https://api.lightningpay.me/api/v2/reports/settlements?from_date=2026-09-01T00:00:00Z&to_date=2026-09-30T00:00:00Z" \
-H "app-id: your-app-id" \
-H "secret-key: your-secret-key"
# 2. GET the file_url from any entry, no auth headers needed
curl "https://cdn-private.helloclever.co/hellocleverweb-prod/clever/sections/report/9f3c1ab2-...?sv=2021-08-06&sr=b&sp=r&sig=..." \
-o settlement.csv
```
## Reporting frequencies
A report is generated for each frequency enabled on your account, in the time zone configured on your account:
| `report_frequency` | Period covered | Generated |
| ------------------ | -------------------------------------------- | ----------------------------- |
| `daily` | The 24 hours to 09:00 on the generation date | Every day at 09:00 |
| `weekly` | The 7 days to 09:00 on the generation date | Mondays at 09:00 |
| `monthly` | The month to 09:00 on the generation date | The 1st of the month at 09:00 |
`period_start` and `period_end` on each entry give the exact window, so you never have to derive it.
Periods overlap across frequencies. With daily and monthly reporting both enabled, a settlement on 14 September appears in the daily report for 14 September and again in the monthly report generated on 1 October. Filter by `report_frequency` so your ledger posts each settlement once.
A daily report covers 09:00 to 09:00 in your account's time zone, not midnight to midnight. If your accounting periods are calendar days, the last hours of each day fall into the next report.
## File format
| Property | Value |
| ---------- | ----------------------------------------------------------------------------------------- |
| Format | CSV, comma delimited, with a header row |
| Encoding | UTF-8 |
| Amounts | Major currency units, prefixed with `-` when funds leave the balance |
| Timestamps | `Date` as `YYYY-MM-DD hh:mm:ss +hhmm`, `Settlement at` as `YYYY-MM-DD hh:mm:ss GMT+hh:mm` |
| Naming | ` Report () ( - ).csv` |
The file name contains spaces and parentheses, for example `Daily Report (AUD) (Sep 06, 2026 - Sep 07, 2026).csv`. URL-encode it if you use it in a path.
## Columns
Each row is one settlement included in the period:
| Column | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Balance ID` | Hello Clever's Id for the balance movement this settlement created. Pass it to [Get Balance History V2](/api/balance/get-balance-history-v2) to see the movement in your balance timeline. |
| `Account Nickname` | The Payments Account the funds settled from, by the nickname set in the Merchant Portal. |
| `Merchant name` | Your registered business name. |
| `Reference` | The settlement reference, matching the reference shown in the Merchant Portal. Use it as the matching key against your bank statement. |
| `Status` | Status of the settlement at the time the report was generated. |
| `Currency` | Currency of the settled funds. One file covers one currency. |
| `Payment method` | How the settlement was addressed to the beneficiary. |
| `Date` | When the settlement was created. |
| `Settlement at` | When the settlement completed. Empty until it does. |
| `Type` | The movement type. Always `settlement` in a settlement report. |
| `Amount` | Amount settled, prefixed with `-` because funds are leaving the balance. |
| `Fee amount` | Fees charged on the settlement. |
| `External ID (Order ID)` | Your own reference, as passed on the original request. This is the column to join on when matching rows to your records. |
A file looks like this:
```csv Daily Report (AUD) (Sep 06, 2026 - Sep 07, 2026).csv theme={null}
Balance ID,Account Nickname,Merchant name,Reference,Status,Currency,Payment method,Date,Settlement at,Type,Amount,Fee amount,External ID (Order ID)
BL8KMRVX,HC Payments AUD,Demo Store Pty Ltd,BAL_cqxDHqDOSs8,done,AUD,bsb,2026-09-06 23:41:08 +0000,2026-09-07 01:12:44 GMT+00:00,settlement,-4205.00,2.34,SETTLE-10241
BL2QBYTF,HC Payments AUD,Demo Store Pty Ltd,BAL_bnwCGpCNRr7,done,AUD,payid,2026-09-05 23:14:02 +0000,2026-09-05 23:51:20 GMT+00:00,settlement,-1180.00,0.85,SETTLE-10238
```
You do not have to open the file to total a period — the `summary` object on the list entry already carries these figures. Fetch the file when you need the settlement-by-settlement detail behind them.
## The `summary` object
`summary` describes the period the report covers. Every figure is derived from the rows in the file, rounded to your currency's precision the same way the file rounds them, so the two always agree:
| Field | Meaning |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| `settlement_count` | Number of settlements in the period — the row count in the file, excluding the header |
| `settled_amount` | Total settled in the period. Positive; the file's `Amount` column carries the same values with a `-` prefix |
| `settled_fee` | Sum of the file's `Fee amount` column |
| `closing_balance` | Your balance immediately after the last settlement in the period |
| `closing_balance_at` | When the ledger stamped that balance, in your account's configured time zone |
`closing_balance` is the ledger's own running balance for the last settlement in the period, not a figure computed from the file.
`closing_balance` and `closing_balance_at` are `null` when no settlement in the period carries a ledger-stamped balance yet. The other three figures are always present.
For the live balance rather than a period-closing figure, call [Get Balance Details V2](/api/balance/get-balance-details-v2). The Reporting API deliberately reports on closed periods only.
## Link expiry
`file_url` is minted when you list the report and is valid for 3 minutes.
Do not store the link in your own database or hand it to a background job that runs later. Keep the report `id`, and list the report again to get a fresh link. Because a link is minted for every entry returned, request only the `size` you intend to fetch in that run.
Because the link carries its own signature, anyone holding it can read the file until it expires. Treat it like the file contents themselves, and never put it in a URL that gets logged or shared.
## Reconciling a period
Call [Get Settlement Reports](/api/reporting/get-settlement-reports) for the window you are closing, filtering by `report_frequency` so overlapping frequencies do not double-post. Remember the range matches generation time, so widen it by one period to catch the report that covers your window's start.
`GET` the `file_url` on each entry, in the same run while the link is valid, and page until `has_more` is `false`.
Use `Reference` as the matching key against `Amount` less `Fee amount`. One reference corresponds to one deposit, and the period's totals are `summary.settled_amount` and `summary.settled_fee`.
Pass `Balance ID` to [Get Balance History V2](/api/balance/get-balance-history-v2) to see the settlement in your balance timeline, alongside the payments, refunds, and fees that built the balance it drew from.
For a nightly job, query a fixed window (for example, the previous two full days in UTC, filtered to `report_frequency=daily`) rather than tracking cursors across runs, and deduplicate on report `id` so an overlapping window posts nothing twice.
## Payments Accounts
A report covers the settlements for one currency, across the Payments Accounts that settled in the period. The file's `Account Nickname` column tells you which account each settlement came from, so a report spanning several accounts can still be split per account on your side.
There is currently no way to request reports for a single Payments Account. If you need that, talk to us — see [Balance Models](/platform-overview/clever-concepts/balance-models) for how accounts hold balances under each model.
## Related topics
- [Reporting API Overview](/api/reporting/overview.md)
- [Hello Clever API Overview](/api/overview.md)
- [Get Settlement Reports](/api/reporting/get-settlement-reports.md)