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

# Document history

> Learn how to review the history of changes made to an invoice, quote, or credit note.

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

## Overview

Tesouro keeps a history of changes made to all [accounts receivable](/finops/guides/accounts-receivable/index) documents - [invoices](/finops/guides/accounts-receivable/invoices/index), [quotes](/finops/guides/accounts-receivable/quotes/index), and [credit notes](/finops/guides/accounts-receivable/credit-notes) - from document creation to the final status. This provides organizations with an overview of how a document has evolved over time.

The change history includes:

* all revisions made to the document,
* who made the change and when,
* status transitions,
* emails sent to the clients and the email addresses of the recipients,
* [payments](/finops/guides/payments/index) made towards an invoice.

<Info>Change history data is available only for changes made since September 30, 2024.</Info>

To access a document's history, call [`GET /receivables/{receivable_id}/history`](/finops/reference/openapi/receivables/get-receivables-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. The `event_data` structure varies based on the `event_type`. For a description of available data fields and query parameters, see the [endpoint description](/finops/reference/openapi/receivables/get-receivables-id-history).

```json expandable lines theme={null}
{
  "data": [
    {
      "id": "59c70641-213c-41fc-9105-5be84f8cfbbc",
      "current_pdf_url": "https://tesouro-file-saver.example.com/12345/67890.pdf",
      "entity_user_id": "9598d748-a5aa-4c60-b490-391b610beaef",
      "event_data": {
        "new_status": "issued",
        "old_status": "draft"
      },
      "event_type": "status_changed",
      "receivable_id": "628e6cc7-c44f-4c26-a7f1-a4b34dcfa429",
      "timestamp": "2024-09-20T15:58:48.674227+00:00"
    },
    ...
  ]
}
```

## Roles and permissions

