> ## 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

> Events API endpoints for listing and retrieving events.

## Overview

Events provide an audit trail of activity (payments, invoices, commerce order updates, etc.). Use these endpoints when you need to:

* backfill history
* build dashboards/reconciliation tools
* debug an integration

## Authentication

Events can be accessed with:

* `x-api-key: pk_...` (merchant scope)
* `x-commerce-api-key: ck_...` (commerce scope)

## Request

Endpoints:

* `GET /api/v1/events`
* `GET /api/v1/events/{eventId}`

Example (list):

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/v1/events?limit=1" \
  -H "x-api-key: pk_..."
```

## Response

Representative event list response:

```json theme={null}
{
  "success": true,
  "data": {
    "object": "list",
    "data": [
      {
        "id": "evt_1700000000000-123",
        "object": "event",
        "api_version": "2025-12-16",
        "type": "invoice.paid",
        "created": 1700000000,
        "data": {
          "object": {
            "object": "invoice",
            "id": "550e8400-e29b-41d4-a716-446655440000"
          }
        }
      }
    ],
    "has_more": false
  }
}
```

## Errors

* `401/403` missing/invalid auth
* `400` invalid pagination parameters

## Examples

Use Events for historical backfills; for realtime delivery, prefer [WebSockets](/api-spec/realtime/websockets) or webhook delivery (Commerce).

Next: [Commerce overview](/api-spec/commerce/overview)