Creating a Ledger

Create a new Ledger in the Console to isolate Assets, Accounts, Routes, and Transactions, and configure Account Type or Route validation while you set it up.

A Ledger isolates Assets, Accounts, Routes, and Transactions in one accounting workspace. Create a new Ledger when you need a separate balance domain, product line, environment, or accounting model.

Before you start

---

You need an existing Organization. If this is the first setup, create the Organization first in Creating an Organization.

Decide what the Ledger boundary means before you create it. Do not use one Ledger for unrelated products that need different account structures, routes, or operational controls.

Create the Ledger

---

1. From the Ledgers page, click the New Ledger button in the top-right corner.

2. The New Ledger form appears.

3. In the Ledger Details tab, enter the Ledger name in the Ledger Name field.

4. (Optional) To include metadata, select the Metadata tab. This tab displays two fields: Key and Value.

   • To add more metadata, click the plus (+) icon next to the first row.
5. (Optional) Select the Settings tab to configure validation rules for this Ledger.

   • Enable Validate Account Type if Accounts must use registered Account Types.
   • Enable Validate Routes if Transactions must follow pre-configured Accounting Routes.
6. After you complete the form, click Save.

7. A success message appears in the top-right corner. The main Ledgers page now lists the new Ledger.

Field guide

---

Field	What to enter	Example
Ledger Name	A clear name for the accounting workspace. Use a name that shows the product, country, environment, or business boundary.	Brazil Payments Ledger
Metadata Key	Optional classification or integration field name.	environment
Metadata Value	Value for the metadata key.	production
Validate Account Type	Optional setting. Turn on when every non-external Account in this Ledger must use a previously registered Account Type. Leave off if you will not classify Accounts by type yet.	Enabled
Validate Routes	Optional setting. Turn on only after the Accounting Routes for this Ledger are planned or configured, because Transactions must match a valid route when this is enabled.	Disabled

The fields in the Metadata tab are open. The tab has no predefined keys or values. Use consistent key names across your Organization, such as environment, businessLine, or region, so you can filter and audit Ledgers later.

Ledger settings

---

The Settings tab controls the validation rules for this Ledger.

Validate Account Type

When you enable this setting, every new non-external Account must use an Account Type registered for this Ledger. Enable it when you want operators to classify Accounts consistently, such as customer, merchant, treasury, or fee.

After you enable Validate Account Type, the Ledger rejects any non-external Account without a valid Account Type.

Validate Routes

When you enable this setting, Transactions must match the Accounting Routes configured for this Ledger. Enable it only after you plan or configure your route model.

If you enable Validate Routes before routes exist, any Transaction without a matching route fails validation.

What to do next

---

After you create the Ledger:

1. Review whether Validate Account Type and Validate Routes are correct for this Ledger.
2. Create at least one Asset in Creating an Asset.
3. If you need to change the validation rules later, use the Settings tab described in Managing Ledgers.

API equivalent

Create a Ledger endpoint