Overview
Line item refers to any service or product added to a payable, along with their descriptions, quantities, rates, and prices. Every payable contains descriptions of all items purchased. Thetotal, subtotal, and tax_amount fields of a line item are stored exactly as you send them. Tesouro does not calculate, cross-check, or back-fill these values from unit_price, quantity, or tax — if you omit one, it stays null rather than being derived. These fields also aren’t validated against each other, so tax_amount doesn’t need to reconcile with subtotal and total, and subtotal doesn’t need to sum to the payable’s subtotal.
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: $10Add line items to a payable
To add line items to a payable, send aPOST request to the /payables/{payable_id}/line-items endpoint:
List all line items of a payable
To list all line items of a specific payable, send aGET request to the /payables/{payable_id}/line-items endpoint:
Retrieve a line item
To retrieve information from a specific line item in a payable, send aGET request to the /payables/{payable_id}/line-items/{line_item_id} endpoint:
Update a specific line item
To update some information about a specific line item in a payable, send aPATCH request to the /payables/{payable_id}/line-items/{line_item_id} endpoint:
Update a payable and selected line items
This combined PATCH is available while a payable is in thedraft or new status.
Use line_items in PATCH /payables/{payable_id} to add, replace, or remove selected line items in the same request as payable fields. A replacement uses the existing line item’s id and a complete line item in data; its ID stays the same. You do not need to resend line items that are unchanged. Tesouro applies the payable and line-item changes together. It stores the monetary amounts you supply as sent; changing line items does not recalculate the payable’s subtotal or total_amount.
add takes complete line item objects, replace takes an existing ID and complete replacement data, and remove takes existing IDs. Omit line_items when you only need to change payable fields. If an ID is unknown or repeated, operations conflict, or the request is invalid, the PATCH fails without applying part of the update. Use the individual line item endpoints above for a single item, or the PUT endpoint below to replace the entire collection. Payable history records header changes and line item changes separately.
Replace all line items
You can also replace all line items of a specific payable at once by sending aPUT request to the /payables/{payable_id}/line-items endpoint:
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.Remove a line item
To remove the line item from the payable, send aDELETE request to the /payables/{payable_id}/line-items/{line_item_id} endpoint: