> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ledger accounts

> Learn how Tesouro handles ledger accounts from your accounting system.

## Overview

A **general ledger** (GL) account is a component of an accounting system that is used to record and categorize a company's financial transactions. Some examples of common ledger accounts are:

* Expenses: office supplies, utilities, salaries, taxes, and so on,
* Income: sales and revenue, dividends, and so on,
* Assets: cash, inventory, and so on,
* Liabilities: accounts payable, debt, and so on.

Within an accounting system, each line item on an invoice is assigned a ledger account in order to properly categorize various expenses and income sources. In Tesouro, the `ledger_account_id` field of [products](/finops/guides/accounts-receivable/products) and payable [line items](/finops/guides/accounts-payable/payables/line-items) is used to assign ledger accounts to business objects. Additionally, the organization setting `accounting.ledger_account_ids.payments` specifies the ledger account for all [payment records](/finops/guides/common/payment-records).

Tesouro supports two types of ledger accounts:

* **External ledger accounts** (`is_external = true`): These are pulled from connected accounting systems and are read-only in Tesouro. They reflect the chart of accounts from your external accounting software.
* **Internal ledger accounts** (`is_external = false`): These are created and managed directly within Tesouro, giving you flexibility to define custom accounts for your business needs.

Products and payables *pulled* from the accounting system have the `ledger_account_id` pre-filled. However, when new products, payables, and payment records are created in Tesouro, the user must manually specify the `ledger_account_id` for those objects. This is required for Tesouro to be able to *push* those objects to the accounting system.

## External ledger accounts

For external ledger accounts, the typical flow is as follows:

1. After connecting an organization to an accounting system, wait until the initial data pull is completed.
2. Call [`GET /ledger-accounts`](/finops/reference/openapi/ledger-accounts/get-ledger-accounts) to get a list of an organization's general ledgers pulled from the accounting system.
3. If an organization uses accounts payable:
   1. Get the line items of all payables and check if the line items have `ledger_account_id`.
   2. If any line item is missing a value for `ledger_account_id`, prompt the user to assign the appropriate ledger account.
4. If an organization uses accounts receivable:
   1. Get all products and check if they have `ledger_account_id`.
   2. If any product is missing a value for `ledger_account_id`, prompt the user to assign the appropriate ledger account.
5. If an organization uses payment records:
   1. Prompt the user to specify a ledger account for all payment records and store the account ID in the [organization setting](/finops/reference/openapi/identity/patch-organizations-id-settings) `accounting.ledger_account_ids.payments`.

## Internal ledger accounts

You can create internal ledger accounts directly in Tesouro using the `POST /ledger-accounts` endpoint:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/ledger-accounts' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "Marketing Expenses",
       "nominal_code": "4500",
       "description": "Expenses related to marketing and advertising activities"
     }'
```

The successful `201` response returns the created ledger account:

```json lines theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2025-09-11T10:00:56.855Z",
  "updated_at": "2025-09-11T10:00:56.855Z",
  "currency": "USD",
  "current_balance": 0,
  "description": "Expenses related to marketing and advertising activities",
  "is_bank_account": true,
  "is_external": false,
  "name": "Accounts Receivable",
  "nominal_code": "610",
  "status": "Active",
  "subtype": "Current",
  "type": "Asset"
}
```

<Info>
  All fields in the create request are optional. Internal ledger accounts are created with
  `is_external = false` by default.
</Info>

## Get ledger accounts

After connecting to an accounting system, Tesouro automatically retrieves a list of ledger accounts from there. Once the initial data synchronization has completed, you can call [`GET /ledger-accounts`](/finops/reference/openapi/ledger-accounts/get-ledger-accounts) to get an organization's ledger accounts that exist in the accounting system:

```sh lines theme={null}
curl 'https://api.sandbox.tesouro.com/v1/ledger-accounts' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

Below is an example of ledger account details. Note down the IDs of the ledger accounts - these are the possible values of the `ledger_account_id` field in products and payable line items.

```json expandable lines theme={null}
{
  "data": [
    {
      "id": "f5f85999-cc35-43e6-93ad-46d22907022a",
      "currency": "USD",
      "current_balance": 0,
      "description": "Outstanding invoices the company has issued out to the client but has not yet received in cash at balance date.",
      "is_bank_account": false,
      "is_external": true,
      "name": "Accounts Receivable",
      "nominal_code": "610",
      "status": "Active",
      "subtype": "Current",
      "type": "Asset"
    },
    {
      "id": "8ecb60fd-88fd-40e4-8bd9-5fa154435b78",
      "currency": "USD",
      "current_balance": 0,
      "description": "Income from business activity",
      "is_bank_account": true,
      "name": "Sales",
      "nominal_code": "200",
      "type": "Income",
      "status": "Active",
      "subtype": "Revenue"
    },
    ...
  ],
  "next_pagination_token": null,
  "prev_pagination_token": null
}
```

The [`GET /ledger-accounts`](/finops/reference/openapi/ledger-accounts/get-ledger-accounts) endpoint can also be used to retrieve internal ledger accounts by setting the query parameter `is_external = false` (e.g., `GET /ledger-accounts?is_external=false`).

To get information about a specific ledger account, call `GET /ledger-accounts/{ledger_account_id}`.

## Edit a ledger account

To edit an existing ledger account, call `PATCH /ledger-accounts/{ledger_account_id}`.

<Note>This operation is only available for cost centers where `is_external = false`.</Note>

## Delete a ledger account

To delete a specific ledger account, call `DELETE /ledger-accounts/{ledger_account_id}`.

<Note>This operation is only available for cost centers where `is_external = false`.</Note>

## Assign ledger accounts to products and payable line items

Before payables can be pushed to an accounting system, each line item in all payables must have the `ledger_account_id` specified. Similarly, before Account Receivable invoices can be pushed to accounting, all products listed on invoices must have the `ledger_account_id` specified.

To specify an associated ledger account for a payable line item or a product, PATCH this object and provide the value for `ledger_account_id`. For example:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/products/51846...39d' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "ledger_account_id": "f5f85999-cc35-43e6-93ad-46d22907022a"
     }'
```

## Assign a ledger account to payment records

Before [payment records](/finops/guides/common/payment-records) can be pushed to an accounting system, the organization must specify
the ledger account for these records.
To do this, store the account ID in the organization setting `accounting.ledger_account_ids.payments`:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/identity/v1/organizations/daf8e...5e7/settings' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "accounting": {
         "ledger_account_ids": {
           "payments": "f5f85999-cc35-43e6-93ad-46d22907022a"
         }
       }
     }'
```

The specified ledger account will be used both for manually added payment records and for payments made via Tesouro [payment page](/finops/guides/payments/payment-links).

<Info>
  This setting can be changed at any time, but it will have no impact on payment records that have
  already been pushed.
</Info>