> ## 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 payables > Learn how to manage your payables. ## Change payable status You can manually change the status of the payables and move them through the [lifecycle](/finops/guides/accounts-payable/payables/index) until their payment. See [Manual transition](/finops/guides/accounts-payable/approvals/manual-transition) for more information. Alternatively, we recommend that you implement [approval policies](/finops/guides/accounts-payable/approvals/policies/index) to manage the payables transitions. ## Get payables analytics You can obtain aggregated statistics for the total number and sum total amount of all existing payables, along with the breakdown per payable status. To do this, send a `GET` request to the [`/payables/analytics`](/finops/reference/openapi/analytics/get-analytics-payables) endpoint. The results can be filtered by a specific time period, counterpart, or other search filters. For the full list of available sort and filter parameters, see the [`GET /payables/analytics`](/finops/reference/openapi/analytics/get-analytics-payables) endpoint. For example, to get statistics about all payables in the `approve_in_progress` and `waiting_to_be_paid` statuses, call `GET /payables/analytics?status__in=approve_in_progress&status__in=waiting_to_be_paid`: ```sh lines theme={null} curl -X GET 'https://api.sandbox.tesouro.com/v1/payables/analytics?status__in=approve_in_progress&status__in=waiting_to_be_paid&id__in=' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` The successful response contains the total number and sum total amount of all existing payables: ```json expandable lines theme={null} { "count": 35, "data": [ { "count": 22, "status": "approve_in_progress", "sum_total_amount": 12566 }, { "count": 13, "status": "waiting_to_be_paid", "sum_total_amount": 22688 } ], "sum_total_amount": 35254 } ``` Some other examples of statistics: * `GET /payables/analytics?created_at__gte=2023-10-01T14%3A48%3A00Z&created_at__lte=2023-10-31T14%3A48%3A00Z` - Get statistics about all payables for a specific period. * `GET /payables/analytics?counterpart_name=Acme%20Inc.` - Get statistics about all payables for a specific counterpart. \*/ ## List all payables It is possible to view all the payables in the Tesouro space. To allow the right level of access to the authorized users, Tesouro allows certain organization users to view them but not change uploads. To list all payables, call [`GET /payables`](/finops/reference/openapi/payables/get-payables). You [can sort and filter](/finops/api/concepts/pagination-sorting-filtering) the results by the amount, status, and other fields. For the full list of available sort and filter parameters, see the [`GET /payables`](/finops/reference/openapi/payables/get-payables) endpoint. Some examples: | Endpoint | Description | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `GET /payables?search_text=Acme%20Inc.` | Applies the `icontains` condition to search for the text “Acme Inc.” in the `document_id` and `counterpart_name` fields in the payables. | | `GET /payables?counterpart_name=Acme%20Inc.` | Get all payables issued to Acme Inc. | | `GET /payables?amount__gte=15000` | Get all payables where the total amount is \$150 or more. | | `GET /payables?status__in=draft&status__in=new` | Get all draft and new payables. | | `GET /payables?created_at__gte=2022-01-01T00%3A00%3A00` | Get all payables created on or after January 1, 2022. | | `GET /payables?ocr_status=error` | Get all payables that have failed to be recognized by the OCR. | | `GET /payables?tag_ids=df715ea3-e8a9-44d0-845c-2beceeb5589e` | Get all payables containing a specific tag. | | `GET /payables?has_file=false` | Get all payables with no files attached. | | `GET /payables?has_tags=false` | Get all payables with no tags associated. | Sample request to fetch 100 payables: ```sh lines theme={null} curl -X GET 'https://api.sandbox.tesouro.com/v1/payables?order=asc&limit=100' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` The successful response returns a paged series of all payables that the organization has access to. For example: ```json expandable lines theme={null} { "data": [ { "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0", "entity_id": "b0ff50d0-cdea-42fd-9461-1b3799b65bcf", "marked_as_paid_with_comment": null, "marked_as_paid_by_entity_user_id": null, "status": "new", "source_of_payable_data": "ocr", "currency": "USD", "total_amount": 9900, "description": null, "due_date": "2022-06-30", "partner_metadata": {}, ..., } ], "prev_pagination_token": null, "next_pagination_token": "bGltaXQ9MiZmaXJzdF9vaWQ9MSZuZXh0X3Rva2VuPTQ=" } ``` The `prev_pagination_token` and `next_pagination_token` fields in the response are [pagination tokens](/finops/api/concepts/pagination-sorting-filtering#pagination). ## Retrieve a payable Once a payable is uploaded, the organization and organization users can review the information extracted from the payable by the OCR system. To retrieve a payable, call `GET /payables/{payable_id}`: ```sh lines theme={null} curl -X GET 'https://api.sandbox.tesouro.com/v1/payables/{payable_id}' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` The successful response contains the payable attributes: ```json expandable lines theme={null} { "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0", "entity_id": "b0ff50d0-cdea-42fd-9461-1b3799b65bcf", "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", "total_amount": 9900, "source_of_payable_data": "ocr", "currency": "USD", "description": null, "due_date": "2023-07-15", "partner_metadata": {}, "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_id": "DEUTDE2HXXX", "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_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": "6ba5a3b8-82c6-4aaa-b010-03bc4128b342", "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": "2021-11-25T05:10:35.211432+00:00", "file_type": "payables", "name": "file name", "region": "eu-central-1", "md5": "623470039566983ed5e5945f769ea873", "mimetype": "image/png", "url": "https://tesouro-payables.com/2d14935e.../669bab57c57f.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": "2021-11-25T05:10:35.211432+00:00", "updated_at": "2021-11-25T05:10:35.211447+00:00", "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, "sender": "hello@example.com" } ``` ## Update a payable Payables in the `draft` and `new` statuses can be updated, for example, to provide additional details or fix the information extracted by OCR. To update a payable, send a `PATCH` request to the `/payables/{payable_id}` endpoint with the request body containing the new field values. For example, to update the `description` field: ```sh lines theme={null} curl -X PATCH 'https://api.sandbox.tesouro.com/v1/payables/{payable_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 '{ "description": "New description of the payable" }' ``` ## Delete a payable Payables in any status can be deleted by calling the [`DELETE /payables/{payable_id}`](/finops/reference/openapi/payables/delete-payables-id) endpoint: ```sh lines theme={null} curl -X DELETE 'https://api.sandbox.tesouro.com/v1/payables/{payable_id}' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` This action is irreversible, and once deleted, payables can no longer be accessed.