Document history

This guide covers the document history for accounts receivable documents. Tesouro also provides document history for accounts payable documents.

Overview

Tesouro 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 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 made towards an invoice.

Change history data is available only for changes made since September 30, 2024.

To access a document’s history, call GET /receivables/{receivable_id}/history. You can filter the history by event_type__in, by entity_user_id__in to see only the events caused by particular organization users, and by a timestamp range. Results are ordered by timestamp and paginated with prev_pagination_token and next_pagination_token. To read a single record, call GET /receivables/{receivable_id}/history/{receivable_history_id}. It returns one record in the same shape as an entry in the list. 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.

{
  "data": [
    {
      "id": "59c70641-213c-41fc-9105-5be84f8cfbbc",
      "current_pdf_url": "https://tesouro-file-saver.example.com/12345/67890.pdf",
      "recorded_by": "user",
      "entity_user_id": "9598d748-a5aa-4c60-b490-391b610beaef",
      "entity_user_first_name": "Mary",
      "entity_user_last_name": "Wong",
      "entity_user_role_id": "9f8b1a2c-3d4e-4f50-a61b-7c8d9e0f1a2b",
      "entity_user_role_name": "Finance admin",
      "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"
    },
    ...
  ],
  "prev_pagination_token": null,
  "next_pagination_token": "eyJvcmQiOiJ0aW1lc3RhbXAifQ"
}

Roles and permissions

To access a receivable’s change history using an organization 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.

Who made the change

Every history record identifies the actor behind the event:

Field	Description
`recorded_by`	`user` if the event is attributed to an organization user, `system` if it is not - for example, an automated reminder, or a change made using a partner-level token.
`entity_user_id`	ID of the organization user who made the change or triggered the event, or `null` in `system` records.
`entity_user_first_name`	First name of that organization user.
`entity_user_last_name`	Last name of that organization user.
`entity_user_role_id`	ID of the role that the organization user held at the time of the event.
`entity_user_role_name`	Name of that role.

The name and role values are captured when the record is written and are never recalculated, so a record shows the name and role that the user held at the time of the event, not the ones they hold today. All four are null on any record where they were not captured, which happens in three cases: the record is a system record, the record predates these fields, or the name or role could not be resolved when the record was written. recorded_by separates the first case from the other two.

The document PDF

Some records carry a current_pdf_url, a link to the PDF of the document as it stood after the change. It is populated only in receivable_created, receivable_updated, status_changed, and payment_received records, and is null in all other event types. In payment_received records it is populated only for a full payment, and only when the organization setting generate_paid_invoice_pdf is true.

Tesouro generates PDFs asynchronously. The current_pdf_url of a record read right after the event usually starts as null and is populated once the PDF has been generated.

Event types

Document history includes the following event types:

Event type	Invoices	Quotes	Credit notes
`based_on_receivable_created`	✔	✔
`deleted`	✔	✔	✔
`mail_sent`	✔	✔	✔
`overdue_reminder_mail_sent`	✔
`payment_received`	✔
`payment_reminder_mail_sent`	✔
`receivable_created`	✔	✔	✔
`receivable_updated`	✔	✔	✔
`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…:

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

`deleted`

Applies to: all receivables This event indicates that a draft document was deleted by calling DELETE /receivables/{receivable_id}. Only draft documents can be deleted. The event_data object contains the old_status that the document held before it was deleted. A deletion does not also record a status_changed event, so the timeline shows a single deleted event for the moment the document was removed.

{
  ...
  "event_data": {
    "old_status": "draft"
  },
  "event_type": "deleted",
  "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.
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}.

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

"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 and embeddable payment component,
payments recorded by organization users via:

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). It also contains the provenance of the payment. Any of these five fields can be null, and which of them are populated depends on how the payment was recorded:

payment_record_id - ID of the payment record behind this payment.
payment_intent_id - ID of the payment intent that was paid.
payment_method - the payment method used, for example ach.
paid_at - the date and time when the payment was made.
is_external - true if the payment was recorded against external payment rails, false if Tesouro processed it.

A payment made through Tesouro payment rails, and a payment recorded via POST /payment-records, both go through a payment record. Tesouro generates the payment_record_id and sets is_external itself in both cases, so neither is something you send and both are always present. is_external is what tells the two paths apart. payment_intent_id is present too, because a payment record cannot reach the succeeded status without one. A payment recorded directly via /mark-as-paid or /mark-as-partially-paid skips the payment record, so it carries only the provenance that the call itself included. A call that sends none records all five as null.

"event_data": {
  "amount_due": 0,
  "amount_paid": 15000,
  "comment": "Paid via bank transfer on 2024/09/25",
  "payment_record_id": "c1a4a3d0-1c79-4b17-9f79-f898c93e5f97",
  "payment_intent_id": "a2b8c6e1-527c-4586-84c9-95881e7ba19f",
  "payment_method": "ach",
  "paid_at": "2024-09-25T12:00:00+00:00",
  "is_external": false
}

`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}. In this event the term is one of:

