# Invoice updated

> Sent when anything on an invoice changes, such as a line item, a payment, a credit or its status.

`eventType` is `invoice.updated`.

Sent when anything on an existing invoice changes: a line item, a payment, a credit or its status. It comes with every change after creation, so subscribing to it alone catches everything.

Finserv records one change as several steps a few seconds apart, such as a payment and then the new balance. Mothership waits until an invoice has gone about 8 seconds without a change, then sends each event that applies once, with the invoice as it is then. A payment that settles an invoice sends one `invoice.status.updated`, one `invoice.paid` and one `invoice.updated`.

## Subscribing

Add `invoice.updated` to a configuration's `subscribedEvents`. The token needs permission to read invoices. Without it, creating or updating a webhook configuration so that it has this event answers `403 MISSING_PERMISSION`. Such a token can still remove the event from a configuration.

## Event data

- `invoice` (object): The invoice as it is when Mothership sends the event, named as Retrieve an invoice names it. Call that with `invoice.id` for line items, payments and credits.
  - `id` (string): The invoice's ID. Pass it to Retrieve an invoice.
  - `referenceNumber` (string): The invoice's reference number, such as `MSI123456`.
  - `status` (string): Where the invoice is. One of: `open`, `paid`, `pastDue`, `void`.
  - `entityType` (string): What the invoice bills. One of: `shipment`, `claim`, `statement`, `payment`.
  - `entityId` (string): For a shipment, its reference number, such as `MS123456`. Otherwise the ID of what the invoice bills.
  - `total` (integer): The invoice's total, in cents.
  - `amountDue` (integer): What is still owed, in cents.
  - `currency` (string): Always `usd`.
  - `dueDate` (string, nullable): When the invoice is due, as an ISO 8601 string.
  - `createdAt` (string): When the invoice was created, as an ISO 8601 string in UTC.
  - `updatedAt` (string): When the invoice last changed, as an ISO 8601 string in UTC. Order events for one invoice by this, not by when they arrive.

## Envelope

Mothership sends a `POST` with this JSON body. The envelope is the same on every event, and `data` holds the keys above.

- `eventType` (string): The event. Always `invoice.updated` here. Route on it, and answer `2xx` to types you don't handle.
- `sentAt` (string): When Mothership queued the event to send, as an ISO 8601 string in UTC. Every retry and resend carries the same value, so it does not say when this attempt went out.
- `deliveryAttempt` (integer): Which send of this event this is, starting at `1`. Resends from the dashboard count too.
- `pendingRetries` (integer): How many automatic attempts are left if this one fails. `0` on the last one.

## Example request

```json Example body
{
  "eventType": "invoice.updated",
  "data": {
    "invoice": {
      "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "referenceNumber": "MSI123456",
      "status": "open",
      "entityType": "shipment",
      "entityId": "MS123456",
      "total": 47500,
      "amountDue": 47500,
      "currency": "usd",
      "dueDate": "2026-11-07T15:04:05.000Z",
      "createdAt": "2026-10-08T15:04:05.000Z",
      "updatedAt": "2026-10-09T18:22:10.000Z"
    }
  },
  "sentAt": "2026-10-08T15:04:05.000Z",
  "deliveryAttempt": 1,
  "pendingRetries": 16
}
```