To access a receivable's change history using an [organization user token](/finops/guides/organizations/users#get-organization-user-token),
this user must have a role with the `receivables.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

Document history includes the following event types:

| Event type                                                    | Invoices | Quotes | Credit notes |
| ------------------------------------------------------------- | -------- | ------ | ------------ |
| [`based_on_receivable_created`](#based_on_receivable_created) | ✔        | ✔      |              |
| [`mail_sent`](#mail_sent)                                     | ✔        | ✔      | ✔            |
| [`overdue_reminder_mail_sent`](#overdue_reminder_mail_sent)   | ✔        |        |              |
| [`payment_received`](#payment_received)                       | ✔        |        |              |
| [`payment_reminder_mail_sent`](#payment_reminder_mail_sent)   | ✔        |        |              |
| [`receivable_created`](#receivable_created)                   | ✔        | ✔      | ✔            |
| [`receivable_updated`](#receivable_updated)                   | ✔        | ✔      | ✔            |
| [`status_changed`](#status_changed)                           | ✔        | ✔      | ✔            |

### `based_on_receivable_created`

*Applies to: invoices, quotes*

In invoice history, this event means that a credit note was created for this invoice.

In quote history, this event means that an invoice was created from this quote.

The `event_data` object contains the type and ID of the newly created document. In the following example, a credit note with ID `0d51…` was created for an invoice with ID `628e…`:

```json lines theme={null}
{
  ...
  "event_data": {
    "receivable_id": "0d51871f-4241-47e6-95b7-0bba0fec45e7",
    "type": "credit_note"
  },
  "event_type": "based_on_receivable_created",
  "receivable_id": "628e6cc7-c44f-4c26-a7f1-a4b34dcfa429",
  ...
}
```

### `mail_sent`

*Applies to: all receivables*

This event indicates that an invoice, quote, or credit note was sent via email. This includes:

* Successful calls to [`POST /receivables/{receivable_id}/send`](/finops/reference/openapi/receivables/post-receivables-id-send).
* Automated scheduled emails containing [recurring invoices](/finops/guides/accounts-receivable/invoices/recurring).

The `event_data` object contains a list of email recipients and the email sending status per recipient and overall. The `mail_id` is the ID of the email sending operation that can be used to get the same information from [`GET /receivables/{receivable_id}/mails/{mail_id}`](/finops/reference/openapi/receivables/get-receivables-id-mails-id).

```json lines theme={null}
"event_data": {
  "mail_id": "19035294-5fe7-4019-8794-5288e3e4f2fa",
  "mail_status": "sent",
  "recipients": {
    "bcc": [],
    "cc": [],
    "to": [
      {
        "email": "customer@example.com",
        "error": null,
        "is_success": true
      }
    ]
  }
},
```

### `overdue_reminder_mail_sent`

*Applies to: invoices*

This event represents an [overdue invoice reminder](/finops/guides/accounts-receivable/invoices/overdue-reminders) sent via email.
Both automated scheduled reminders and [on-demand reminders](/finops/guides/accounts-receivable/invoices/overdue-reminders#manually-trigger-overdue-reminders) generate this event.

The `event_data` object contains a list of email recipients and the email sending status per recipient and overall. The `mail_id` is the ID of the email sending operation that can be used to get the same information from [`GET /receivables/{receivable_id}/mails/{mail_id}`](/finops/reference/openapi/receivables/get-receivables-id-mails-id).

```json expandable lines theme={null}
"event_data": {
  "mail_id": "19035294-5fe7-4019-8794-5288e3e4f2fa",
  "mail_status": "sent",
  "recipients": {
    "bcc": [],
    "cc": [],
    "to": [
      {
        "email": "customer@example.com",
        "error": null,
        "is_success": true
      }
    ]
  },
  "term": "overdue"
},
```

### `payment_received`

*Applies to: invoices*

This event indicates that a full or partial invoice payment has been received. This includes:

* payments made by counterparts via Tesouro [payment links](/finops/guides/payments/payment-links) and [embeddable payment component](/finops/guides/payments/payment-web-component),
* payments recorded by organization users via:
  * [`POST /payment-records`](/finops/reference/openapi/payment-records/post-payment-records)
  * [`POST /receivables/{receivable_id}/mark-as-paid`](/finops/reference/openapi/receivables/post-receivables-id-mark-as-paid)
  * [`POST /receivables/{receivable_id}/mark-as-partially-paid`](/finops/reference/openapi/receivables/post-receivables-id-mark-as-partially-paid)

The `event_data` object contains the payment amount, the remaining amount due for the given invoice, and the payment comment (the latter available only for payments recorded via `/mark-as-paid` and `/mark-as-partially-paid`).

```json lines theme={null}
"event_data": {
  "amount_due": 0,
  "amount_paid": 15000,
  "comment": "Paid via bank transfer on 2024/09/25"
}
```

### `payment_reminder_mail_sent`

*Applies to: invoices*

This event represents an [invoice payment reminder](/finops/guides/accounts-receivable/invoices/payment-reminders) sent via email.
Both automated scheduled reminders and [on-demand reminders](/finops/guides/accounts-receivable/invoices/payment-reminders#manually-trigger-payment-reminders) generate this event.

The `event_data` object contains the reminder type (`term`), a list of email recipients, and the email sending status per recipient and overall. The `mail_id` is the ID of the email sending operation that can be used to get the same information from [`GET /receivables/{receivable_id}/mails/{mail_id}`](/finops/reference/openapi/receivables/get-receivables-id-mails-id).

```json expandable lines theme={null}
"event_data": {
  "mail_id": "19035294-5fe7-4019-8794-5288e3e4f2fa",
  "mail_status": "sent",
  "recipients": {
    "bcc": [],
    "cc": [],
    "to": [
      {
        "email": "customer@example.com",
        "error": null,
        "is_success": true
      }
    ]
  },
  "term": "term_2"
},
```

### `receivable_created`

*Applies to: all receivables*

This is the first event in each receivable's history. It contains the date and time when this receivable was created, and a link to the PDF version of the initial draft document.

```json lines theme={null}
{
  ...
  "current_pdf_url": "https://tesouro-file-saver.example.com/12345/67890.pdf",
  "event_data": {},
  "event_type": "receivable_created",
  "receivable_id": "628e6cc7-c44f-4c26-a7f1-a4b34dcfa429",
  "timestamp": "2024-09-20T15:58:48.674227+00:00"
  ...
}
```

### `receivable_updated`

*Applies to: all receivables*

This event is recorded when a receivable is successfully updated via [`PATCH /receivables/{receivable_id}`](/finops/reference/openapi/receivables/patch-receivables-id) or when its [line items are updated](/finops/guides/accounts-receivable/invoices/manage#update-invoice-line-items).

The `receivable_updated` events have empty `event_data`. Instead, the `current_pdf_url` contains a link to the PDF version of the document after the change.

```json lines theme={null}
{
  ...
  "current_pdf_url": "https://tesouro-file-saver.example.com/12345/67890.pdf",
  "event_data": {},
  "event_type": "receivable_updated",
  ...
}
```

<Warning>
  The following changes do not trigger the `receivable_updated` event:

  * Updates made to external linked objects - organization, counterpart, their bank accounts, payment terms, and others - unless followed by a call to `PATCH /receivables/{receivable_id}`.
  * Status transitions (for example, from `draft` to `issued`). They trigger the [`status_changed`](#status_changed) event instead.
</Warning>

### `status_changed`

*Applies to: all receivables*

This event indicates that a document's `status` was changed. The `event_data` object contains the old and new statuses of the document. If the status change caused an update of the PDF version of the document, a link to the new PDF is stored in `current_pdf_url`.

```json lines theme={null}
{
  ...
  "current_pdf_url": "https://tesouro-file-saver.example.com/12345/67890.pdf",
  "event_data": {
    "old_status": "draft",
    "new_status": "issued"
  },
  "event_type": "status_changed",
  ...
}
```

See [invoice statuses](/finops/guides/accounts-receivable/invoices/index#invoice-statuses), [quote statuses](/finops/guides/accounts-receivable/quotes/index#quote-statuses), and [credit note statuses](/finops/guides/accounts-receivable/credit-notes#credit-note-lifecycle) for the possible status values.

## See also

* [Webhooks](/finops/guides/getting-started/webhooks/index) - get notified about certain events in real time