> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Events

> The Events API provides a read-only audit trail of everything that happens in your account. Use it to inspect event history, debug webhook delivery issues, and build event timelines for individual entities.

Events are automatically generated whenever a state change occurs in PaymentKit — when an invoice is paid, a subscription is created, or a customer is updated. They are the same events that drive webhook delivery.

# Event object

Each event captures a single state change. An event always belongs to one entity (`aggregate_id`) and carries a full snapshot of the entity's state before and after the change.

| Field            | Type           | Description                                                                       |
| ---------------- | -------------- | --------------------------------------------------------------------------------- |
| `id`             | string         | Unique event identifier (e.g., `evt_prod_a1b2c3d4e5f6g7h8`)                       |
| `type`           | string         | Event type (e.g., `invoice.paid`, `customer.subscription.created`)                |
| `aggregate_type` | string         | Entity type the event belongs to (e.g., `invoice`, `subscription`, `customer`)    |
| `aggregate_id`   | string         | External ID of the entity this event relates to                                   |
| `data`           | object         | Full entity state after the change                                                |
| `previous_data`  | object \| null | Full entity state before the change; `null` for create events                     |
| `metadata`       | object         | Additional event-specific metadata                                                |
| `correlation_id` | string \| null | Request correlation ID for distributed tracing                                    |
| `version`        | integer        | Schema version for event format evolution                                         |
| `created`        | datetime       | When the event occurred (ISO 8601)                                                |
| `actor_type`     | string \| null | Type of actor who triggered the event: `user`, `api_key`, `system`, or `customer` |
| `actor_id`       | string \| null | External ID of the actor who triggered the event                                  |

```json
{
  "id": "evt_prod_a1b2c3d4e5f6g7h8",
  "type": "invoice.paid",
  "aggregate_type": "invoice",
  "aggregate_id": "in_prod_a1b2c3d4e5f6g7h8",
  "data": {
    "id": "in_prod_a1b2c3d4e5f6g7h8",
    "status": "paid",
    "currency": "usd",
    "total_amount_atom": 290000,
    "due_amount_atom": 0,
    "paid_amount_atom": 290000
  },
  "previous_data": {
    "id": "in_prod_a1b2c3d4e5f6g7h8",
    "status": "open",
    "currency": "usd",
    "total_amount_atom": 290000,
    "due_amount_atom": 290000,
    "paid_amount_atom": 0
  },
  "metadata": {},
  "correlation_id": "req_a1b2c3d4",
  "version": 1,
  "created": "2024-01-01T00:00:00Z",
  "actor_type": "system",
  "actor_id": null
}
```

Both `data` and `previous_data` contain the full entity state at the time of the event. `previous_data` is `null` for create events.

# List events

Retrieve a paginated list of events for your account. Results are ordered by `created` descending (newest first).

```bash
curl https://api.paymentkit.com/api/{account_id}/events \
  -H "Authorization: Bearer st_prod_..."
```

## Filters

Use query parameters to narrow results:

| Parameter        | Type   | Description                                                        |
| ---------------- | ------ | ------------------------------------------------------------------ |
| `event_id`       | string | Fetch a specific event by its ID                                   |
| `aggregate_id`   | string | Show all events for a specific entity (e.g., invoice timeline)     |
| `aggregate_type` | string | Show events for a type of entity (e.g., `invoice`, `subscription`) |
| `event_type`     | string | Show events of a specific type (e.g., `invoice.paid`)              |

Results are ordered by `created_at` descending (newest first).

```bash
# All events for a specific invoice
curl "https://api.paymentkit.com/api/{account_id}/events?aggregate_id=in_prod_a1b2c3d4e5f6g7h8" \
  -H "Authorization: Bearer st_prod_..."

# All subscription events
curl "https://api.paymentkit.com/api/{account_id}/events?aggregate_type=subscription" \
  -H "Authorization: Bearer st_prod_..."

# All invoice.paid events
curl "https://api.paymentkit.com/api/{account_id}/events?event_type=invoice.paid" \
  -H "Authorization: Bearer st_prod_..."
```

# Get an event

Retrieve a single event by its ID.

