Resources under the NIF

What's new: an account can now hold several NIFs. A fiscal identity is no longer inferred from your credential — you name it in the path, so one account can invoice under many NIFs. That's the model documented in Multi-NIF and Companies; this note is the API side of it.

Each resource now lives under the axis it belongs to: business resources under the NIF (/v1/companies/{company_id}), account-wide ones under the account (/v1/accounts/{account_id}), the shared catalogues at the top level, and your preferred language on /v1/me. The full move is in the route table below.

Nothing breaks today. The old flat routes are deprecated, not removed: each keeps answering and now carries Deprecation: true, a Sunset date and, where one is declared, a Link to its successor. Three routes deliberately have none — the PUTs that replace a customer, a product or a recurring invoice — and the contract says so instead of pointing you at something that behaves differently. They all retire on 10 September 2026 — migrate on your own schedule until then.

What breaks

Five changes need more than a new path — a mechanical find-and-replace gets each of them wrong:

• GET /v1/products/search is the one trap. Its successor is GET /v1/companies/{company_id}/products, which takes the same query filter but answers a different shape: the old route returned data: [ … ], the successor returns data: { products, pagination }. Swapping the path without reading the schema leaves you mapping over an object.
• The PUTs that really replace have no successor, on purpose. PUT /v1/customers/{customer_id}, PUT /v1/products/{product_id} and PUT /v1/recurring-invoices/{recurring_invoice_id} replace the whole resource: a field you leave out is cleared. The canonical form has a single update verb, PATCH, and it merges — so it is not a drop-in destination. The contract marks these three x-no-successor, and the API sends them no Link: rel="successor-version", precisely so that nobody migrates them blind. Moving one of them to the company-scoped PATCH changes what your call does, from replacing to merging: go through those call sites by hand, and where you relied on replacement send the resource complete, passing null in every field you want cleared. Their PATCH siblings — which already existed on the flat routes — are the ones with a clean 1:1 successor.
• PUT /v1/invoices/{invoice_id} is the exception, and it costs you nothing. It is the only PUT here with a declared successor, PATCH /v1/companies/{company_id}/invoices/{invoice_id}, and it earns it: this route never replaced the invoice. It applied only the fields present in the body and left the rest as they were — exactly what the successor does. The verb was the lie, not the behaviour. Change route and verb, keep the body, and the result is the same as before.
• Action verbs converged onto status. mark-paid, mark-sent and revert-to-issued all become PUT /v1/companies/{company_id}/invoices/{invoice_id}/status with the target status in the body; pause and resume do the same for recurring invoices. The old path is gone from the successor — the state you want is now data, not a URL.
• The four /v1/invoices/bulk/* routes split by intent into pdf-archive, deliveries, batches and exports, each with its own request and response. There is no single successor to find-and-replace them onto.

Does this affect you?

• Grep your integration for /v1/invoices, /v1/customers, /v1/products, /v1/recurring-invoices, /v1/configuration/, /v1/webhooks, /v1/emails and /v1/developers/request-logs. Every hit is a deprecated route, and the table below gives its successor — or says it has none.
• Watch your responses: a deprecated route answers with Deprecation: true, a Sunset date and, when a successor is declared, Link: <successor>; rel="successor-version". Log those headers for a week and you have the exact list of calls left to migrate, with no guessing — and a deprecated route arriving without the Link is one of the three replacing PUTs, which you have to move by hand.
• Check whether you send the BeeL-Active-Company header. Only the flat routes read it; once the NIF is in the path, the header plays no part.

The retirement calendar

The deprecated routes retire on 10 September 2026 — about a month from now. One speed, with a grace period on every route until then.

Find your route

Every route this release touched, grouped by resource. All 82 keep answering and carry Deprecation and Sunset, and all but the three replacing PUTs also carry Link: <successor>; rel="successor-version" — migrate before the date Sunset announces. Both columns show the route in full. Where the Now cell leads with a method, the method changed too, and a path-only find-and-replace leaves you calling a verb the successor does not serve. Read the note on those rows before you move them: PUT becoming PATCH is harmless on invoices and a change of behaviour on customers, products and recurring invoices.

Invoices

Configuration

Recurring invoices

Customers

Products

Webhooks

Emails

Request logs

Hand it to Claude Code

Migrate my BeeL. API integration to the per-NIF routes.

First, read https://docs.beel.es/api/changelog and find the entry whose slug is
"resources-under-the-nif". Treat its `routeMigration` groups as the authoritative
old-to-new mapping, and its `breakingChanges` as the list of changes that a
find-and-replace will get wrong.

Then find every BeeL. API call in this codebase and report, before editing anything:

1. Each call to a DEPRECATED route — give me the successor and the Sunset date
   read from the response headers.
2. Calls that need more than a new path: a different HTTP verb (PUT becoming
   PATCH), a different request body, or a different response shape.

Propose a diff for (1). For (2), show me each call site and stop for my review —
do not rewrite them automatically.

Finally, tell me which of my calls need no change at all, so I know the scope.

See also

• Multi-NIF — the model behind the axis: one account, many fiscal identities.
• Companies — creating and addressing each NIF.
• Payment connections — Stripe per NIF.
• Managed accounts — issuing on behalf of another account.
• VeriFactu auto-submit — what changes for fiscal submission per NIF.
• Node/TypeScript SDK — the official typed client, generated from this contract, so it targets the per-NIF routes.