# Events

Retrieve immutable records of changes in an account.

FiscalRail creates an immutable Event whenever a supported account resource changes. Live and Test accounts have separate event streams.

Every Event contains a `related_object` reference and a `data.object` snapshot captured when the event occurred. The snapshot never changes, including after the resource is updated or deleted. Retrieve the related resource by its ID when you need its current state.

The `actor` identifies what caused the event. API requests expose the API key and request ID, dashboard actions expose the user and request ID, and automated actions use the `system` type with null IDs.

Webhook deliveries use the same top-level envelope but omit `data`. Retrieve the Event by ID when a webhook handler needs its historical snapshot.

## Balance transactions

`billing.balance_transaction.created` is emitted whenever money moves in a Live
account balance. Its `related_object` is the immutable Balance Transaction and
`data.object` contains its complete snapshot.

Usage transactions have a negative `amount_cents` and identify the successful
domain Event that caused the debit in `source_event`. Top-ups have a positive
amount and a null source. Test accounts do not hold balances, so they emit their
normal domain Events but no balance transaction Event.

## The Balance Transaction object

### Properties

#### `id`

Type: `string`

Opaque identifier for the balance transaction.

#### `object`

Type: `string`

String identifying this as a Balance Transaction object. Always `balance_transaction`.

#### `live`

Type: `boolean`

True when the object belongs to the live environment; false for test data.

#### `account`

Type: `string`

Account whose balance changed.

#### `kind`

Type: `enum`

Whether the transaction debited usage or credited a top-up.

Possible values:

- `usage` — 
- `top_up` — 

#### `amount_cents`

Type: `integer`

Signed amount in euro cents. Usage is negative and top-ups are positive.

#### `currency`

Type: `enum`

Billing currency for the amount.

Possible values:

- `EUR` — 

#### `source_event`

Type: `string or null`

Domain Event that caused a usage debit. Null for top-ups.

#### `created_at`

Type: `string`

When the balance transaction was created.


### Example

```json
{
  "id": null,
  "object": "balance_transaction",
  "live": null,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "kind": null,
  "amount_cents": null,
  "currency": null,
  "source_event": null,
  "created_at": null
}
```

## The Event object

### Properties

#### `id`

Type: `string`

Opaque identifier for the event.

#### `object`

Type: `string`

String identifying this as an Event object. Always `event`.

#### `live`

Type: `boolean`

True when the object belongs to the live environment; false for test data.

#### `account`

Type: `string`

Account in which the event occurred.

#### `type`

Type: `string`

Stable event type used when configuring subscriptions.

#### `occurred_at`

Type: `string`

When the represented change occurred.

#### `actor`

Type: `object`

Actor and request that caused the event.

##### `actor.type`

Type: `enum`

Kind of actor that caused the event.

Possible values:

- `api_key` — 
- `user` — 
- `system` — 

##### `actor.id`

Type: `string or null`

API key or user ID. Null for system events.

##### `actor.request_id`

Type: `string or null`

Request ID for API and dashboard actions. Null for system events.


#### `related_object`

Type: `object or null`

Reference to the primary resource represented by the event.

##### `related_object.id`

Type: `string`

Opaque identifier for the related resource.

##### `related_object.object`

Type: `string`

API object type of the related resource.


#### `data`

Type: `object`

Immutable resource snapshot stored when the event occurred.

##### `data.object`

Type: `object`

Complete API representation captured for this event.

##### `data.previous_attributes`

Type: `object`

Previous values of changed properties for update events.



### Example

```json
{
  "id": null,
  "object": "event",
  "live": null,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "type": null,
  "occurred_at": null,
  "actor": {
    "type": null,
    "id": null,
    "request_id": null
  },
  "related_object": {
    "id": null,
    "object": null
  },
  "data": {
    "object": {},
    "previous_attributes": {}
  }
}
```

## Event types

### `billing.balance_transaction.created`

Emitted when billing balance transaction created.

### `customer.created`

Emitted when customer created.

### `customer.updated`

Emitted when customer updated.

### `customer.deleted`

Emitted when customer deleted.

### `tax_id.verification.completed`

Emitted when tax id verification completed.

### `tax_id.verification.failed`

Emitted when tax id verification failed.

### `invoice.issued`

Emitted when invoice issued.

### `invoice.amended`

Emitted when invoice amended.

### `invoice.pdf_rendered`

Emitted when invoice pdf rendered.

### `invoice.verifactu_registration.accepted`

Emitted when invoice verifactu registration accepted.

### `invoice.verifactu_registration.accepted_with_errors`

Emitted when invoice verifactu registration accepted with errors.

### `invoice.verifactu_registration.rejected`

Emitted when invoice verifactu registration rejected.

New event types can be added over time. Code that listens to all events must ignore types it does not handle.

## Retrieve an event

`GET /v1/events/{id}`

### Path parameters

#### `id`

Type: `string` — required

The opaque event ID.


### Responses

- `200` — [An Event object including its immutable snapshot.](#the-event-object) Formats: JSON.

### Example request

```bash
curl --request GET \
  'https://api.fiscalrail.com/v1/events/example' \
  --header "Authorization: Bearer ak_test_..."
```

### Example response — 200

```json
{
  "id": null,
  "object": "event",
  "live": null,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "type": null,
  "occurred_at": null,
  "actor": {
    "type": null,
    "id": null,
    "request_id": null
  },
  "related_object": {
    "id": null,
    "object": null
  },
  "data": {
    "object": {},
    "previous_attributes": {}
  }
}
```

## List events

`GET /v1/events`

Returns immutable events in reverse chronological ID order.

### Query parameters

#### `limit`

Type: `integer`

Maximum number of resources to return. Defaults to `25`.

#### `starting_after`

Type: `string`

Return events older than this event ID.

#### `ending_before`

Type: `string`

Return events newer than this event ID.

#### `types`

Type: `array of strings`

Up to 20 exact event types to include.


### Responses

- `200` — [A list of Event objects.](#the-event-object) Formats: JSON.

### Example request

```bash
curl --request GET \
  'https://api.fiscalrail.com/v1/events?limit=25' \
  --header "Authorization: Bearer ak_test_..."
```

### Example response — 200

```json
{
  "object": "list",
  "has_more": null,
  "data": [
    {
      "id": null,
      "object": "event",
      "live": null,
      "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
      "type": null,
      "occurred_at": null,
      "actor": {
        "type": null,
        "id": null,
        "request_id": null
      },
      "related_object": {
        "id": null,
        "object": null
      },
      "data": {
        "object": {},
        "previous_attributes": {}
      }
    }
  ]
}
```