> For the complete documentation index, see [llms.txt](https://docs.ezeebit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ezeebit.com/customer-accounts/customer-account-ledger.md).

# Customer Account Ledger

Page a customer account's transaction history.

**Live:**

<mark style="color:green;">`POST`</mark> [<mark style="color:blue;">https://api.ezeebit.com/open/api/v1/customerAccount/ledger</mark>](https://api.ezeebit.com/open/api/v1/customerAccount/ledger)

**UAT:**

<mark style="color:green;">`POST`</mark> [<mark style="color:blue;">https://uat-api.ezeebit.com/open/api/v1/customerAccount/ledger</mark>](https://uat-api.ezeebit.com/open/api/v1/customerAccount/ledger)

## Headers

| Name                   | Type   | Required | Value                          |
| ---------------------- | ------ | -------- | ------------------------------ |
| Content-Type           | string | Y        | application/json               |
| Ezeebit-Timestamp      | long   | Y        | Unix timestamp in milliseconds |
| Ezeebit-Nonce          | string | Y        | 32 characters                  |
| Ezeebit-Certificate-SN | string | Y        | API key issued by Ezeebit Pay  |
| Ezeebit-Signature      | string | Y        | Uppercase SHA512 signature     |

## Request Body

```json
{
  "customerAccountId": "cust-1001",
  "pageIndex": 1,
  "pageSize": 20,
  "fromTimestamp": 1759276800000,
  "toTimestamp": 1761955199999
}
```

## Form data

| Parameter         | Type   | Required | Description                                             |
| ----------------- | ------ | -------- | ------------------------------------------------------- |
| customerAccountId | string | Yes      | The account to read.                                    |
| pageIndex         | int    | No       | Page number. Default `1`.                               |
| pageSize          | int    | No       | Rows per page. `1`–`100`. Default `20`.                 |
| fromTimestamp     | long   | No       | Earliest `createdAt` to include, in epoch milliseconds. |
| toTimestamp       | long   | No       | Latest `createdAt` to include, in epoch milliseconds.   |

Newest entries come first. Both bounds are inclusive and work on their own; omit both for the full history. Every entry carries its own `balanceAfter`, so you can rebuild the running balance without reading the live one.

A withdrawal is written when it completes. Until then its amount is held and isn't in `balance`.

## Response

| Status | Description                |
| ------ | -------------------------- |
| 200    | Entries returned           |
| 10121  | Customer account not found |

### Response fields

<table><thead><tr><th width="170">Field</th><th width="90">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>long</td><td>Ledger entry ID. The same value is the <code>ledgerEntryId</code> on the <a href="https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md">Wallet Webhook</a></td></tr><tr><td>createdAt</td><td>long</td><td>Epoch milliseconds</td></tr><tr><td>entryType</td><td>string</td><td><code>DEPOSIT</code>, <code>WITHDRAW</code>, <code>CONVERT</code> or <code>TRANSFER</code></td></tr><tr><td>source</td><td>string</td><td>Where the movement was requested: <code>OPEN_API</code> or <code>MERCHANT_PORTAL</code>. <code>null</code> on a deposit</td></tr><tr><td>description</td><td>string</td><td>For example <code>Chain deposit</code> or <code>Transfer from merchant wallet</code></td></tr><tr><td>reference</td><td>string</td><td>The transaction hash on a deposit or withdrawal, the <code>conversionId</code> on a conversion, and the <code>transferId</code> on a transfer</td></tr><tr><td>debitAmount</td><td>string</td><td>Amount out of the account</td></tr><tr><td>creditAmount</td><td>string</td><td>Amount into the account</td></tr><tr><td>balanceAfter</td><td>string</td><td>Balance straight after this entry</td></tr></tbody></table>

{% tabs %}
{% tab title="200" %}

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "totalCount": 2,
    "totalPage": 1,
    "pageSize": 20,
    "currentPageNo": 1,
    "data": [
      {
        "id": 3108,
        "createdAt": 1761811200000,
        "entryType": "TRANSFER",
        "source": "OPEN_API",
        "description": "Transfer from merchant wallet",
        "reference": "0b7d4c2e-91a3-4f6e-b8d2-5c1a9e7f3d40",
        "debitAmount": "0.00000000",
        "creditAmount": "50.00000000",
        "balanceAfter": "300.00000000"
      },
      {
        "id": 3107,
        "createdAt": 1761800400000,
        "entryType": "DEPOSIT",
        "source": null,
        "description": "Chain deposit",
        "reference": "0x8d2e...",
        "debitAmount": "0.00000000",
        "creditAmount": "250.00000000",
        "balanceAfter": "250.00000000"
      }
    ]
  }
}
```

{% endtab %}

{% tab title="10121" %}

```json
{
  "code": 10121,
  "msg": "Customer account not found",
  "data": null
}
```

{% endtab %}
{% endtabs %}
