> ## 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.
# Manage invoices
> Learn how to manage invoices and change invoice statuses.
## Update an invoice
All newly created invoices start in the `draft` status. You can edit draft invoices before issuing them to a counterpart.
To edit a draft invoice, send a `PATCH` request to the [`/receivables/{receivable_id}`](/finops/reference/openapi/receivables/patch-receivables-id) endpoint with the request body containing the updated properties. You can update counterpart data, [payment terms](/finops/guides/common/payment-terms), invoice memo, existing line items data, and other details.
```sh expandable lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"invoice": {
"currency": "USD",
"counterpart_id": "782b6f0f-0177-475c-b1e4-98dc160a656f",
"counterpart_billing_address_id": "796d1f1d-f345-4888-849c-6cbcfbd39982",
"payment_terms_id": "f7c577590-2680-462a-a2b4-7c564f65449d",
"entity_bank_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"entity": {
"logo": "https://new-organization-logo.com/icon-192x192.png",
"email": "example@email.com"
}
}
}'
```
When updating an invoice's counterpart, you must also provide the new counterpart's `counterpart_billing_address_id` in the request object to update the `counterpart_billing_address` object.
## Update invoice line items
You can modify an invoice's line items to add, remove, or update the products and product details on the invoice. To update an invoice's line items, send a `PUT` request to the [`/receivables/{receivable_id}/line-items`](/finops/reference/openapi/receivables/put-receivables-id-line-items) endpoint. In the request body, use the `data` field to specify an array of the invoice's new line items.
```sh expandable lines theme={null}
curl -X PUT 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3/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 '{
"data": [
{
"quantity": 2,
"product_id": "fb2cc78f-3396-42e1-a69f-04b1931e4a84",
"vat_rate_id": "8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
"discount": {
"type": "amount",
"amount": 0
}
},
{
"quantity": 4,
"product_id": "d1bc6df0-1571-457c-8407-7cf42aceb5dd",
"vat_rate_id":"8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
"discount": {
"type":"amount",
"amount":0
}
}
]
}'
```
A successful request overwrites the invoice's existing line items and replaces them with the newly defined array of line item objects.
## Preview an invoice's email
After creating an invoice, you can preview an invoice's email before issuing it. This step can be used when troubleshooting [email template](/finops/guides/advanced/email-templates/index) layouts for an invoice to ensure that the final presentation aligns with your template design.
To preview an invoice's template, send a `POST` request to the [`/receivables/{receivable_id}/preview`](/finops/reference/openapi/receivables/post-receivables-id-preview) endpoint. The `language` field determines the language of the email template used to preview the invoice. If a value is not provided, it defaults to `en`.
```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3/preview' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"subject_text": "New invoice #{invoice_number}",
"body_text": "Dear {contact_name},\n\nThank you for your business!\nPlease pay the balance of {amount_due} (invoice #{invoice_number}) by {due_date}.\n\nFor any questions or concerns, please don’t hesitate to get in touch with us at {entity_email}. We look forward to serving you again and wish you all the best!",
"language": "en"
}
```
The values of the `subject_text` and `body_text` fields will replace the `subject_text` and `body_template` variables if they were used when creating your custom templates. For more information, see [Create and manage email templates](/finops/guides/advanced/email-templates/manage) and [Variables list](/finops/guides/advanced/variables#list).
Only invoices in the `draft`, `issued`, `overdue`, and `partially_paid` statuses can be previewed.
Attempting to preview an invoice in any other status will return a `409 Conflict` error.
## Connect an invoice to a payment link
All created invoices have an assigned QR code. By default, all invoices' QR codes point to the [Tesouro homepage](https://tesouro.com/). Connecting a payment link to an invoice automatically assigns a payment page dedicated to the specific invoice and updates the invoice's QR code destination to point to that payment page.
The process of connecting payment links to an invoice varies slightly between using Tesouro's payment links or your custom payment links. However, the `payment_page_url` field on the invoice object determines the payment link embedded in the invoice PDF's QR code.
### Using Tesouro's payment links
Before using Tesouro's payment link, you must first create a payment link connected to the invoice. To connect a payment link to an invoice, send a `POST` request to the [`/payment-links`](/finops/reference/openapi/payment-links/post-payment-links) endpoint.
In the request body, include the `object.id` field representing the invoice ID. For more information about connecting a payment link to an invoice, see [Payment links](/finops/guides/payments/payment-links#create).
```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payment-links' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: 7884aa8a-34c7-4c78-87d2-4d1c6b8c6936' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"object": {
"type": "receivable",
"id": "411dc6eb-3bf4-465b-8dfe-f6b5ec6289b3"
},
"recipient": {
"type": "entity",
"id": "7884aa8a-34c7-4c78-87d2-4d1c6b8c6936"
},
"payment_methods": [
"card"
],
"return_url": "https://example.com/where-to-redirect-after-payment"
}'
```
A successful request generates and returns the payment link for the invoice in the `object.id` field. The payment link generated can be found on the `payment_page_url` field of the invoice object.
You can only generate payment links for invoices in the `issued` and `overdue` statuses.
Attempting to create a payment link for an invoice in any other status will throw an error.
### Using external payment links
If you use custom payment rails, you can connect an external payment link to an invoice. To do this, provide your custom invoice payment link in the `payment_page_url` field when creating or updating an invoice:
```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"invoice": {
"payment_page_url": "https://pay.example.com/497f374d-39b6-4506-bad1-689ed0fc5627"
}
}'
```
When using external payment links, the `payment_page_url` field can only be updated for invoices
in the `draft` status. Attempting to connect an external payment link after issuing an invoice
will throw an error.
## Record payments on an invoice
When using external payment rails, you must manually send all invoice payment information to Tesouro. This can be either one complete or multiple partial payments. To send information about a payment, call `POST /payment-records`:
```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payment-records' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"payment_intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"object": {
"id": "1877d46f-2f16-484d-a44a-b537b30c2f34",
"type": "receivable"
},
"paid_at": "2024-08-26T11:59:54.789Z",
"amount": 500,
"currency": "USD"
}'
```
A successful request contains details of the payment record created and includes details of the invoice's updated status. Tesouro automatically reconciles and transitions the invoice to the appropriate status. For more information, see [Create a payment record](/finops/guides/common/payment-records#create) and [Invoice reconciliation](/finops/guides/accounts-receivable/reconciliation).
**Notes**
* This endpoint can be used for invoices in the `issued`, `partially_paid`, and `overdue` [statuses](/finops/guides/accounts-receivable/invoices/index).
* The `amount` field must always be less than or equal to the current value of the invoice's `amount_due` field.
## Mark an invoice as paid
If the counterpart has paid an invoice in full, you can mark this invoice as paid by calling [`POST /receivables/{receivable_id}/mark-as-paid`](/finops/reference/openapi/receivables/post-receivables-id-mark-as-paid). Optionally, you can provide a JSON body containing the following fields:
* `paid_at` - Date and time of the payment. This value will be saved to the `paid_at` field of the invoice object. If omitted, it defaults to the date and time of the `/mark-as-paid` request.
* `comment` - Additional notes about the paid invoice. For example, which payment method was used. This comment will be saved to the `comment` field of the invoice object.
```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3/mark-as-paid' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"paid_at": "2024-08-26T00:00:00Z",
"comment": "Paid on 2024/08/26 by a wire transfer."
}'
```
**Notes**
* Only invoices in the `issued`, `overdue`, and `partially_paid` [statuses](/finops/guides/accounts-receivable/invoices/index) can be marked as fully paid.
* If the invoice is already `paid`, a call to `/receivables/{receivable_id}/mark-as-paid` has no effect on the invoice, and the specified `paid_at` and `comment` values are ignored.
Alternatively, you can use `POST /payment-records` to record a full payment for the invoice, as [shown above](#record-payment). The main differences from `/mark-as-paid` are that you need to provide the payment `amount` in the request and that a [payment record](/finops/guides/common/payment-records) will be created to reflect the payment. To get the amount due for use in the `/payment-records` request, you can use the `amount_to_pay` field of the invoice object.
## Customize invoice number
Invoice numbers are customized in the organization settings. Customizing an invoice number will affect all invoices subsequently issued by the organization. The `document_id` on previously issued invoices will not be affected by this change. To customize invoice numbering, make a `PATCH` request to the `/organizations/{organization_id}/settings` endpoint as shown:
```sh expandable lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/identity/v1/organizations/5b031d0c...44df31ebf0db/settings' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"document_ids": {
"include_date": true,
"min_digits": 3,
"document_type_prefix": {
"invoice": "INV",
},
"next_number": {
"invoice": "20",
}
}
}'
```
For more information on customizing invoice numbering, see [Document number customization](/finops/guides/advanced/document-number-customization).
## Mark an invoice as uncollectible
If an invoice is [overdue](/finops/guides/accounts-receivable/invoices/index#overdue) and the counterpart cannot pay it due to insolvency, you can write off this invoice as uncollectible. To do this, call [`POST /receivables/{receivable_id}/mark-as-uncollectible`](/finops/reference/openapi/receivables/post-receivables-id-mark-as-uncollectible). This will change the invoice `status` to "uncollectible".
Optionally, you can provide a JSON request body with the `comment` field containing an arbitrary comment. This comment will be saved to the `comment` field of the invoice object.
```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3/mark-as-uncollectible' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"comment": "An optional comment explaining why the invoice was deemed uncollectible."
}'
```
## Clone an invoice
You can clone an invoice of any status by sending a `POST` request to the [`/receivables/{receivable_id}/clone`](/finops/reference/openapi/receivables/post-receivables-id-clone) endpoint. Cloning an invoice copies the updated organization and counterpart information associated with the invoice.
```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3/clone' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
A successful request returns an object with the newly cloned invoice details.
All newly cloned invoices will have a `draft` status regardless of the status of the original
invoice they were cloned from. Therefore, all previously updated values related to issuing and
paying the original invoice will be reset.
## Delete an invoice
Draft invoices can be deleted by calling [`DELETE /receivables/{receivable_id}`](/finops/reference/openapi/receivables/delete-receivables-id). It's important to note that this action is irreversible, and once deleted, invoices can no longer be accessed.
```sh lines theme={null}
curl -X DELETE 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
Only invoices in the `draft` status can be deleted successfully. Attempting to delete an invoice
with any other status will fail.
## Cancel an invoice
Invoices in the `issued` and `overdue` [statuses](/finops/guides/accounts-receivable/invoices/index) can be canceled if they have not been paid in full yet. For example, an organization may want to cancel an invoice if it was issued by mistake or if some data in the invoice is missing or incorrect. Depending on the organization settings (mentioned below), canceling an invoice can automatically create and issue a [credit note](/finops/guides/accounts-receivable/credit-notes) for this invoice.
To cancel an invoice, call [`POST /receivables/{invoice_id}/cancel`](/finops/reference/openapi/receivables/post-receivables-id-cancel):
```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3/cancel' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
A successful request will return the 204 status code. Additionally, if the [organization setting](/finops/reference/openapi/identity/patch-organizations-id-settings) `receivable_edit_flow` is *"compliant"*, a new credit note is automatically created and issued for the remaining invoice amount. Note that credit notes are not automatically sent to counterparts, but the organization can [send the documents manually](/finops/reference/openapi/receivables/post-receivables-id-send).
To find the created credit note, you can call:
```sh lines theme={null}
GET /receivables?based_on={invoice_id}&limit=1&status=issued
```
**Notes**
* Canceled invoices cannot be reissued. If the reason for cancelling was to fix missing or incorrect data in the invoice, the organization will need to create a new invoice with the corrected data.
* An invoice cannot be canceled if a *draft* credit note exists for this invoice and the organization setting `receivable_edit_flow` is *"compliant"*.
* Another way to cancel an invoice is to manually create and issue a credit note for the remaining invoice amount. In this case, the invoice status is changed to "canceled" automatically.
## List all invoices
To get a list of all invoices generated by an organization, call [`GET /receivables?type=invoice`](/finops/reference/openapi/receivables/get-receivables):
```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/receivables?type=invoice' \
-H 'X-Finops-Version: 2025-06-23' \
-H 'X-Organization-Id: ORGANIZATION_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
You can [sort and filter](/finops/api/concepts/pagination-sorting-filtering#sorting) the results by the amount, counterpart name, and other fields. For the full list of available sort and filter parameters, see the description of the [`GET /receivables`](/finops/reference/openapi/receivables/get-receivables) endpoint.
Some examples:
* `GET /receivables?type=invoice&counterpart_name=Acme%20Inc.` - get all invoices issued to Acme Inc.
* `GET /receivables?type=invoice&amount__gte=15000` - get all invoices where the total amount is \$150 or more.
* `GET /receivables?type=invoice&status__in=draft&status__in=issued` - get all draft and issued invoices.
* `GET /receivables?type=invoice&created_at__gte=2024-01-01T00%3A00%3A00` - get all invoices created on or after January 1, 2024.
## Retrieve an invoice
To get information about a specific invoice, call [`GET /receivables/{receivable_id}`](/finops/reference/openapi/receivables/get-receivables-id) and provide the invoice ID.