Events — FiscalRail documentation

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 string

Opaque identifier for the balance transaction.

object string

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

live boolean

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

account string

Account whose balance changed.

kind enum

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

Possible values

usage

top_up

amount_cents integer

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

currency enum

Billing currency for the amount.

Possible values

EUR

source_event string or null

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

created_at string

When the balance transaction was created.

Balance Transaction object

{
  "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 string

Opaque identifier for the event.

object string

String identifying this as an Event object. Always event.

live boolean

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

account string

Account in which the event occurred.

type string

Stable event type used when configuring subscriptions.

occurred_at string

When the represented change occurred.

actor object

Actor and request that caused the event.

Show child propertiesHide child properties

type enum

Kind of actor that caused the event.

Possible values

api_key

user

system

id string or null

API key or user ID. Null for system events.

request_id string or null

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

related_object object or null

Reference to the primary resource represented by the event.

Show child propertiesHide child properties

id string

Opaque identifier for the related resource.

object string

API object type of the related resource.

data object

Immutable resource snapshot stored when the event occurred.

Show child propertiesHide child properties

object object

Complete API representation captured for this event.

previous_attributes object

Previous values of changed properties for update events.

Event object

{
  "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 string required

The opaque event ID.

Responses

200 An Event object including its immutable snapshot. JSON

Example request

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

Example response — 200

{
  "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 integer

Maximum number of resources to return. Defaults to 25.

starting_after string

Return events older than this event ID.

ending_before string

Return events newer than this event ID.

types array of strings

Up to 20 exact event types to include.

Responses

200 A list of Event objects. JSON

Example request

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

Example response — 200

{
  "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": {}
      }
    }
  ]
}