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

{
    "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

POST /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

JSON

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

Response

200

{
    "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"
    }
}