# Retrieving events

GET `https://app.iteras.dk/api/events/`

The API key must allow "Retrieve event data".

Lists the events in the history of the account: changes to customers and subscriptions, invoices, payments and more.

Changes in Iteras produce events - a customer is created, an address is updated, a subscription changes status. Events exist for customers, subscriptions, vacations and future changes, product assignments, invoices, payments and campaigns and more. Each event has a type, a timestamp and an increasing `event_id`. Keeping another system up to date is essentially a matter of processing the events in order. See the [synchronization guide](/api/docs/guides/synchronization.md) for how to do this.

It is also possible to receive the raw event data as the events happen, by setting up [event webhooks](/api/docs/server/webhooks.md). Using a webhook reduces the latency, as Iteras pushes the event data immediately to your server - but that of course requires you to have a server set up to receive the data, whereas you can call this endpoint at your leisure.

## Using events

In some cases, you want to learn about what's happening. The attributes on the events describe that. Much of that is internal to Iteras, though.

In many cases, what you really want to know is the new state of the changed object, e.g. the customer or a subscription. Instead of having to go through the customer data API to retrieve that information immediately afterwards, you can pass a prefetch parameter. Then Iteras will the attach the information about the concerned objects directly.

The prefetched data comes in the same format as when you [retrieve customer data](/api/docs/server/retrievingcustomers.md) to make it trivial to use the same code to update a system whether the data comes from events or from the customer data API.

There are many events in Iteras, so use filtering to get only those you're interested in.

## Parameters

All parameters are optional.

- `event_id` (string): ID of a specific event, e.g. `event_id=462416`.
- `customer` (string): Events for a specific customer with the provided customer ID, e.g. `customer=9224437`.
- `types` (string): Events with the requested event types, repeating the parameter for each type, e.g. `types=customer:created&types=customer:deleted`.

  The available types are listed on the [event types](/api/docs/server/eventtypes.md) page.
- `created_before` (date): Events created on or before the date, given as `YYYY-MM-DD`.
- `created_after` (date): Events created on or after the date, given as `YYYY-MM-DD`.
- `created_before_id` (string): Events created before the event with the given ID, e.g. `created_before_id=63524` (the event with ID not included).
- `created_after_id` (string): Events created after the event with the given ID, e.g. `created_after_id=63524` (the event with ID not included).
- `exclude_from_webhooks` (bool): Filter on whether the events were excluded from webhooks by a mass update through the API or an automation, e.g. `exclude_from_webhooks=false`.

  See [bulk updates](/api/docs/server/customerbulkupdates.md) for how a mass update excludes events from webhooks. The values are:

  - `false` - only the events that are sent to webhooks.
  - `true` - only the excluded events.
  - Left out - all events.
- `newest_first` (bool, Defaults to `false`, may change): Return the newest events first, e.g. `newest_first=true`, to see what happened last. The `next_url` then continues with older events.
- `max_results` (integer, Defaults to `10000`): How many events to retrieve at most, e.g. `max_results=1000`. If there are more results available, a `next_url` is returned which you can use to grab the next page.
- `prefetch` (string): Settings for attaching data about the objects each event concerns, each of three parts separated by colon: the event object type, the type of setting and its value, e.g. `prefetch=customer:fields:data,subscriptions`.

  The default is that no prefetching is done.

  For the events available through this API except the campaign events, the fields available for prefetch are related to the customer of the event. The available fields are the same as the ones you can fetch for customers via `/api/customers/`. E.g. when fetching payment events, the prefetch options are based on the customer data, so that to prefetch customers, their subscriptions and payments the prefetch settings could be `payment:fields:data,subscriptions,payments`. To prefetch only the subscription, payment or invoice related to the event, you can add the setting `subscription:single_subscription:true`, `payment:single_payment:true` or `invoice:single_invoice:true` to the list of settings.

  If you add a setting for an event type without a `fields` setting, only the ID of the customer is prefetched.

  - `customer:fields:subscriptions`: Prefetch a list of subscriptions for the prefetched customers.
  - `subscription:fields:data`: Fetch related customer data for each subscription event.
  - `subscription:fields:subscriptions.begin`: Fetch related customer subscription data for each subscription event.
  - `campaign:fields:data`: Fetch related campaign data for each campaign event.
  - `payment:fields:data,subscriptions,payments`: Fetch all subscriptions and payment data for the related customer for each payment event.
  - `invoice:fields:data,invoices`: Fetch related customer invoices for each invoice event.
  - `subscription:single_subscription:true`: Fetch only subscription data for the event subscription for the related customer prefetch data.
  - `payment:single_payment:true`: Fetch only payment data for the event payments for the related customer prefetch data.
  - `invoice:single_invoice:true`: Fetch only invoice data for the event invoice for the related customer prefetch data.

