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

# Payable history

> Learn how to review the history of changes made to a payable.

<Info>
  This guide covers the document history for accounts payable documents. Tesouro also provides
  [document history for accounts receivable](/finops/guides/accounts-receivable/document-history) documents.
</Info>

## Overview

The document history for payables provides visibility into key actions performed on these documents. Each event includes the timestamp, the type of action, and the user (or system) that performed it.

This helps teams and auditors understand when documents were created, updated, or linked — and by whom.

## Roles and permissions

To access a payables's change history using an [organization user token](/finops/guides/organizations/users#get-organization-user-token),
this user must have a role with the `payables.read` [permission](/finops/api/concepts/permissions).
If the permission type is `allowed_for_own` (rather than `allowed`), the user can access the change history only for documents that they themselves created, but the returned history still includes the changes made to their documents by other users.

If a [partner-level token](/finops/guides/authentication/client-credentials) is used, no special permissions are needed.

## Event types

Payable history includes the following event types:

| Event Name             | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `payable_created`      | When a payable is created.                                                            |
| `payable_updated`      | When any fields of the payable are updated.                                           |
| `status_changed`       | When the payable's status changes at any stage throughout the full payable lifecycle. |
| `credit_note_linked`   | When a credit note is linked to the payable.                                          |
| `credit_note_unlinked` | When a credit note is unlinked from the payable.                                      |
| `file_attached`        | When a file is attached to the payable.                                               |

To access a document’s history, call [`GET /payables/{payable_id}/history`](/finops/reference/openapi/payables/get-payables-id-history). You can filter the history by a date range or the `event_type`.

The history consists of a list of timestamped events that have occurred since the document was created. For a description of available data fields and query parameters, see the [endpoint description](/finops/reference/openapi/payables/get-payables-id-history).

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/payables/{payable_id}/history?event_type__in=status_changed' \
  -H 'X-Finops-Version: 2025-06-23' \
  -H 'X-Organization-Id: ORGANIZATION_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

The successful `200` response returns the history of the payable:

```json expandable lines theme={null}
{
  "data": [
    {
      "id": "cd58435b-1c79-4b17-9f79-f898c93e5f97",
      "entity_user_id": "d5a577b0-01c0-4566-ac5c-44f41935e8c4",
      "event_data": {
        "new_status": "draft",
        "old_status": "approve_in_progress"
      },
      "event_type": "status_changed",
      "payable_id": "f669a8a4-0563-4ab9-b54f-e9d700d282c5",
      "timestamp": "2025-05-28T13:27:23.572Z"
    }
  ],
  "next_pagination_token": null,
  "prev_pagination_token": null
}
```

<Info>
  Some events are triggered automatically by the system and occur in the background. In these cases,
  the `entity_user_id` field will be empty, as no specific user initiated the action.
</Info>