```bash
curl https://api.paymentkit.com/api/{account_id}/events/evt_prod_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer st_prod_..."
```

Returns the full [Event object](#event-object), or `404` if not found.

# Event deliveries

Events are delivered to your webhook endpoints asynchronously. The delivery endpoints let you inspect the delivery status of any event across all your configured endpoints.

## Delivery object

| Field                  | Type             | Description                                                        |
| ---------------------- | ---------------- | ------------------------------------------------------------------ |
| `id`                   | string           | Unique delivery identifier (e.g., `ed_prod_a1b2c3d4e5f6g7h8`)      |
| `event_id`             | string           | ID of the event being delivered                                    |
| `webhook_endpoint_id`  | string           | ID of the target webhook endpoint                                  |
| `webhook_endpoint_url` | string \| null   | URL of the target webhook endpoint                                 |
| `status`               | string           | Delivery status: `pending`, `delivering`, `delivered`, or `failed` |
| `attempt_count`        | integer          | Number of delivery attempts made so far                            |
| `last_attempt_at`      | datetime \| null | When the most recent delivery attempt occurred                     |
| `delivered_at`         | datetime \| null | When the event was successfully acknowledged (2xx response)        |
| `next_retry_at`        | datetime \| null | When the next retry will be attempted; `null` if not scheduled     |
| `response_status`      | integer \| null  | HTTP status code returned by your endpoint                         |
| `error`                | string \| null   | Error message if the last attempt failed                           |
| `created`              | datetime         | When this delivery record was created                              |

## List deliveries for an event

Returns all webhook delivery records for a specific event — one record per subscribed webhook endpoint.

```bash
curl https://api.paymentkit.com/api/{account_id}/events/evt_prod_a1b2c3d4e5f6g7h8/deliveries \
  -H "Authorization: Bearer st_prod_..."
```

```json
[
  {
    "id": "ed_prod_a1b2c3d4e5f6g7h8",
    "event_id": "evt_prod_a1b2c3d4e5f6g7h8",
    "webhook_endpoint_id": "whe_prod_a1b2c3d4e5f6g7h8",
    "webhook_endpoint_url": "https://your-server.com/webhooks",
    "status": "delivered",
    "attempt_count": 1,
    "last_attempt_at": "2024-01-01T00:00:05Z",
    "delivered_at": "2024-01-01T00:00:05Z",
    "next_retry_at": null,
    "response_status": 200,
    "error": null,
    "created": "2024-01-01T00:00:00Z"
  }
]
```

## Get event with deliveries

Retrieve an event together with all its delivery records in a single request, instead of calling the event and deliveries endpoints separately.

```bash
curl https://api.paymentkit.com/api/{account_id}/events/evt_prod_a1b2c3d4e5f6g7h8/full \
  -H "Authorization: Bearer st_prod_..."
```

```json
{
  "event": {
    "id": "evt_prod_a1b2c3d4e5f6g7h8",
    "type": "invoice.paid",
    "aggregate_type": "invoice",
    "aggregate_id": "in_prod_a1b2c3d4e5f6g7h8",
    "data": { ... },
    "previous_data": { ... },
    "metadata": {},
    "correlation_id": "req_a1b2c3d4",
    "version": 1,
    "created": "2024-01-01T00:00:00Z",
    "actor_type": "system",
    "actor_id": null
  },
  "deliveries": [
    {
      "id": "ed_prod_a1b2c3d4e5f6g7h8",
      "event_id": "evt_prod_a1b2c3d4e5f6g7h8",
      "webhook_endpoint_id": "whe_prod_a1b2c3d4e5f6g7h8",
      "webhook_endpoint_url": "https://your-server.com/webhooks",
      "status": "delivered",
      "attempt_count": 1,
      "last_attempt_at": "2024-01-01T00:00:05Z",
      "delivered_at": "2024-01-01T00:00:05Z",
      "next_retry_at": null,
      "response_status": 200,
      "error": null,
      "created": "2024-01-01T00:00:00Z"
    }
  ]
}
```

Use `/full` when debugging a specific event — it gives you the full event payload and all delivery outcomes in one request.