A `customer` or `event_id` that does not exist returns a plain text HTTP 404 error. A malformed `created_after`/`created_before`, a non-numeric `created_after_id`/`created_before_id`, an unavailable `types` value, an `exclude_from_webhooks` that isn't `true` or `false` or a malformed `prefetch` returns a plain text HTTP 400 error.

## Return value

The data returned is an object with an array of event information (possibly empty array). The events will be sorted with the oldest event first.

Note that the content depends on the type of the event. Each event object may contain the following attributes:

- `event` (string): The type of the event, e.g. `customer:created`. The available types are listed on the [event types](/api/docs/server/eventtypes.md) page.
- `event_id` (string): Increasing ID of the event, e.g. `6791`. Use it to keep track of which events you have processed.
- `timestamp` (datetime): When the change happened, as `YYYY-MM-DDTHH:MM:SS`, e.g. `2026-11-21T13:56:56`.
- `customer_id` (string): Customer ID of the customer the event concerns, e.g. `4560`. Included if the event concerns a customer.
- `subscription_id` (string): Subscription ID of the subscription the event concerns, e.g. `10243`. Included if the event concerns a subscription.
- `data` (object): The raw event data, e.g. `{"name": "Arnold Smith", "email": "a@smith.com"}`. The fields depend on the event type; amounts are in the main currency with two decimals.
- `prefetch` (object): Data about the concerned objects, in the same format as [retrieving customers](/api/docs/server/retrievingcustomers.md), e.g. `{"customers": [{"id": "4560", "name": "Arnold Smith"}]}`. Included when a `prefetch` setting is passed.

```http
GET /api/events/?created_after_id=6789&types=customer:created&types=payment:created&prefetch=customer:fields:data&prefetch=payment:fields:data&prefetch=payment:single_payment:true
```

```json
{
  "events": [
    {
      "event_id": "6791",
      "timestamp": "2026-11-21T13:56:56",
      "event": "customer:created",
      "via": "administration",
      "customer_id": "4560",
      "data": {
        "name": "Arnold Smith",
        "email": "a@smith.com",
        "company": "Big Business Corp."
      },
      "prefetch": {
         "customers": [
           {
             "id": "4560",
             "name": "Arnold Smith",
             "company": "Big Business Corp.",
             "email": "a@smith.com"
           }
         ]
       },
    },
    {
      "event_id": "6790",
      "timestamp": "2026-11-20T13:56:56",
      "event": "payment:created",
      "amount": 5.0,
      "method": "manual",
      "payment_id": "1186",
      "currency": "DKK",
      "invoice_type": "invoice",
      "invoice": 1004,
      "customer_id": "3256",
      "prefetch": {
         "customers": [
           {
             "id": "3256",
             "name": "Maggie Johnson",
             "company": "",
             "email": "maggie@example.com",
             "payments": [
               {
                 "id": "1186",
                 "amount": 5.0,
                 "currency": "DKK",
                 "business_entity": "TinyCorp"
               }
             ]
           }
         ]
       }
     }
  ]
}
```