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

# Collect payables

> Learn how to collect an incoming invoice to start the payable flow.

## Overview

There are several ways to collect [payables](/finops/support/glossary#payable) into Tesouro:

* [Create a payable via API](#create-a-payable-from-data) by providing the amount, currency, and other details.
* [Upload an invoice](#upload-files-via-api) in PDF, PNG, or JPEG formats via API.
* [Send an invoice in PDF, PNG, or JPEG formats by email](#send-payables-by-email) to the [organization](/finops/support/glossary#organization)'s mailbox.

When a payable is created from a PDF, PNG, or JPEG file, Tesouro's [OCR](/finops/support/glossary#ocr) service automatically extracts the invoice information from the file and a new payable is created with the extracted data fields accordingly. The `file` property of the payable contains the file metadata and the link to access the original source file.

## About Tesouro OCR

Tesouro OCR uses top-notch Optical Character Recognition ([OCR](/finops/support/glossary#ocr)) algorithms to pull text from payables.

* The OCR process is asynchronous and the processing time may vary according to the document size. The [webhook](/finops/guides/getting-started/webhooks/index) `ocr_finished` is triggered once the OCR has finished processing the file and storing the extracted data into a payable.
* The field `payable.ocr_status` reflects the current status of the OCR process of a payable. Its possible values are `processing`, `error`, and `success`.
* The minimum image file size is 100 KB.
* The maximum image file size is 20 MB.
* The maximum email size is 25 MB (including all attachments).
* Files with dimensions smaller than 400x400 px are not considered payables, thus, they are not processed.
* PDF files must have at least one page with dimensions bigger than 400x400 px to be considered a payable, otherwise, they are not processed.
* Multipage PDF files can have up to 100 pages.
* Tesouro's OCR service is not executed if the format of the uploaded document is not supported or the number of pages exceeds 10. Therefore, no invoice information is stored. In this case, only the information about the file is stored.
* You can configure the system to [avoid the creation of duplicated payables](#cancel-duplicated-payables-automatically) based on the information obtained by the OCR.

<Accordion title="Covered languages">
  While this is not an exhaustive list, Tesouro OCR guarantees tested coverage for the following languages:

  * Arabic
  * Bulgarian
  * Catalan
  * Chinese
  * Czech
  * Danish
  * Dutch
  * English
  * Estonian
  * Finnish
  * French
  * Georgian
  * German
  * Greek
  * Hebrew
  * Hungarian
  * Italian
  * Japanese
  * Latvian
  * Lithuanian
  * Norwegian
  * Polish
  * Portuguese
  * Romanian
  * Russian
  * Serbian
  * Slovak
  * Slovenian
  * Spanish
  * Swedish
  * Thai
  * Turkish
  * Ukrainian
</Accordion>

## Create a payable from data

If you already have the invoice data (amount in [minor units](/finops/support/currencies#minor-units), currency, vendor information, and other details) stored somewhere as individual attributes, you can create a payable with these attributes by calling `POST /payables`.

You can provide the [base64-encoded](https://en.wikipedia.org/wiki/Base64) contents of the original invoice file in the field `base64_encoded_file`:

```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payables' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -d '{
       "partner_metadata": {},
       "currency": "USD",
       "description": "Restock office supplies",
       "due_date": "2023-07-15",
       "payment_terms": {
         "name": "2/10, 1/20, net 30",
         "term_1": {
           "number_of_days": 10,
           "discount": 200
         },
         "term_2": {
           "number_of_days": 20,
           "discount": 100
         },
         "term_final": {
           "number_of_days": 30
         }
       },
       "suggested_payment_term": {
         "date": "2023-07-25",
         "discount": 200
       },
       "issued_at": "2023-06-15",
       "counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
       "counterpart_bank_account_id": "ee415e8a-4368-4ef8-b192-d25b8e86ad0f",
       "counterpart_address_id": "d0f2899d-e2b1-4b95-8411-2ed1a9063bce",
       "counterpart_vat_id_id": "c0d3ca66-bdfa-4cdb-aceb-633d4dfe4f11",
       "base64_encoded_file": "... Base64-encoded contents of the invoice file ...",
       "file_name": "invoice.pdf",
       "tag_ids": [
         "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
       ],
       "enforced_approval_policy_id": null,
       "document_id": "DE2287",
       "sender": "hello@example.com"
     }'
```

Notes:

* The `file_name` field is optional. If omitted, it defaults to `"default_file_name"`.
* If the settings are [configured](#suggested-payment-date) to automatically set `suggested_payment_term`, this object can be omitted from the request body.
* The fields `subtotal` and `total_amount` of the payable are automatically calculated based on the values of the [line items](/finops/guides/accounts-payable/payables/line-items), therefore, they are read-only and appear only in the response schema. This feature can be disabled in the [partner](/finops/support/glossary#partner)'s settings by calling `PATCH /settings` passing the field `enable_line_items` as `false` (the default value is `true`). Once `enable_line_items` is disabled, the fields `amount`, `subtotal`, `tax`, and `tax_amount` of the `payable` object become editable during its creation and update, as they will no longer be calculated/re-calculated based on line items.
* You can manually enforce which approval policy should be applied to the payable by setting the optional field `enforce_approval_policy_id`. When set, this policy will be applied when the payable is submitted for approval, regardless of trigger conditions.

The successful response returns the `id` assigned to this payable, along with the information passed in the request. You can use this `id` in other API calls to update the data of this payable or trigger [status transitions](/finops/guides/accounts-payable/approvals/manual-transition):

```json expandable lines theme={null}
{
  "partner_metadata": {},
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
  "marked_as_paid_with_comment": null,
  "marked_as_paid_by_entity_user_id": null,
  "amount_due": 9900,
  "amount_paid": 0,
  "amount_to_pay": 9900,
  "status": "new",
  "source_of_payable_data": "user_specified",
  "currency": "USD",
  "total_amount": 0,
  "total_amount_with_credit_notes": 0,
  "description": "Restock office supplies",
  "due_date": "2023-07-15",
  "payment_terms": {
    "name": "2/10, 1/20, net 30",
    "term_1": {
      "number_of_days": 10,
      "discount": 200
    },
    "term_2": {
      "number_of_days": 20,
      "discount": 100
    },
    "term_final": {
      "number_of_days": 30
    }
  },
  "suggested_payment_term": {
    "date": "2023-07-25",
    "discount": 200
  },
  "issued_at": "2022-06-15",
  "counterpart_id": "8737964a-5246-47f4-8243-8728a2be1e75",
  "counterpart_bank_account_id": "ee415e8a-4368-4ef8-b192-d25b8e86ad0f",
  "counterpart_address_id": "d0f2899d-e2b1-4b95-8411-2ed1a9063bce",
  "counterpart_vat_id_id": "c0d3ca66-bdfa-4cdb-aceb-633d4dfe4f11",
  "counterpart_bank_id": null,
  "counterpart_account_id": null,
  "counterpart_name": "Acme Inc.",
  "counterpart_address": {
    "country": "US",
    "city": "Austin",
    "postal_code": "78701",
    "state": "TX",
    "line1": "123 Congress Ave",
    "line2": "Suite 100"
  },
  "payable_origin": "upload",
  "created_by_role_id": "6ba5a3b8-82c6-4aaa-b010-03bc4128b342",
  "credit_notes": [...]
  "was_created_by_user_id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
  "currency_exchange": {
    "default_currency_code": "USD",
    "rate": 10.0,
    "total": 0
  },
  "file": {
    "id": "2d14935e-505b-4863-a082-b6a340acabbc",
    "created_at": "2022-04-05T06:31:31.431Z",
    "file_type": "payables",
    "name": "file name",
    "region": "eu-central-1",
    "md5": "623470039566983ed5e5945f769ea873",
    "mimetype": "application/pdf",
    "url": "https://tesouro-file-saver-payables-eu-central-1-dev.s3.amazonaws.com/2d14935e.../669bab57c57f.pdf",
    "size": 49463,
    "previews": [],
    "pages": []
  },
  "tags": [
    {
      "name": "Marketing",
      "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
      "created_at": "2022-09-07T16:35:18.484507+00:00",
      "updated_at": "2022-09-07T16:35:18.484507+00:00",
      "created_by_entity_user_id": "efe7eedd-89c5-56f5-984c-0712ee41a2eb"
    }
  ],
  "created_at": "2022-06-17T06:31:31.431Z",
  "updated_at": "2022-06-17T06:31:31.431Z",
  "approval_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "enforced_approval_policy_id": null,
  "document_id": "DE2287",
  "subtotal": 0,
  "tax": null,
  "tax_amount": null,
  "sender": "hello@example.com"
}
```

### Automatic calculation of due date

If the values of the fields `payment_terms.final_term` and `issued_at` are provided in the payable, the `due_date` will be automatically calculated based on `issued_at` plus the number of days defined by `payment_terms.final_term.number_of_days`.

For example, if `issued_at` equals to `2023-06-15` and `payment_terms.term_final.number_of_days` equals to 10, the `due_date` will be automatically set to `2023-06-25`.

In any other case, the `due_date` supplied by the user is stored in the payable. The `payment_terms` and `issued_at` fields have priority in the calculation of the `due_date`, even if the`due_date` is supplied by the user.

The automatic calculation of the `due_date` happens when the payable is parsed by the OCR, created with data, or updated.

### Suggested payment date

Once the payable is created, Tesouro automatically fills the payable's field `suggested_payment_term` with a suggestion for the payment date and corresponding discount, if available, based on its [payment terms](/finops/guides/common/payment-terms) (represented by the field `payment_terms`). When the payable's `issued_at` or `payment_terms` fields are updated, the value for the `suggested_payment_term` is recalculated.

It is possible to choose the payment term (`term_1`, `term_2`, or `term_final`) to be suggested as default by setting the field `payment_priority` in the organization's settings to one of these values:

* `working_capital`: Selects the term with the latest possible payment target.

* `bottom_line`: Selects the term with the highest discount.

* `balanced`: Selects the intermediate term, that is, a balance between duration and drawn discount.

The `suggested_payment_term` will be calculated based on the field `issued_at` added by the `term_X.number_of_days`. Note that this suggestion does not affect the invoice's due date, which remains the same.

#### Change the payment priority

To update the `payment_priority` of in the organization's settings, call `PATCH /organizations/{organization_id}/settings`, passing the new `payment_priority` in the body:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/identity/v1/organizations/{organization_id}/settings' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -d '{
       "payment_priority": "working_capital"
     }'
```

### Automatic recalculation with credit notes

When a related [credit note](/finops/guides/accounts-payable/credit-notes/index) transitions from the status `approve_in_progress` to `approved`, the associated payable undergoes automatic recalculation. This ensures that the payable reflects the updated amounts and maintains consistency across related records.

The `amount_with_credit_notes` of the payable is recalculated using the `total_amount` of the credit note. After the recalculation is complete, the status of the related credit note is updated to `applied`.

### Attach file

You can attach an invoice file to an existing payable, in any status, by calling `POST /payables/{payable_id}/attach-file`:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payables/{payable_id}/attach-file' \
     -H 'accept: application/json' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: multipart/form-data' \
     -F 'file=@payable.png;type=image/png'
```

The provided file is then returned in the file field on the `payable` object.

```json expandable lines theme={null}
{
  "partner_metadata": {},
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "marked_as_paid_with_comment": null,
  "marked_as_paid_by_entity_user_id": null,
  "amount_due": 9900,
  "amount_paid": 0,
  "amount_to_pay": 9900,
  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
  "status": "new",
  "source_of_payable_data": "user_specified",
  "currency": "USD",
  "total_amount": 0,
  "description": "Restock office supplies",
  "due_date": "2022-07-15",
  "payable_origin": "upload",
  "file": {
    "id": "2d14935e-505b-4863-a082-b6a340acabbc",
    "created_at": "2022-04-05T06:31:31.431Z",
    "file_type": "payables",
    "name": "payable",
    "region": "eu-central-1",
    "md5": "623470039566983ed5e5945f769ea873",
    "mimetype": "image/png",
    "url": "https://tesouro-file-saver-payables-eu-central-1-dev.s3.amazonaws.com/2d14935e.../payable.png",
    "size": 49463,
    "previews": [],
    "pages": []
  },
  "tags": [
    {
      "name": "Marketing",
      "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
      "created_at": "2022-09-07T16:35:18.484507+00:00",
      "updated_at": "2022-09-07T16:35:18.484507+00:00",
      "created_by_entity_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
    }
  ],
  "created_at": "2023-11-21T15:32:36.695Z",
  "updated_at": "2023-11-21T15:32:36.695Z",
  ...
}
```

Notes:

* The uploaded file is stored only for reference purposes.
* The file is not processed by the OCR or validated, therefore, the users need to ensure that the information in the file is correct.
* If the payable already has a file attached, an error is returned when trying to attach another one.

### Cancel duplicated payables automatically

You can configure the system to avoid the creation of duplicated payable based on the information obtained by the OCR.

To enable this feature, send a `PATCH` request to the `/settings` endpoint, setting the `payable.allow_cancel_duplicates_automatically` field to `true`:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/settings' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -d '{
        "payable": {
          "allow_cancel_duplicates_automatically": true
        }
      }'
```

This way, once the counterpart is successfully [auto-linked](/finops/guides/common/counterparts/index#auto-linking) and the OCR identifies the invoice number inside the payable, the system verifies if there is any invoice with an identical counterpart ID (`counterpart_id` field) and invoice number (`document_id` field) for the given [organization](/finops/support/glossary#organization). If a payable with this information is found, i.e. the payable already exists, the system automatically sends the newly created payable to the `canceled` [status](/finops/guides/accounts-payable/approvals/manual-transition#cancel-a-payable).

<Info>
  To ensure the automatic cancellation of duplicated payables, it is imperative to have the
  [auto-linking feature](/finops/guides/common/counterparts/index#auto-linking) enabled.
</Info>

## Upload files via API

You can upload invoices in the PDF, PNG, or JPG format to Tesouro by calling `POST /payables/upload-from-file`. The maximum file size is 20 MB:

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payables/upload-from-file' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: multipart/form-data' \
     -F 'file=@pdf-invoice.pdf;type=application/pdf'
```

In return, you receive back the `201 Created` response with `id` and other parameters:

```json expandable lines theme={null}
{
  "partner_metadata": {},
  "id": "61257ac9-ef71-4977-9e40-c9e027c7d539",
  "entity_id": "9d2b4c8f-2087-4738-ba91-7359683c49a4",
  "marked_as_paid_with_comment": null,
  "marked_as_paid_by_entity_user_id": null,
  "amount_due": 9900,
  "amount_paid": 0,
  "amount_to_pay": 9900,
  "status": "draft",
  "source_of_payable_data": "ocr",
  "currency": "USD",
  "total_amount": 0,
  "total_amount_with_credit_notes": 0,
  "description": null,
  "due_date": null,
  "payment_terms": null,
  "suggested_payment_term": null,
  "issued_at": null,
  "counterpart_bank_account_id": "ee415e8a-4368-4ef8-b192-d25b8e86ad0f",
  "counterpart_address_id": "d0f2899d-e2b1-4b95-8411-2ed1a9063bce",
  "counterpart_vat_id_id": "c0d3ca66-bdfa-4cdb-aceb-633d4dfe4f11",
  "counterpart_bank_id": null,
  "counterpart_id": null,
  "counterpart_account_id": null,
  "counterpart_name": null,
  "counterpart_tax_id": null,
  "counterpart_address": null,
  "payable_origin": "upload",
  "created_by_role_id": null,
  "credit_notes": [...],
  "was_created_by_user_id": null,
  "currency_exchange": null,
  "file": {
    "id": "eac016c4-e06e-4cea-8ebf-3ec72dc8b49d",
    "created_at": "2023-03-20T18:24:24.808836+00:00",
    "file_type": "payables",
    "name": "8d545f97-bcb3-4dfc-8ccf-1aa62d887781",
    "region": "eu-central-1",
    "md5": "89746feb534f35364e6760e2d834fe19",
    "mimetype": "application/pdf",
    "url": "https://tesouro-file-saver-payables-eu-central-1-dev.s3.amazonaws.com/2d14935e.../669bab57c57f.pdf",
    "size": 18095,
    "previews": [],
    "pages": []
  },
  "tags": null,
  "created_at": "2023-03-22T08:09:06.650657+00:00",
  "updated_at": "2023-03-22T08:09:06.650669+00:00",
  "approval_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "document_id": null,
  "subtotal": 0,
  "tax": null,
  "tax_amount": null,
  "sender": null,
  "ocr_request_id": "d31562e6-8e7d-4dbd-ba53-a8a62b6c2a62",
  "ocr_status": "success"
}
```

You will also receive a [webhook](/finops/guides/getting-started/webhooks/index) indicating that this payable resource has been created:

```json lines theme={null}
{
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "created_at": "2024-03-04T20:06:48.593225+00:00",
  "action": "payable.created_from_file_upload",
  "api_version": "2025-06-23",
  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
  "description": "Action has been performed on the invoice: created_from_file_upload.",
  "object": {
    "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0"
  },
  "object_type": "payable",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}
```

Note that at this stage the payable resource is incomplete and waiting for the results of the OCR service, which automatically scans the details from the uploaded invoice and maps the information from the invoice to the corresponding data field in the system.

When the OCR scanning is finished (this might take up to 5-7 minutes), you will receive the `payable.ocr_finished` webhook event:

```json lines theme={null}
{
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "created_at": "2024-03-04T20:09:32.593225+00:00",
  "action": "payable.ocr_finished",
  "api_version": "2025-06-23",
  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
  "description": "Action has been performed on the invoice: ocr_finished.",
  "object": {
    "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0"
  },
  "object_type": "payable",
  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
}
```

Now, you can call `GET /payables/{payable_id}` to retrieve the results of the OCR scanning:

```json expandable lines theme={null}
{
  "partner_metadata": {},
  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
  "marked_as_paid_with_comment": null,
  "marked_as_paid_by_entity_user_id": null,
  "amount_due": 9900,
  "amount_paid": 0,
  "amount_to_pay": 9900,
  "status": "new",
  "source_of_payable_data": "ocr",
  "currency": "USD",
  "total_amount": 9900,
  "total_amount_with_credit_notes": 9900,
  "description": "",
  "due_date": "2023-07-15",
  "payment_terms": {
    "name": "2/10, 1/20, net 30",
    "term_1": {
      "number_of_days": 10,
      "discount": 200
    },
    "term_2": {
      "number_of_days": 20,
      "discount": 100
    },
    "term_final": {
      "number_of_days": 30
    }
  },
  "suggested_payment_term": {
    "date": "2023-07-25",
    "discount": 200
  },
  "issued_at": "2023-06-15",
  "counterpart_bank_account_id": "ee415e8a-4368-4ef8-b192-d25b8e86ad0f",
  "counterpart_address_id": "d0f2899d-e2b1-4b95-8411-2ed1a9063bce",
  "counterpart_vat_id_id": "c0d3ca66-bdfa-4cdb-aceb-633d4dfe4f11",
  "counterpart_bank_id": "ACMEUSAAXXX",
  "counterpart_id": "8737964a-5246-47f4-8243-8728a2be1e75",
  "counterpart_account_id": "123456789012",
  "counterpart_name": "Acme Inc.",
  "counterpart_address": {
    "country": "US",
    "city": "Austin",
    "postal_code": "78701",
    "state": "TX",
    "line1": "123 Congress Ave",
    "line2": "Suite 100"
  },
  "payable_origin": "upload",
  "created_by_role_id": null,
  "credit_notes": [...],
  "was_created_by_user_id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
  "currency_exchange": null,
  "file": {
    "id": "2d14935e-505b-4863-a082-b6a340acabbc",
    "created_at": "2022-04-05T06:31:31.431Z",
    "file_type": "payables",
    "name": "invoice-example.pdf",
    "region": "eu-central-1",
    "md5": "623470039566983ed5e5945f769ea873",
    "mimetype": "application/pdf",
    "url": "https://tesouro-file-saver-payables-eu-central-1-dev.s3.amazonaws.com/2d14935e.../669bab57c57f.pdf",
    "size": 49463,
    "previews": [],
    "pages": [
      {
        "id": "ad712600-bab8-4e0d-9da7-5d561484f1b1",
        "mimetype": "image/png",
        "size": 219712,
        "number": 0,
        "url": "https://tesouro-payables.com/1a95c387.../ac02c56d2a3d.png"
      }
    ]
  },
  "tags": [],
  "created_at": "2022-04-05T06:31:31.431Z",
  "updated_at": "2022-04-05T06:31:31.431Z",
  "ocr_request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ocr_status": "success",
  "approval_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "document_id": "DE2287",
  "subtotal": 9000,
  "tax": 1000,
  "tax_amount": 250,
  "sender": "hello@example.com"
}
```

## Send payables by email

Each organization has a [dedicated mailbox](/finops/guides/advanced/mailboxes) in Tesouro to which the payables can be sent. The organization or organization user can send invoices as attachments in PDF, PNG, or JPEG format to this mailbox (the maximum file size is 20 MB).

The optical character recognition (OCR) service scans the information inside each email's attachments. Then, Tesouro automatically creates a [draft payable](/finops/guides/accounts-payable/payables/index#statuses) invoice for each occurrence found. The email of the sender of these files is saved in the field `sender` of the invoice.

To find the mailbox assigned to a specific organization, call `GET /v1/mailboxes`:

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

The successful response contains information about the mailbox:

```json lines theme={null}
[
  {
    "id": "e8c884f8-bed3-4d92-afc9-3538c5079014",
    "entity_id": "68fdd6b5-b60c-4f4d-8642-1cd7f2fa31e8",
    "status": "active",
    "related_object_type": "payable",
    "mailbox_name": "1102737648192968373_payables",
    "mailbox_full_address": "1102737648192968373_payables@mg.sandbox.tesouro.com",
    "belongs_to_mailbox_domain_id": null
  }
]
```

<Info>
  By default, the automatically created mailboxes belong to the Tesouro domain (the web address that
  comes after `@` in an email address), but the [partners ](/finops/support/glossary#partner) can
  [set up their own email domain](/finops/guides/advanced/mailboxes) for better convenience.
</Info>

## Uploading already paid payables

Uploaded payables that are already paid can be automatically recognized as such for automatic payment approval. Once the payable is recognized as paid, its status will be changed to `paid` or `partially paid` according to the this rule:

* If the value of the `amount_paid` is greater or equal to the `amount_to_pay`, the payable status is automatically changed to the `paid` status.
* If the value of the `amount_paid` is greater than `0` and the value of the `amount_paid` is greater or equals to the `amount_to_pay`, the payable status is automatically changed to the `partially_paid` status.

To enable this behavior, set the field `skip_approval_for_paid_invoice` to `true` in the [partner settings](/finops/reference/openapi/partner-settings/patch-settings):

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/settings' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -d '{
        "payable": {
          "skip_approval_for_paid_invoice": true
        }
      }'
```

The `skip_approval_for_paid_invoice` default value is `false`.

## Automatic matching of purchase orders with payables

Every time a payable is created or updated, Tesouro automatically tries to link this payable to its corresponding purchase order, which is already created in the system. The conditions for the purchase order autolinking to be performed are:

* The counterpart name on the payable must match, [with a certain tolerance](#tolerance-match), the counterpart name on the purchase order.
* The line items\` name and price on the payable must match those on the purchase order.
* The total amount of the payable or unit price for the line items on the payable must match those on the purchase order.

Once the corresponding purchase order is found, its ID is added to the `payable.purchase_order_id` field. If more than one applicable purchase order is found, the most recently created is selected.

The automatic matching is **enabled** by default. To disable this behavior, call `PATCH /organizations/{organization_id}/settings`, passing the field `allow_purchase_order_autolinking` as `false` in the body.

The payable can also be manually matched by calling `PATCH /payables/{payable_id}`, passing the `purchase_order_id` in the body.

### Tolerance match

The matching is performed considering these tolerance rules:

* Minor variations in the counterparts\` names are accepted (e.g., "Ltd" vs. "Limited").
* The billed quantity may vary slightly within a small allowable range.
* The total amount of the payable or the unit price on the payable may exceed the agreed-upon price by 5%.

Payables that do not meet the exact or tolerance match criteria require a manual review. This process includes:

* Checking for typos or data entry errors.
* Verifying explanations for discrepancies (e.g., price changes, shipping fees).