Ledgers

Ledgers overview

Learn how ledgers work in Blnk

Blnk uses a structured ledger system to organize and group account balances effectively. This system simplifies navigation and improves the clarity and accessibility of financial data.

When setting up Blnk for your application, the first step is to create ledgers. Since balances need to be grouped within a ledger, you cannot create balances without one. Therefore, it’s essential to plan how you want to categorize your balances before you begin.

To learn more, see the following: Ledger architecture.

Types of ledgers in Blnk

Blnk includes two types of ledgers - a General Ledger and custom ledgers.

1. General Ledger: This built-in ledger is designed to group balances that represent accounts owned by your organization, similar to a Chart of Accounts.

   Unlike custom ledgers, balances in the General Ledger come with indicators, making it easier to reference them in your code when recording transactions. To learn more about the General Ledger, see the following: General Ledger.

2. Custom ledgers: These are ledgers you create based on the ledger architecture you’ve defined for your application.

Creating a ledger

Using the API

To create a ledger, call the Create Ledger endpoint:

curl -X POST "http://localhost:5001/ledgers" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Savings Account",
    "meta_data": {
        "project_owner": "YOUR_APP_NAME"
    }
  }'

const response = await blnk.Ledgers.create({
  name: 'Customer Savings Account',
  meta_data: {
    project_owner: 'YOUR_APP_NAME',
  },
});

ledger, _, _ := client.Ledger.Create(blnkgo.CreateLedgerRequest{
    Name: "Customer Savings Account",
    MetaData: blnkgo.MetaData{
        "project_owner": "YOUR_APP_NAME",
    },
})

response = blnk.ledgers.create({
  "name": "Customer Savings Account",
  "meta_data": {
    "project_owner": "YOUR_APP_NAME",
  },
})

ApiResponse<JsonNode> response = blnk.ledgers().create(
    CreateLedger.create()
        .name("Customer Savings Account")
        .metaData(Map.of("project_owner", "YOUR_APP_NAME")));

blnk ledgers create

{
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "name": "Customer Savings Account",
    "created_at": "2024-12-21T01:36:46.997063436Z",
    "meta_data":{
        "project_owner": "YOUR_APP_NAME"
    }
}

Using the Dashboard

You can also create a custom ledger from the dashboard. The General Ledger is already there when your instance is deployed.

Updating a ledger name

You can rename an existing ledger using the Update Ledger Name endpoint without affecting any balances or transactions:

curl -X PUT "http://localhost:5001/ledgers/{id}" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Customer Savings Account"
  }'

const response = await blnk.Ledgers.update(
  'ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc',
  {
    name: 'Updated Customer Savings Account',
  },
);

ledger, _, _ := client.Ledger.Update(
    "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    blnkgo.UpdateLedgerRequest{
        Name: "Updated Customer Savings Account",
    },
)

response = blnk.ledgers.update(
  "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
  {
    "name": "Updated Customer Savings Account",
  },
)

ApiResponse<JsonNode> response = blnk.ledgers().update(
    "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    UpdateLedger.create()
        .name("Updated Customer Savings Account"));

blnk ledgers update-name

{
  "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
  "name": "Updated Customer Savings Account",
  "created_at": "2024-12-21T01:36:46.997063436Z"
}

Practical example

Here’s an example with seven accounts to illustrate how to use ledgers in Blnk:

With Blnk’s ledger functionality, you can categorize these accounts by name, type, or other criteria that fit your organizational needs.

This helps you maintain clean, organized records that are easy to search and manage. As your data scales, this categorization becomes even more valuable, enabling you to conduct deeper analyses, identify patterns, and make more informed decisions.

Ledger grouping by type

In this approach, accounts are organized by type rather than by individual customer. Two separate ledgers are created- one for “Savings Accounts” and another for “Checking Accounts.” This setup groups accounts by their function, making it easy to reference all accounts within a specific type.

In this example, there are 5 savings accounts and 4 checking accounts across 7 unique customers. But customers like Jasper Hale and Ruby Foster have both types of accounts, which means they appear in both ledgers.

This type-based grouping provides a clear breakdown of accounts, showing which accounts fall under savings and which under checking. This can be useful for tracking and reference, particularly if you need to analyze account activity or usage patterns based on account type.

Ledger grouping by name

In this approach, rather than organizing accounts by type (e.g., Savings or Checking), we create a separate ledger for each unique customer. This allows each customer’s accounts to be listed together under their name, making it easy to view all accounts belonging to a single individual.

Each ledger entry is focused on the customer, showing all accounts that the customer holds. For instance, Jasper Hale and Ruby Foster each have both a checking and a savings account, so both account types are listed under their names.

This customer-focused organization makes it easy to see all account types associated with each individual. It can be helpful when managing customer relationships or viewing a comprehensive overview of each customer’s financial engagement in the system.