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

# Ledger

A **Ledger** is the highest-level resource in Segment Ledgers. It represents an isolated financial environment that contains its own accounts, balances, transactions, statements, and accounting entries.

Every financial operation takes place within a ledger. Resources belonging to one ledger are completely isolated from resources in another, making ledgers ideal for multi-tenant applications, organizations, business units, or separate financial products.

A ledger acts as the container for all accounting activity and ensures that balances and transactions remain independent and fully auditable.

## Why Use Multiple Ledgers?

Using separate ledgers allows you to isolate financial data based on your application's architecture.

Common use cases include:

* One ledger per customer
* One ledger per merchant
* One ledger per organization
* One ledger per business
* One ledger per platform
* One ledger per project
* One ledger per environment (Development, Staging, Production)

Each ledger maintains its own:

* Accounts
* Balances
* Transactions
* Journal Entries
* Statements
* Metadata

Data is never shared across ledgers.

## Ledger Architecture

A ledger contains all financial resources required to record accounting activity.

```
Ledger
│
├── Accounts
│     ├── Treasury
│     ├── Customer Wallet
│     ├── Merchant Wallet
│     └── Fee Account
│
├── Transactions
│
├── Entries
│
├── Statements
│
└── Balances
```

## Ledger Lifecycle

A typical ledger lifecycle follows these steps:

1. Create a ledger.
2. Create one or more accounts.
3. Fund the accounts.
4. Process transactions.
5. Retrieve statements.
6. Reconcile balances.

Once a ledger is created, you can begin creating accounts and recording financial activity immediately.

## Ledger Object

A ledger object represents a single accounting environment.

### Example

```json
{
    "id": "led_01J9T3M2X5AB7C8D9EFGH12345",
    "name": "Production Ledger",
    "description": "Primary production ledger",
    "status": "ACTIVE",
    "currency": "EUR",
    "metadata": {
        "environment": "production"
    },
    "created_at": "2026-08-05T14:12:18.462Z",
    "updated_at": "2026-08-05T14:12:18.462Z"
}
```

## Ledger Attributes

| Field         | Type      | Description                                 |
| ------------- | --------- | ------------------------------------------- |
| `id`          | String    | Unique identifier of the ledger.            |
| `name`        | String    | Human-readable ledger name.                 |
| `description` | String    | Optional description of the ledger.         |
| `status`      | String    | Current ledger status.                      |
| `currency`    | String    | Default ledger currency (if configured).    |
| `metadata`    | Object    | Custom application-defined data.            |
| `created_at`  | Timestamp | Date and time the ledger was created.       |
| `updated_at`  | Timestamp | Date and time the ledger was last modified. |

## Create a Ledger

Creates a new ledger.

```
POST /v1/ledgers
```

## Create a Ledger

<mark style="color:green;">`POST`</mark> `/v1/ledgers`

Creates a new ledger.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer API Key`   |

**Body**

| Name          | Type   | Description                      |
| ------------- | ------ | -------------------------------- |
| `name`        | string | Name of the ledger.              |
| `description` | string | Description of the ledger.       |
| `metadata`    | object | Additional application metadata. |

**Example Request**

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

```json
{
    "name": "Production Ledger",
    "description": "Primary accounting ledger",
    "metadata": {
        "environment": "production",
        "region": "eu-west-1"
    }
}
```

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
    "statusCode": 201,
    "statusMessage": "Ledger created successfully",
    "payload": {
        "id": "led_01J9T3M2X5AB7C8D9EFGH12345",
        "name": "Production Ledger",
        "description": "Primary accounting ledger",
        "status": "ACTIVE",
        "created_at": "2026-08-05T14:12:18.462Z"
    }
}
```

{% endtab %}
{% endtabs %}