Document history
---
title: Document history
subtitle: >-
Learn how to review the history of changes made to an invoice, quote, or
credit note.
---
## Overview
Monite keeps a history of changes made to all [accounts receivable](./index) documents - [invoices](./invoices/index), [quotes](./quotes/index), and [credit notes](./credit-notes) - from document creation to the final status. This provides entities 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](../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`](/api/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](/api/receivables/get-receivables-id-history).
```json
{
"data": [
{
"id": "59c70641-213c-41fc-9105-5be84f8cfbbc",
"current_pdf_url": "https://monite-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 [#permissions]
To access a receivable's change history using an [entity user token](../entities/users#get-entity-user-token),
this user must have a role with the `receivables.read` [permission](/api/concepts/authentication#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](../get-started/credentials#generate-partner-token) 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
{
...
"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`](/api/receivables/post-receivables-id-send).
* Automated scheduled emails containing [recurring invoices](./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}`](/api/receivables/get-receivables-id-mails-id).
```json
"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](./invoices/overdue-reminders) sent via email.
Both automated scheduled reminders and [on-demand reminders](./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}`](/api/receivables/get-receivables-id-mails-id).
```json
"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 Monite [payment links](../payments/payment-links) and [embeddable payment component](../payments/payment-web-component),
* payments recorded by entity users via:
* [`POST /payment_records`](/api/payment-records/post-payment-records)
* [`POST /receivables/{receivable_id}/mark_as_paid`](/api/receivables/post-receivables-id-mark-as-paid)
* [`POST /receivables/{receivable_id}/mark_as_partially_paid`](/api/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
"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](./invoices/payment-reminders) sent via email.
Both automated scheduled reminders and [on-demand reminders](./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}`](/api/receivables/get-receivables-id-mails-id).
```json
"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
{
...
"current_pdf_url": "https://monite-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"
...
}
```
{/*
<Info>The `timestamp` of the `receivable_created` event may differ by milliseconds from the `created_at` timestamp of the receivable itself due to technical reasons. We recommend that you discard the milliseconds part when displaying creation timestamps to your users.</Info>
*/}
### `receivable_updated`
_Applies to: all receivables_
This event is recorded when a receivable is successfully updated via [`PATCH /receivables/{receivable_id}`](/api/receivables/patch-receivables-id) or when its [line items are updated](./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
{
...
"current_pdf_url": "https://monite-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 - entity, 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
{
...
"current_pdf_url": "https://monite-file-saver.example.com/12345/67890.pdf",
"event_data": {
"old_status": "draft",
"new_status": "issued"
},
"event_type": "status_changed",
...
}
```
See [invoice statuses](./invoices/index#invoice-statuses), [quote statuses](./quotes/index#quote-statuses), and [credit note statuses](./credit-notes#credit-note-lifecycle) for the possible status values.
## See also
* [Webhooks](../../references/webhooks/index) - get notified about certain events in real time