---
updatedAt: 2026-10-16T08:11:00.482Z
---

Fetch the complete documentation index at: https://docs.avvio.xyz/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# List events

`GET https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/events`

Everything that has happened to your payouts, in order.

Reconcile from this feed. Each event is written once and never
changes, carries its own `id`, and `sequence` is a total order you cursor on, so "page forward from where I left off" is expressible, which
listing payouts cannot do: that is ordered by creation and can never
surface a change to one you have already read.

`payout.returned` is its own type rather than a flavour of
`payout.failed`, because a bank returning a settled payment days later is
the one event that reverses something you already booked.

**At-least-once: dedupe on `id`.** And the cursor is `sequence`, not a
timestamp: timestamps tie, and a tie is indistinguishable from a
boundary.

**The row is the webhook body.** `data` is the same object a delivery
carries, so the amounts, fee, rate, your `reference` and `endUserId`
are here, so you can book from the feed alone. `id` is the delivery's
`svix-id`, so a webhook is the trigger to read `GET /events?since=`
from the right place.

**Every family is here**, `type`-discriminated: `payout.*`,
`payout_batch.*` (with `batchId` set and `payoutId` null),
`payout_approval.*`, `webhook_endpoint.*` and `checkout_payment.*`
(whose `data` is the checkout payment: `fee` is a decimal string and
there is no `payoutId`). A reconciler that wants only payouts passes
`type=`; otherwise skip types it does not recognize.

**An event becomes readable about two seconds after it happens.** That
lag is what makes `since` safe against a write that commits out of
order.

## Parameters

- `orgId` (path, required) — The opaque organization id issued to you, normally CUID-shaped (for example `cmsx…`). It is not an `org_`-prefixed alias. Pass it unchanged in every organization-scoped path.
- `since` (query) — Return events after this `sequence`. Omit it on the first call (or send `0`) to start from the first row; afterwards feed back the page's `nextSince`.
- `payoutId` (query) — Everything that ever happened to one payout.
- `type` (query) — Comma-separated event types to include. Each must be a known type (see `PayoutEventType`); an unknown one is a `400 VALIDATION_ERROR`, never an empty page.
- `limit` (query) — Maximum events to return, from 1 to 500. Defaults to 100.

## Example

```bash
curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/events?since=43&type=payout.completed%2Cpayout.failed%2Cpayout.returned" \
  -H "x-api-key: $AVVIO_API_KEY"
```

## Responses

- `200` — Events, oldest first.
- `401` — The key was refused. Nothing ran. - `UNAUTHORIZED`: missing, invalid or revoked, or a key on a route that does not accept one. - `KEY_EXPIRED`: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated. - `KEY_IP_NOT_ALLOWED`: the key is pinned to source addresses and this request came from another.
- `403` — A valid key that may not make this call. Nothing ran. - `FORBIDDEN`: the key belongs to a different organization. - `ACCOUNT_BLOCKED`: API access for your organization is suspended, and every key is refused until we lift it. Contact support.
- `429` — Too many requests. The default ceiling is **100 requests per minute per API credential** on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies. Obey `Retry-After`; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same `Idempotency-Key`.

Machine contract: [partner-payouts.openapi.yaml](/partner-payouts.openapi.yaml), operation `listEvents`.