> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Events (REST)

> List and retrieve events, and recover missed events with helper utilities.

## Overview

Use Events API for historical lookup and recovery workflows.

## Authentication

Uses merchant auth (API key, commerce API key, or bearer JWT depending on scope).

## Request

### List events

```ts theme={null}
const events = await pepay.events.list({ limit: 25 });
```

### Retrieve a single event

```ts theme={null}
const event = await pepay.events.retrieve('evt_123');
```

### Recover events since a cursor (helper)

```ts theme={null}
const missed = await pepay.events.recoverSince('evt_1700000000000-123', { limit: 50 });
```

## Response

Example event (event\_v1 envelope):

```json theme={null}
{
  "id": "evt_1734780000000-123",
  "object": "event",
  "api_version": "2025-12-16",
  "created": 1734780000,
  "type": "invoice.updated",
  "livemode": false,
  "pending_webhooks": 0,
  "data": {
    "object": {
      "object": "invoice",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "paid",
      "invoice_type": "standard",
      "environment": "devnet"
    }
  }
}
```

## Errors

* `401` missing/invalid auth headers
* `400` invalid filters/cursors
* `404` event not found (retrieve)

## Examples

* Use `recoverSince` after reconnecting a websocket stream to backfill missed events and return them in chronological order.

Next: [WebSockets (merchant)](/sdk/merchants/websockets)