Ledger account categories are free-form account groups that can be used to create account hierarchies. Categories can contain other accounts or as well as other categories. The balance of a ledger category is equal to the sum of the balances of all contained accounts. Ledgers supports an unlimited amount of ledger categories.

A best practice is to set up ledger accounts as the lowest level aggregations for your business and use categories to 'rollup' balances as needed. If you are using the ledger to track accounts payable, for instance, you can have each individual vendor you owe represented as an account and use categories to group accounts by state, country, or any other grouping of your choice.

In this guide, we will walk through the following examples: creating a category, adding existing ledger accounts to a new category, adding existing ledger categories to a new category, and querying balances. You can find the API reference for ledger account categories here.

Creating a category

Ledger categories can be created simply by calling our create ledger account category endpoint:

curl --request POST \
     --url https://app.moderntreasury.com/api/ledger_account_categories \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "name": "US Payables",
     "description": "Groups all payable accounts in the United States",
     "normal_balance": "credit",
     "currency": "USD",
     "ledger_id": "78fa571-fe0e-97b2-4228-ccc79018db8e9",
     "metadata": {}
}
'

This would return the following object:

{
  "id": "f1c7e474-e6d5-4741-9f76-04510c8b6d7a",
  "object": "ledger_account_category",
  "name": "US Payables",
  "ledger_id": "78fa571-fe0e-97b2-4228-ccc79018db8e9",
  "description": "Groups all payable accounts in the United States",
  "normal_balance": "credit",
  "balances": {
    "pending_balance": {
      "credits": 0,
      "debits": 0,
      "amount": 0,
      "currency": "USD"
    },
    "posted_balance": {
      "credits": 0,
      "debits": 0,
      "amount": 0,
      "currency": "USD"
    }
  },
  "metadata": {},
  "live_mode": true,
  "created_at": "2022-08-04T16:54:32Z",
  "updated_at": "2022-08-04T16:54:32Z"
}

Note that similar to ledger accounts, account categories take a normal_balance (one of debit or credit) and free-form metadata.

Adding an existing ledger account to a category

We can use the add ledger account to category endpoint to add an account to a category. For this, we simply need the ids of both the parent category and the ledger account we will be nesting under it.

curl --request PUT \
     --url https://app.moderntreasury.com/api/ledger_account_categories/f1c7e474-e6d5-4741-9f76-04510c8b6d7a/ledger_accounts/7244f59-cfd8-8dfa-9466-7de9f42b0b1a9 \
     --header 'Accept: application/json'

After we add an account to a category, it can be removed by using the remove ledger account from category endpoint. This does not affect the underlying transactions, which are immutable, or the underlying account: it simply removes the newly excluded account balance from the category balance calculation.

Finally, to add several accounts to a category, we can use the list ledger transactions endpoint to query transactions by metadata and programmatically add them into a category using the same API call above repeatedly.

Adding an existing ledger category to a category

We can add a ledger account category to another category by using the add ledger account category to category endpoint. For this call, we again need ids of both categories:

curl --request PUT \
     --url https://app.moderntreasury.com/api/ledger_account_categories/40cb8f7-2ba1-c303-bcf7-5605c2f20eb4b/ledger_account_categories/fc5b284-da91-d70a-b43f-fdda68ae21d84 \
     --header 'Accept: application/json'

As above, a category can be removed from another by using the remove ledger account category from category endpoint. This also does not affect underlying transactions: it simply removes the newly excluded child category balance from the parent category balance calculation.

As of now, nested categories up to level 4 are allowed. A root category without any nested category is considered level 0.

Querying balances

We can use the get ledger account categories and list ledger account categories endpoints to return balances from categories in the ledger.

When using the LIST endpoint, you can define queries using parameters such as id, name, ledger_id, parent_ledger_account_category_id and metadata, among other fields. In the example below we are returning two categories that belong to the same ledger.

curl --request GET \
     --url 'https://app.moderntreasury.com/api/ledger_account_categories?ledger_id=6266f306-6441-4b4c-988c-82a6fc3c72fa&per_page=25' \
     --header 'Accept: application/json'

Response:

[
  {
    "id": "17a7e900-435f-419b-848f-a8d80d26b62f",
    "object": "ledger_account_category",
    "live_mode": false,
    "name": "MT Combined Accounts",
    "ledger_id": "6266f306-6441-4b4c-988c-82a6fc3c72fa",
    "description": null,
    "normal_balance": "credit",
    "balances": {
      "pending_balance": {
        "credits": 600,
        "debits": 0,
        "amount": 600,
        "currency": "USD",
        "currency_exponent": 2
      },
      "posted_balance": {
        "credits": 600,
        "debits": 0,
        "amount": 600,
        "currency": "USD",
        "currency_exponent": 2
      },
      "available_balance": {
        "credits": 600,
        "debits": 0,
        "amount": 600,
        "currency": "USD",
        "currency_exponent": 2
      }
    },
    "metadata": {},
    "discarded_at": null,
    "created_at": "2022-06-24T21:27:19Z",
    "updated_at": "2022-06-24T21:27:19Z"
  },
  {
    "id": "0999a267-58dd-4c3f-98e5-9f7af40cc25d",
    "object": "ledger_account_category",
    "live_mode": true,
    "name": "Combined View",
    "ledger_id": "6266f306-6441-4b4c-988c-82a6fc3c72fa",
    "description": "Test Category",
    "normal_balance": "credit",
    "balances": {
      "pending_balance": {
        "credits": 1220,
        "debits": 0,
        "amount": 1220,
        "currency": "USD",
        "currency_exponent": 2
      },
      "posted_balance": {
        "credits": 900,
        "debits": 0,
        "amount": 900,
        "currency": "USD",
        "currency_exponent": 2
      },
      "available_balance": {
        "credits": 900,
        "debits": 0,
        "amount": 900,
        "currency": "USD",
        "currency_exponent": 2
      }
    },
    "metadata": {},
    "discarded_at": null,
    "created_at": "2022-06-24T17:55:18Z",
    "updated_at": "2022-06-24T17:55:18Z"
  }
]

Note that, similar to ledger accounts, categories also feature pending, posted, and available balances.