> ## 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.

# Line items in payables

> Manage line items on payables including descriptions, quantities, unit prices, taxes, and automatic total calculations.

## Overview

[Line item](/finops/support/glossary#line-item) refers to any service or product added to a payable, along with their descriptions, quantities, rates, and prices. Every [payable](/finops/support/glossary#payable) contains descriptions of all items purchased.

By default, the `subtotal` and `total` fields of line items are automatically calculated based on the `unit_price`, `quantity`, and `tax` fields, therefore, are read-only and appear only in the response schema.

<Note>
  When an item is processed via OCR, the line items quantity and unit price may be extracted in a way that leads to rounding discrepancies. In this case, the API may adjust its quantity and unit price to prevent rounding issues and ensure accurate calculations while keeping the total price unchanged, ensuring they align with the invoice. When it happens, the line item field `ocr_set_quantity_to_one` is set to `true`.

  Example of an adjustment:

  **Before:** `Quantity: 2000`, `Price: $10`, `Unit Price: $0.005` (rounded to `$0.01` due to minor units)
  **After:** `Quantity: 1`, `Price: $10`, `Unit Price: $10`
</Note>

## Add line items to a payable

To add line items to a payable, send a `POST` request to the `/payables/{payable_id}/line-items` endpoint:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payables/{payable_id}/line-items' \
     -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": "Ice cream",
        "description": "A delicious vanilla ice cream",
        "quantity": 1,
        "unit": "unit",
        "unit_price": 1200,
        "tax": 1250,
        "ledger_account_id": "7df884fd-8be8-4eba-b6ff-417b66efe033",
        "accounting_tax_rate_id": "dd13735f-ef3a-4312-8c37-835d70341375"
      }'
```

The successful response contains information about the created line item:

```json expandable lines theme={null}
{
  "name": "Ice cream",
  "description": "A delicious vanilla ice cream",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "quantity": 1,
  "unit": "unit",
  "unit_price": 1200,
  "total": 1350,
  "tax": 12500,
  "tax_amount": 150,
  "subtotal": 1200,
  "ledger_account_id": "7df884fd-8be8-4eba-b6ff-417b66efe033",
  "was_created_by_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
  "accounting_tax_rate_id": "dd13735f-ef3a-4312-8c37-835d70341375",
  "payable_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

## List all line items of a payable

To list all line items of a specific payable, send a `GET` request to the `/payables/{payable_id}/line-items` endpoint:

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

```

You will get a list of all line items present in the informed payable:

```json expandable lines theme={null}
{
  "data": [
    {
      "name": "Ice cream",
      "description": "A delicious vanilla ice cream",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 1,
      "unit": "unit",
      "unit_price": 1200,
      "total": 1350,
      "tax": 1250,
      "tax_amount": 150,
      "subtotal": 1200,
      "ledger_account_id": "7df884fd-8be8-4eba-b6ff-417b66efe033",
      "was_created_by_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
      "accounting_tax_rate_id": "dd13735f-ef3a-4312-8c37-835d70341375",
      "payable_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    {
      "name": "Cake",
      "description": "A chocolate cake",
      "id": "12188fc1-493d-48a7-aea8-382240dd7ce7",
      "quantity": 1,
      "unit": "unit",
      "unit_price": 1200,
      "total": 1350,
      "tax": 1250,
      "tax_amount": 150,
      "subtotal": 1200,
      "ledger_account_id": "7df884fd-8be8-4eba-b6ff-417b66efe033",
      "was_created_by_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
      "accounting_tax_rate_id": "dd13735f-ef3a-4312-8c37-835d70341375",
      "payable_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}
```

## Retrieve a line item

To retrieve information from a specific line item in a payable, send a `GET` request to the `/payables/{payable_id}/line-items/{line_item_id}` endpoint:

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

## Update a specific line item

To update some information about a specific line item in a payable, send a `PATCH` request to the `/payables/{payable_id}/line-items/{line_item_id}` endpoint:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/payables/{payable_id}/line-items/{line_item_id}' \
     -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": "Double ice cream"}'
```

## Replace all line items

You can also replace all line items of a specific payable at once by sending a `PUT` request to the `/payables/{payable_id}/line-items` endpoint:

```sh expandable lines theme={null}
curl -X PUT 'https://api.sandbox.tesouro.com/v1/payables/{payable_id}/line-items' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
        "data": [
          {
            "description": "A delicious vanilla ice cream",
            "name": "Ice cream",
            "quantity": 1,
            "subtotal": 1200,
            "tax": 1250,
            "total": 1350,
            "unit": "unit",
            "unit_price": 1200
          }
        ]
      }'
```

<Note>
  This action removes all existing line items of a payable and recreates them with the new data. As
  a result, all line items get new `id` values.
</Note>

## Remove a line item

To remove the line item from the payable, send a `DELETE` request to the `/payables/{payable_id}/line-items/{line_item_id}` endpoint:

```sh lines theme={null}
curl -X DELETE 'https://api.sandbox.tesouro.com/v1/payables/{payable_id}/line-items/{line_item_id}`' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```