---
title: "Invoice history"
description: "What happened to a document: every time it was emailed (to which address, whether that is the customer's, and whether it was automatic, a payment reminder, a bulk send or a BCC copy), printed, downloaded or opened, newes"
url: https://docs.invoicefalcon.com/v3-reference/documents/invoice-history/
api: "API v3 reference"
method: GET
path: "/documents/invoices/{id}/history"
---

# Invoice history

`GET https://app.invoicefalcon.com/api/v3/external/documents/invoices/{id}/history`

What happened to a document: every time it was emailed (to which address, whether that is the customer's, and whether it was automatic, a payment reminder, a bulk send or a BCC copy), printed, downloaded or opened, newest first, plus the emails sent for it with the recipient and the delivery, open, click and bounce timestamps the mail provider reported. The last 200 of each. Read-only.

`event` values: `sent` (Emailed to the customer), `reminder_sent` (Payment reminder emailed), `copy_sent` (Copy emailed to the shop (BCC)), `printed` (Printed), `downloaded` (Downloaded), `viewed` (Opened in the dashboard), `rendered` (Rendered on the customer account page).

## Path parameters

- `id` (string, required)

## Returns

- `invoice_id` (integer): e.g. `980191021`
- `invoice_number` (string): e.g. `INV-2`
- `customer_email` (string, nullable)
- `events` (array of objects)
  - `id` (integer): e.g. `46`
  - `event` (string): e.g. `sent`
  - `at` (string): e.g. `2026-11-10T09:07:40Z`
  - `automatic` (boolean): e.g. `false`
  - `bulk` (boolean): e.g. `false`
  - `template` (string): e.g. `default`
  - `to` (string): e.g. `test@example.com`
- `emails` (array of objects)
  - `id` (integer): e.g. `5`
  - `to` (string): e.g. `test@example.com`
  - `kind` (string): e.g. `invoice`
  - `sent_at` (string): e.g. `2026-11-10T09:07:40Z`
  - `delivered_at` (string, nullable)
  - `opened_at` (string, nullable)
  - `clicked_at` (string, nullable)
  - `bounced_at` (string, nullable)
  - `bounce_reason` (string, nullable)
  - `rejected_at` (string, nullable)
  - `complained_at` (string, nullable)

Rate limit: this call costs 1 point ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Example request

```sh
curl "https://app.invoicefalcon.com/api/v3/external/documents/invoices/980191059/history" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
```

## 200

The requested resource.

```json
{
  "invoice_id": 980191021,
  "invoice_number": "INV-2",
  "customer_email": null,
  "events": [
    {
      "id": 46,
      "event": "sent",
      "at": "2026-11-10T09:07:40Z",
      "automatic": false,
      "bulk": false,
      "template": "default",
      "to": "test@example.com"
    }
  ],
  "emails": [
    {
      "id": 5,
      "to": "test@example.com",
      "kind": "invoice",
      "sent_at": "2026-11-10T09:07:40Z",
      "delivered_at": null,
      "opened_at": null,
      "clicked_at": null,
      "bounced_at": null,
      "bounce_reason": null,
      "rejected_at": null,
      "complained_at": null
    }
  ]
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 404

The resource does not exist for this shop, or no action is registered at this path.

```json
{
  "errors": [
    "Resource not found"
  ],
  "code": "not_found"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

