beel_list_payment_events
Read-onlyIdempotent
Lists payment events for a company's payment connection, newest first, to audit charges that produced invoices and find those that did not.
Instructions
Lists the payment events received through the payment provider connection of a NIF (company), most recent first. Use it to audit the charges that produced an invoice and to find the ones that did not.
By default, every event is listed. Nothing is hidden: events the connection skipped, duplicates and disputes are all returned. Narrow the list with the filters below; what you do not filter, you get. Set
charges_only=trueto read the same events as one row per money movement instead.Scope: events belong to the connection, not to the NIF directly. The
{connection_id}segment picks one connection of the NIF in the path, and only the events of that connection are returned; an event of another NIF of the same account is never reachable from here.Unknown connection: a
{connection_id}that belongs to no connection of this NIF returns404.
Endpoint: GET /v1/companies/{company_id}/payment-connections/{connection_id}/events
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text search over the payer name and the provider identifiers of the charge (`pi_`, `ch_`, `cs_`, `evt_`). Case-insensitive, partial matches allowed. The payer email is deliberately not searchable. | |
| to | No | Keep only the events received at or before this instant. | |
| from | No | Keep only the events received at or after this instant. | |
| page | No | Page number, starting at 1. The response echoes it back as `pagination.current_page`. | |
| limit | No | How many items to return per page. The response echoes it back as `pagination.items_per_page`. | |
| status | No | Keep only the events in these processing states. Repeat the parameter to combine states; omit it, or send it empty (`status=`), for all of them. | |
| company_id | Yes | Unique identifier (UUID) of the company the events belong to — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed. | |
| event_kind | No | Keep only the events of these kinds. Matches `event_kind`, never `event_type`: the kind is what the event is about, while `event_type` is the raw name the provider emitted (`payment_intent.succeeded`) and is not filterable. `UNKNOWN` keeps every event whose provider name we do not classify. Repeat the parameter to combine kinds. An empty value (`event_kind=`) is the same as omitting it. | |
| max_amount | No | Keep only the events whose `amount` is at or below this value. | |
| min_amount | No | Keep only the events whose `amount` is at or above this value. | |
| charges_only | No | Return one row per money movement instead of one row per event. Today, when this parameter is omitted or `false`, every event is listed. **The default changes on 11 December 2026.** From that day, omitting this parameter reads the listing as `charges_only=true` — one row per money movement. Until then a request that omits it answers with `Deprecation`, `Sunset` and `Link` headers. Send the value you want explicitly, whichever it is, so the change of default cannot surprise you. See the [migration guide](https://docs.beel.es/changelog/payments-cleanup). A money movement is a sale, a failed payment, each refund and each dispute. The provider usually reports a single movement through several events. When this parameter is `true`, each movement is returned in at most two rows: its outcome and, when any of its events requires action, its incident. The outcome row stands for the events of the movement that require no action; the incident row stands for the events of the movement that require action, so an invoiced movement that still has something to resolve always shows it. Within each row, the event that produced an invoice comes first, then an event of a classified kind before an unclassified one, and then the most recent one. A sale and a failed payment of the same charge are two movements, and every refund and every dispute of a charge is a movement of its own; the opening and the closing of a dispute are the same movement. An event of an unclassified kind that requires action joins the incident row of the movement its identifier names: a charge joins its sale, a dispute joins that dispute, and a refund or a credit note joins that refund. An event whose identifier names no movement, or that carries no identifier at all, stays a row of its own and is never merged with another. Events that moved no money, such as a customer, a price or a product being created, are left out, except those that require action, which are always listed. Discarded events of a movement that is still listed through a live event are ignored: they are neither returned nor counted. A movement whose events are all discarded is returned as a single row, only when `include_discarded` is `true`, and counts once in `discarded`. Without other filters, the number of rows returned with `include_discarded=true` is therefore `total` plus `discarded`. The other filters narrow the rows returned and `pagination.total_items`, and nothing else. `counts` describes the whole connection in the view you asked for and disregards every other filter: with `charges_only=true`, its `total`, `discarded`, `needs_action` and `by_status` values count money movements rather than individual events, while its `ignored` and `failure_reasons` values keep counting events. A request that filters by `q` may therefore return a single row while `counts.total` still reports every movement of the connection. | |
| needs_action | No | `true` keeps only the events still worth acting on; `false`, only the ones that are not. Omit it for both. | |
| connection_id | Yes | Unique identifier (UUID) of the payment connection the operation acts on, as returned by `GET /v1/companies/{company_id}/payment-connections`. A NIF can hold several connections of the same provider, so the provider slug alone does not name one. A connection of another NIF answers `404`, exactly like one that does not exist. | |
| failure_reason | No | Keep only the events that did not complete for these reasons. Repeat the parameter to combine reasons. An empty value (`failure_reason=`) is the same as omitting it. | |
| failure_category | No | Keep only the events that did not complete for a cause in these categories. Repeat the parameter to combine categories. Events that completed carry no category and are therefore never kept by this filter. An empty value (`failure_category=`) is the same as omitting it. | |
| include_discarded | No | Include the events you discarded. They are excluded by default; discarding is a decision about the list, not a state of the event. |