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

# Get Merchant Balance

> Retrieve wallet balances for a sub-merchant across all currencies.

# Get Merchant Balance

Retrieve the wallet balances for a specific sub-merchant in your marketplace. Returns balances for all currencies the merchant has received payments in.

## Path Parameters

<ParamField path="merchantId" type="string" required>
  The ID of the sub-merchant to retrieve balances for.
</ParamField>

## Response

```json theme={null}
{
  "success": true,
  "message": "Merchant balance retrieved successfully",
  "data": {
    "merchant_id": 1676,
    "balances": [
      {
        "currency": "NGN",
        "balance": 1250000,
        "formatted_balance": "NGN 12500.00",
        "total_credits": 1500000,
        "total_debits": 250000,
        "transaction_count": 45
      },
      {
        "currency": "USD",
        "balance": 85000,
        "formatted_balance": "USD 850.00",
        "total_credits": 100000,
        "total_debits": 15000,
        "transaction_count": 12
      }
    ]
  }
}
```

## Response Fields

### balances (array)

| Field               | Type   | Description                                            |
| ------------------- | ------ | ------------------------------------------------------ |
| `currency`          | string | Currency code (e.g., `NGN`, `USD`, `GBP`)              |
| `balance`           | number | Current balance in smallest currency unit (cents/kobo) |
| `formatted_balance` | string | Human-readable balance with currency symbol            |
| `total_credits`     | number | Total credits received in smallest unit                |
| `total_debits`      | number | Total debits (payouts/refunds) in smallest unit        |
| `transaction_count` | number | Total number of wallet transactions                    |

## Balance Calculation

The balance is calculated as:

```
balance = total_credits - total_debits
```

**Credits** include:

* Successful payment settlements from charges

**Debits** include:

* Payouts to bank accounts
* Refunds issued

## Currency Units

All amounts are returned in the smallest currency unit:

| Currency      | Unit        | Example             |
| ------------- | ----------- | ------------------- |
| USD, GBP, EUR | cents       | 85000 = \$850.00    |
| NGN           | kobo        | 1250000 = 12,500.00 |
| JPY, KRW, VND | whole units | 1000 = 1,000        |

## Error Codes

| Status | Error                                                  | Fix                                                     |
| ------ | ------------------------------------------------------ | ------------------------------------------------------- |
| `403`  | `This endpoint is restricted to marketplace operators` | Your account must have marketplace mode enabled         |
| `404`  | `Active merchant relationship not found`               | The merchant is not actively linked to your marketplace |

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/balance \
    -H "X-API-Key: pk_sandbox_your_key"
  ```
</RequestExample>