Manage payables

Change payable status

You can manually change the status of the payables and move them through the lifecycle until their payment. See Manual transition for more information. Alternatively, we recommend that you implement approval policies 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 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 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:

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:

{
  "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. You can sort and filter the results by the amount, status, and other fields. For the full list of available sort and filter parameters, see the 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:

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:

{
  "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.

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}:

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:

{
  "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:

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} endpoint:

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.

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Manage payables

Change payable status

Get payables analytics

List all payables

Retrieve a payable

Update a payable

Delete a payable

​Change payable status

​Get payables analytics

​List all payables

​Retrieve a payable

​Update a payable

​Delete a payable

Change payable status

Get payables analytics

List all payables

Retrieve a payable

Update a payable

Delete a payable