> ## 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. # Get Settlement Reports > Lists the settlement reports generated for your account within a date range. One report covers one reporting period, for one currency, at one frequency — so a merchant with daily and monthly reports enabled receives both, and the same settlements appear in each. Reports are returned for the currency tied to the `app-id` you authenticate with. Each entry carries `file_url`, a pre-signed link to the CSV: fetch it with a plain `GET` and no authentication headers. `from_date` and `to_date` are matched against when the report was **generated**, not the period it covers. A daily report generated on 7 September covers 6–7 September, so widen the range by one period if you are looking for a specific window. Results are ordered by generation time descending and are paginated with a cursor, in either direction: pass `next_cursor` back as `cursor` to move forward, or `previous_cursor` back as `previous_cursor` to move backward. ## OpenAPI ````yaml /api/openapi/reporting-reference.yaml get /v2/reports/settlements openapi: 3.0.3 info: title: Reporting APIs description: >- ## Introduction The Reporting API gives you programmatic access to the settlement reports Hello Clever generates for your account. These are the same reports that were previously delivered to your inbox: the same file, the same figures, retrieved on your own schedule instead of waiting for an email. ### Key Features - **Settlement Reports**: - **Get Settlement Reports**: List the settlement report files generated for a date range, with the file name, the period each file covers, the settlement totals for that period, and a link to the CSV. ### How reporting works 1. Hello Clever generates a settlement report after each end-of-day settlement run, at 09:00 in your account's time zone. You receive a report per frequency you have enabled (daily, weekly, monthly), per currency. 2. Call **Get Settlement Reports** to list the reports generated in a period. Each entry carries `summary`, the settlement totals for that period, plus `file_url`. 3. `file_url` is a pre-signed link to the CSV. Issue a plain `GET` against it to retrieve the file. It needs no `app-id` or `secret-key`, and it expires 3 minutes after being issued. A report file never changes once generated, which makes it safe to use as the source record for accounting periods that have been closed. version: 1.0.0 termsOfService: https://helloclever.co/terms contact: email: support@helloclever.co servers: - url: https://sandbox-api.lightningpay.me/api description: Sandbox Environment - url: https://api.lightningpay.me/api description: Production Environment security: [] paths: /v2/reports/settlements: get: tags: - Reporting summary: Get Settlement Reports description: > Lists the settlement reports generated for your account within a date range. One report covers one reporting period, for one currency, at one frequency — so a merchant with daily and monthly reports enabled receives both, and the same settlements appear in each. Reports are returned for the currency tied to the `app-id` you authenticate with. Each entry carries `file_url`, a pre-signed link to the CSV: fetch it with a plain `GET` and no authentication headers. `from_date` and `to_date` are matched against when the report was **generated**, not the period it covers. A daily report generated on 7 September covers 6–7 September, so widen the range by one period if you are looking for a specific window. Results are ordered by generation time descending and are paginated with a cursor, in either direction: pass `next_cursor` back as `cursor` to move forward, or `previous_cursor` back as `previous_cursor` to move backward. operationId: getSettlementReports parameters: - name: from_date in: query required: true schema: type: string format: date-time description: >- Start of the range, in the format 'YYYY-MM-DDThh:mm:ssZ'. Defaults to UTC timezone. Matched against the time the report was generated. example: '2026-09-01T00:00:00Z' - name: to_date in: query required: true schema: type: string format: date-time description: >- End of the range, in the format 'YYYY-MM-DDThh:mm:ssZ'. Defaults to UTC timezone. The range must not exceed 90 days. example: '2026-09-30T00:00:00Z' - name: report_frequency in: query schema: type: string enum: - daily - weekly - monthly description: >- Return only reports generated at this frequency. Accepts a comma-separated list, for example `daily,weekly`. Omit to return every frequency enabled on your account. example: daily - name: cursor in: query schema: type: string description: >- Page forward. Pass the `next_cursor` from the previous response to fetch the entries after that page. Omit both cursors to fetch the first page. Cannot be combined with `previous_cursor`. example: MjAyNi0wOS0wMVQwOTowMDowOS4wMDAwMDArMDA6MDB8NDc5NQ== - name: previous_cursor in: query schema: type: string description: >- Page backward. Pass the `previous_cursor` from a response to fetch the entries before that page. Cannot be combined with `cursor`. example: MjAyNi0wOS0wN1QwOTowMDoxNC4wMDAwMDArMDA6MDB8NDgyMQ== - name: size in: query schema: type: integer default: 20 maximum: 100 description: >- Number of report entries to return per page. A pre-signed link is minted for every entry returned, so request only the page size you intend to fetch. example: 20 responses: '200': description: OK content: application/json: schema: type: object properties: from_date: type: string example: '2026-09-01T00:00:00Z' to_date: type: string example: '2026-09-30T00:00:00Z' size: type: integer example: 20 description: Number of report entries returned per page. next_cursor: type: string nullable: true example: MjAyNi0wOS0wMVQwOTowMDowOS4wMDAwMDArMDA6MDB8NDc5NQ== description: >- Cursor to pass as the `cursor` query parameter to fetch the next page. `null` when there are no more entries after this page. previous_cursor: type: string nullable: true example: MjAyNi0wOS0wN1QwOTowMDoxNC4wMDAwMDArMDA6MDB8NDgyMQ== description: >- Cursor to pass as the `previous_cursor` query parameter to fetch the preceding page. `null` on the first page. has_more: type: boolean example: true description: Whether more entries are available after this page. has_previous: type: boolean example: false description: >- Whether entries are available before this page. Always `false` on the first page. records: type: array items: type: object properties: id: type: string example: rpt_8KmRvXq3N2dL description: >- Settlement report Id. Stable for the life of the report, so it is the value to store against your own reporting record. file_name: type: string example: Daily Report (AUD) (Sep 06, 2026 - Sep 07, 2026).csv description: >- Name of the generated file, the same name the report email attached. Contains spaces and parentheses, so URL-encode it if you use it in a path. file_url: type: string nullable: true description: >- Pre-signed link to the CSV. Issue a plain `GET` against it, with no `app-id` or `secret-key`, and the response is the file. The link is minted when you list the report and expires 3 minutes later, so do not store it: keep `id` and list the report again for a fresh link. example: >- https://cdn-private.helloclever.co/hellocleverweb-prod/clever/sections/report/9f3c1ab2-5d84-4c11-b0a7-2e6f8c4d1b90?sv=2021-08-06&se=2026-09-07T09%3A03%3A00Z&sr=b&sp=r&sig=... file_url_expires_at: type: string nullable: true description: >- Timestamp when `file_url` stops working (UTC Time), 3 minutes after the response was issued. example: 2026-09-07T09:03:00.000+0000 format: type: string description: File format of the report. example: csv enum: - csv report_frequency: type: string description: > The reporting frequency this report was generated for, matching the frequencies enabled on your account. - `daily`: covers the 24 hours to 09:00 on the generation date - `weekly`: covers the 7 days to 09:00 on the generation date, generated on Mondays - `monthly`: covers the month to 09:00 on the generation date, generated on the 1st example: daily enum: - daily - weekly - monthly currency: type: string example: AUD description: >- Currency of the settled funds, as an ISO 4217 code. One report covers one currency. period_start: type: string description: >- Start of the period the report covers, in your account's configured time zone. example: 2026-09-06T09:00:00.000+1000 period_end: type: string description: >- End of the period the report covers, in your account's configured time zone. example: 2026-09-07T09:00:00.000+1000 generated_at: type: string description: Timestamp when the report was generated (UTC Time). example: 2026-09-07T09:00:14.000+0000 summary: type: object description: > Totals for the period the report covers, so headline figures reconcile without fetching the file. Every figure is derived from the rows in the file itself, rounded to the currency's precision the same way the file rounds them. properties: currency: type: string example: AUD settlement_count: type: integer example: 12 description: >- Number of settlements in the period. Equals the number of rows in the file, excluding the header. settled_amount: type: number example: 31877.4 description: >- Total settled in the period. Positive; the file's `Amount` column carries the same values prefixed with `-` because the funds leave your balance. settled_fee: type: number example: 18.62 description: >- Total fees charged on those settlements. Equals the sum of the file's `Fee amount` column. closing_balance: type: number nullable: true description: >- Your balance immediately after the last settlement in the period. `null` when no settlement in the period carries a ledger-stamped balance yet. example: 9410.2 closing_balance_at: type: string nullable: true description: >- When the ledger stamped `closing_balance`, in your account's configured time zone. `null` whenever `closing_balance` is. example: '2026-09-01T08:52:11.000+10:00' example: from_date: '2026-09-01T00:00:00Z' to_date: '2026-09-30T00:00:00Z' size: 20 next_cursor: MjAyNi0wOS0wMVQwOTowMDowOS4wMDAwMDArMDA6MDB8NDc5NQ== previous_cursor: null has_more: true has_previous: false records: - id: rpt_8KmRvXq3N2dL file_name: Daily Report (AUD) (Sep 06, 2026 - Sep 07, 2026).csv file_url: >- https://cdn-private.helloclever.co/hellocleverweb-prod/clever/sections/report/9f3c1ab2-5d84-4c11-b0a7-2e6f8c4d1b90?sv=2021-08-06&se=2026-09-07T09%3A03%3A00Z&sr=b&sp=r&sig=... file_url_expires_at: 2026-09-07T09:03:00.000+0000 format: csv report_frequency: daily currency: AUD period_start: 2026-09-06T09:00:00.000+1000 period_end: 2026-09-07T09:00:00.000+1000 generated_at: 2026-09-07T09:00:14.000+0000 summary: currency: AUD settlement_count: 3 settled_amount: 4205 settled_fee: 2.34 closing_balance: 12980.55 closing_balance_at: '2026-09-07T08:47:33.000+10:00' - id: rpt_2QbYtF7hJ9wS file_name: Monthly Report (AUD) (Aug 01, 2026 - Sep 01, 2026).csv file_url: >- https://cdn-private.helloclever.co/hellocleverweb-prod/clever/sections/report/2b74de90-1c35-4f88-9a6d-77f1e0c5a413?sv=2021-08-06&se=2026-09-07T09%3A03%3A00Z&sr=b&sp=r&sig=... file_url_expires_at: 2026-09-07T09:03:00.000+0000 format: csv report_frequency: monthly currency: AUD period_start: 2026-08-01T09:00:00.000+1000 period_end: 2026-09-01T09:00:00.000+1000 generated_at: 2026-09-01T09:00:09.000+0000 summary: currency: AUD settlement_count: 12 settled_amount: 31877.4 settled_fee: 18.62 closing_balance: 9410.2 closing_balance_at: '2026-09-01T08:52:11.000+10:00' '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: object properties: code: type: string message: type: string example: errors: code: INVALID_DATE_RANGE message: The requested date range must not exceed 90 days '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: object properties: code: type: string message: type: string example: errors: code: REQUIRE_LOGIN message: Not Authorised '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: object properties: code: type: string message: type: string example: errors: code: UNPROCESSABLE_ENTITY message: from_date is required security: - app-id: [] secret-key: [] components: securitySchemes: app-id: type: apiKey in: header name: app-id description: | A unique identifier assigned to each application. secret-key: type: apiKey in: header name: secret-key description: | A secure token associated with the `app-id`. ```` ## Related topics - [Settlement Reporting](/api/reporting/settlement.md) - [Reporting API Overview](/api/reporting/overview.md) - [Settlement Service: Flexible Fund Access](/services/settlement.md)