Document history

Overview

Monite keeps a history of changes made to all accounts receivable documents - invoices, quotes, and 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 made towards an invoice.

To access a document’s history, call GET /receivables/{receivable_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.

1
{
2
  "data": [
3
    {
4
      "id": "59c70641-213c-41fc-9105-5be84f8cfbbc",
5
      "current_pdf_url": "https://monite-file-saver.example.com/12345/67890.pdf",
6
      "entity_user_id": "9598d748-a5aa-4c60-b490-391b610beaef",
7
      "event_data": {
8
        "new_status": "issued",
9
        "old_status": "draft"
10
      },
11
      "event_type": "status_changed",
12
      "receivable_id": "628e6cc7-c44f-4c26-a7f1-a4b34dcfa429",
13
      "timestamp": "2024-09-20T15:58:48.674227+00:00"
14
    },
15
    ...
16
  ]
17
}

Roles and permissions

To access a receivable’s change history using an entity user token, this user must have a role with the receivables.read permission. 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 is used, no special permissions are needed.

Event types

Document history includes the following event types:

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

1
{
2
  ...
3
  "event_data": {
4
    "receivable_id": "0d51871f-4241-47e6-95b7-0bba0fec45e7",
5
    "type": "credit_note"
6
  },
7
  "event_type": "based_on_receivable_created",
8
  "receivable_id": "628e6cc7-c44f-4c26-a7f1-a4b34dcfa429",
9
  ...
10
}

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.
• Automated scheduled emails containing recurring invoices.

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

1
"event_data": {
2
  "mail_id": "19035294-5fe7-4019-8794-5288e3e4f2fa",
3
  "mail_status": "sent",
4
  "recipients": {
5
    "bcc": [],
6
    "cc": [],
7
    "to": [
8
      {
9
        "email": "customer@example.com",
10
        "error": null,
11
        "is_success": true
12
      }
13
    ]
14
  }
15
},

overdue_reminder_mail_sent

Applies to: invoices

This event represents an overdue invoice reminder sent via email. Both automated scheduled reminders and on-demand 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}.

1
"event_data": {
2
  "mail_id": "19035294-5fe7-4019-8794-5288e3e4f2fa",
3
  "mail_status": "sent",
4
  "recipients": {
5
    "bcc": [],
6
    "cc": [],
7
    "to": [
8
      {
9
        "email": "customer@example.com",
10
        "error": null,
11
        "is_success": true
12
      }
13
    ]
14
  },
15
  "term": "overdue"
16
},

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 and embeddable payment component,
• payments recorded by entity users via:
  • POST /payment_records
  • POST /receivables/{receivable_id}/mark_as_paid
  • POST /receivables/{receivable_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).

1
"event_data": {
2
  "amount_due": 0,
3
  "amount_paid": 15000,
4
  "comment": "Paid via bank transfer on 2024/09/25"
5
}

payment_reminder_mail_sent

Applies to: invoices

This event represents an invoice payment reminder sent via email. Both automated scheduled reminders and on-demand 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}.

1
"event_data": {
2
  "mail_id": "19035294-5fe7-4019-8794-5288e3e4f2fa",
3
  "mail_status": "sent",
4
  "recipients": {
5
    "bcc": [],
6
    "cc": [],
7
    "to": [
8
      {
9
        "email": "customer@example.com",
10
        "error": null,
11
        "is_success": true
12
      }
13
    ]
14
  },
15
  "term": "term_2"
16
},

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.

1
{
2
  ...
3
  "current_pdf_url": "https://monite-file-saver.example.com/12345/67890.pdf",
4
  "event_data": {},
5
  "event_type": "receivable_created",
6
  "receivable_id": "628e6cc7-c44f-4c26-a7f1-a4b34dcfa429",
7
  "timestamp": "2024-09-20T15:58:48.674227+00:00"
8
  ...
9
}

receivable_updated

Applies to: all receivables

This event is recorded when a receivable is successfully updated via PATCH /receivables/{receivable_id} or when its line items are updated.

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.

1
{
2
  ...
3
  "current_pdf_url": "https://monite-file-saver.example.com/12345/67890.pdf",
4
  "event_data": {},
5
  "event_type": "receivable_updated",
6
  ...
7
}

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.

1
{
2
  ...
3
  "current_pdf_url": "https://monite-file-saver.example.com/12345/67890.pdf",
4
  "event_data": {
5
    "old_status": "draft",
6
    "new_status": "issued"
7
  },
8
  "event_type": "status_changed",
9
  ...
10
}

See invoice statuses, quote statuses, and credit note statuses for the possible status values.

See also

• Audit log - review all API calls made to an entity’s resources
• Webhooks - get notified about certain events in real time