Skip to main content

​
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 and payable 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. 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 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 accounting.ledger_account_ids.payments.

​
Internal ledger accounts

You can create internal ledger accounts directly in Tesouro using the POST /ledger-accounts endpoint: 
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: 
{
  "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"
}
All fields in the create request are optional. Internal ledger accounts are created with is_external = false by default.

​
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 to get an organization’s ledger accounts that exist in the accounting system: 
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. 
{
  "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 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}.
This operation is only available for cost centers where is_external = false.

​
Delete a ledger account

To delete a specific ledger account, call DELETE /ledger-accounts/{ledger_account_id}.
This operation is only available for cost centers where is_external = false.

​
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: 
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 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: 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/entities/daf8e...5e7' \
     -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.
This setting can be changed at any time, but it will have no impact on payment records that have already been pushed.