term_1 - sent before discount date 1.
term_2 - sent before discount date 2.
term_final - sent before the invoice due date.

An overdue_reminder_mail_sent event always carries overdue instead.

"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. The event_data object contains the status that the document was created with, and the source that describes how it came into being:

manual - created directly through the API.
based_on - derived from another document, for example an invoice created from a quote.
recurrence - issued by a recurring invoice.

{
  ...
  "current_pdf_url": "https://tesouro-file-saver.example.com/12345/67890.pdf",
  "event_data": {
    "status": "draft",
    "source": "manual"
  },
  "event_type": "receivable_created",
  "receivable_id": "628e6cc7-c44f-4c26-a7f1-a4b34dcfa429",
  "timestamp": "2024-09-20T15:58:48.674227+00:00"
  ...
}

This event is recorded on the document that was created. It is distinct from based_on_receivable_created, which is recorded on the source document to point at the new one.

`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 event_data object contains a fields map that describes what changed. Each entry is keyed by the name of a changed field, and gives the old and new values of that field. Both keys are always present, and either can be null when the value was unset or cleared. Fields that hold a nested object are expanded into dotted paths, so changing one part of an address records a single counterpart_billing_address.city entry rather than replacing the whole object. Where a field holds an ID that resolves to a display name, the entry also carries old_label and new_label - currently counterpart_id. The following fields are tracked:

attachments
bank_account_id
bank_account_type
counterpart_billing_address
counterpart_contact
counterpart_id
counterpart_shipping_address
counterpart_vat_id
currency
discount
document_rendering
entity
entity_address
entity_vat_id
expiry_date
footer
fulfillment_date
line_items
memo
overdue_reminder_id
payment_page_url
payment_reminder_id
payment_terms
project_id
quote_accept_page_url
signature_required
tag_ids
tax_exempt
tax_exemption_rationale
withholding_tax_rate

line_items and attachments are recorded as whole lists rather than expanded into dotted paths, and reordering either of them counts as a change. The order of tag_ids is not significant, so reordering the tags of a document is not recorded as a change. An update that writes none of the tracked fields still records a receivable_updated event, carrying an empty field map ({"fields": {}}). A change confined to fields outside the list above is the usual reason for one. The current_pdf_url contains a link to the PDF version of the document after the change.

{
  ...
  "current_pdf_url": "https://tesouro-file-saver.example.com/12345/67890.pdf",
  "event_data": {
    "fields": {
      "counterpart_id": {
        "old": "3f2dbb6e-8e1a-4f2b-9c3d-5a7f1e2b4c60",
        "new": "8b1ce4a2-77d5-4a19-b0f6-2c9e3d8a5471",
        "old_label": "Acme Inc.",
        "new_label": "Globex LLC"
      },
      "memo": {
        "old": "Dear customer! Pay please",
        "new": "Thank you for your business"
      }
    }
  },
  "event_type": "receivable_updated",
  ...
}

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 event instead.

`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. When an invoice is marked uncollectible with a comment, the event_data object also contains that comment. Every other transition carries only old_status and new_status.

{
  ...
  "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, quote statuses, and credit note statuses for the possible status values.

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Document history

Overview

Roles and permissions

Who made the change

The document PDF

Event types

`based_on_receivable_created`

`deleted`

`mail_sent`

`overdue_reminder_mail_sent`

`payment_received`

`payment_reminder_mail_sent`

`receivable_created`

`receivable_updated`

`status_changed`

See also

​Overview

​Roles and permissions

​Who made the change

​The document PDF

​Event types

​based_on_receivable_created

​deleted

​mail_sent

​overdue_reminder_mail_sent

​payment_received

​payment_reminder_mail_sent

​receivable_created

​receivable_updated

​status_changed

​See also

Overview

Roles and permissions

Who made the change

The document PDF

Event types

`based_on_receivable_created`

`deleted`

`mail_sent`

`overdue_reminder_mail_sent`

`payment_received`

`payment_reminder_mail_sent`

`receivable_created`

`receivable_updated`

`status_changed`

See also