> ## Documentation Index
> Fetch the complete documentation index at: https://developer.novacpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance Report

> Fetch your wallet balance history across a date range, returned inline for small datasets or delivered to your email for larger exports.

## Overview

The Balance Report API lets merchants retrieve a ledger of all wallet movements i.e **payouts**, **settlement fees**, **credits**, and more. Its filtered by currency and date range.

<Info>
  Results under **1,000 records** are returned directly in the API response while results over **1,000 records** are compiled into a CSV and sent to your registered email address automatically.
</Info>

***

## Fetch Balance Report

Retrieve a chronological ledger of wallet movements including payouts, settlement fees, credits, and debits, filtered by currency and date range.

<Note>
  This endpoint requires your **Secret Key** for authentication. Never expose your Secret Key in client-side code.
</Note>

### Path Parameters

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| `currency`  | string | ✓        | `NGN`, `GHS`, `USD` |
| `startdate` | string | ✓        | Start of date range |
| `enddate`   | string | ✓        | End of date range   |

<Warning>
  Both dates must follow the `yyyy-MM-dd`. The maximum range between `startdate` and `enddate` is **6 months**.
</Warning>

***

### Get Record

```bash Request theme={null}
curl --request GET \
  --url https://api.novacpayment.com/api/v1/balancereport/NGN/2026-06-05/2026-07-01 \
  --header 'Authorization: Bearer <your-secret-key>'
```

When the result set is **1,000 records or fewer**, the full ledger is returned in the response body.

```json Response theme={null}
{
  "status": true,
  "message": "Balance report details retrieved successfully",
  "data": [
    {
      "type": "payout",
      "isDebit": "yes",
      "currency": "NGN",
      "domain": "live",
      "amount": "1,186.50",
      "balanceBefore": "2,730.89",
      "balanceAfter": "1,544.39",
      "reference": "XXXXXXXXXXXXXXXXXXXXXX",
      "note": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "status": "successful",
      "date": "27/06/2026 00:30"
    },
    {
      "type": "settlement_fee",
      "isDebit": "yes",
      "currency": "NGN",
      "domain": "live",
      "amount": "18.00",
      "balanceBefore": "2,748.89",
      "balanceAfter": "2,730.89",
      "reference": "XXXXXXXXXXXXXXXXXXXXX",
      "note": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "status": "successful",
      "date": "27/06/2026 00:30"
    }
  ]
}
```

***

### Large export sent by email

When the result set **exceeds 1,000 records**, the report is compiled into a CSV file and sent to your registered merchant email. The API response confirms the dispatch.

```json theme={null}
{
  "status": true,
  "message": "Balance report sent to your email address"
}
```

<Info>
  Check the email address registered on your Novac merchant account. The CSV is typically delivered within a few minutes. If you don't see it, check your spam folder.
</Info>

***

### Error Responses

| Scenario                            | Response                                                                         |
| ----------------------------------- | -------------------------------------------------------------------------------- |
| No records found for the date range | `"No balance record found for date range : 2026-01-01 to 2026-01-24"`            |
| Wrong date format                   | `"End Date format is wrong please use the format :: yyyy-MM-dd (eg 2025-02-09)"` |
| Range exceeds 6 months              | `"You can only pull a maximum of 6 months No balance report."`                   |
| Start date is after end date        | `"Start Date cannot be greater than End Date."`                                  |

All error responses follow this structure:

```json theme={null}
{
  "status": false,
  "message": "<error description>"
}
```

***

## What next ?

* [Transfer funds from your wallet to a bank account](/docs/make-payment/make-payout)
* [Manage Teams](/docs/accounts/manage-teams)