# Payments cleanup

Two never-documented payment-connection operations are retired today. On 11 December 2026 the event listing defaults to one row per money movement, and three `counts` fields and four schema aliases go with it — here's what changes, when, and how to tell whether it affects you.

**What's new: the payment area of the contract is smaller and says less
twice.** Two operations that no SDK, MCP tool, n8n node or integrator ever
called are gone as of today. Everything else in
[payment connections](/multi-nif/payment-connections) and payment events keeps
answering exactly as before, and **no operation is deprecated**.

What *is* announced is one change of default and a handful of fields and
aliases that nothing reads. They retire on **11 December 2026**, and the API
tells you so from today through the `Deprecation`, `Sunset` and `Link` headers
described below.

## Retired today

Both operations were added on 4 September 2026. They appeared in this
auto-generated reference between 7 and 12 September, and nowhere else — not in
the Node SDK, the MCP server, the n8n node, the CLI or any guide — and in those
days no request reached them. Nothing called them, so they go without a grace
period.

| Operation | Route | Answers now |
|---|---|---|
| `getCompanyPaymentConnection` | `GET /v1/companies/{company_id}/payment-connections/{connection_id}` | `405 Method Not Allowed` — the route stays for `PATCH` and `DELETE` |
| `reactivateCompanyPaymentConnection` | `POST /v1/companies/{company_id}/payment-connections/{connection_id}/reactivations` | `404 Not Found` |

Everything the `GET` returned is in the response of
`PATCH …/payment-connections/{connection_id}`; an empty `PATCH` body reads the
connection without changing it. The error codes only the reactivation emitted —
`CONNECTION_ALREADY_ACTIVE`, `CONNECTION_DEAUTHORIZED` and
`CONNECTION_PROVIDER_UNAVAILABLE` — leave the catalogue with it.

<Callout type="info">
  **Bringing a disconnected connection back** is done the way it was first
  connected: open a new authorization with
  `POST …/payment-connections/authorizations` (or from the BeeL dashboard) and
  let the holder authorize the provider again. Reactivating without a fresh
  OAuth authorization was never used by the dashboard or by any integrator.
</Callout>

## What retires on 11 December 2026

Nothing below stops working before that date. Until then the contract marks
each item `deprecated: true` with the same date and a link back to this page.

| What | Where | What to do |
|---|---|---|
| **The default of `charges_only`** — today `false`, one row per provider event | Query parameter of `GET …/payment-connections/{connection_id}/events` | On that day, omitting the parameter reads as `charges_only=true`: one row per money movement. **Send the value you want explicitly**, whichever it is. The parameter itself is not deprecated. |
| `counts.needs_action` | Field of the event listing | Filter with `needs_action=true` and read `pagination.total_items`. |
| `counts.ignored` | Field of the event listing | The closest surviving figure is `counts.by_status.SKIPPED`. |
| `counts.by_failure_reason` | Field of the event listing (deprecated since 10 September) | Read `counts.failure_reasons`: the same counts, plus the reason written out in the language of the request. |
| `RetryManagedPaymentEventResponse`, `ResolveManagedPaymentEventResponse`, `DiscardManagedPaymentEventResponse`, `RestoreManagedPaymentEventResponse` | Schema aliases in generated clients | Use `ManagedPaymentEventResponse`. The aliases always had the same shape; only the type name goes. |

## Does this affect you?

- **Grep your integration for `/events` under `/payment-connections/`** and
  check whether each call sends `charges_only`. A call that omits it changes
  shape on 11 December: it will get one row per money movement instead of one
  per event, and `pagination.total_items`, `counts.total`, `counts.discarded`,
  `counts.needs_action` and `counts.by_status` will describe movements rather
  than events. Add `charges_only=false` to keep today's view, or
  `charges_only=true` to adopt the new one now.
- **Watch your responses.** From today, a request to that listing that omits
  `charges_only` answers with:

  ```http
  Deprecation: true
  Sunset: Fri, 11 Dec 2026 00:00:00 GMT
  Link: <https://docs.beel.es/changelog/payments-cleanup>; rel="deprecation"
  ```

  A request that sends `charges_only` — `true` or `false` — gets none of them:
  you have already chosen. Log the headers for a week and you have the exact
  list of calls left to touch.
- **Grep for `by_failure_reason`, `counts.ignored` and `counts.needs_action`**
  in whatever reads the listing. Each has a replacement in the table above.
- **Regenerate your client** if you rely on the `*ManagedPaymentEventResponse`
  alias type names; the generated types for those routes are
  `ManagedPaymentEventResponse` already.

## The retirement calendar

| Phase | What happens |
|---|---|
| **Today** | The two operations above answer `405` / `404`. Everything else answers as before. Requests that omit `charges_only` carry `Deprecation`, `Sunset` and `Link`. |
| **Until 11 December 2026** | `charges_only` keeps defaulting to `false`; `counts.ignored`, `counts.needs_action` and `counts.by_failure_reason` keep being returned; the aliases stay in the contract. |
| **11 December 2026** | Omitting `charges_only` reads as `true`. The three `counts` fields and the four aliases leave the contract. |

<Callout type="warn">
  The change of default is the one that alters a response you may already be
  parsing without touching a line of your code. If you list payment events and
  do not send `charges_only`, decide which view you want and send it before
  the date.
</Callout>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi