# BeeL. API changelog > Every change to the API that can affect an integration, newest first. Migration notes come first. ## Changelog - [Changelog](https://docs.beel.es/changelog.md): Every change to the BeeL. API, newest first — what moved, when the old way stops working, and how to tell whether it affects you. ## Migration notes - [Payments cleanup](https://docs.beel.es/changelog/payments-cleanup.md): Two never-documented payment-connection operations are retired today. On 11 December 2026 the event listing defaults to one row per money… - [external_reference is now external_ref](https://docs.beel.es/changelog/external-ref-rename.md): The invoice field first announced as external_reference is now called external_ref — the old name still works when you write, but responses… - [Resources under the NIF](https://docs.beel.es/changelog/resources-under-the-nif.md): An account can now hold several NIFs, each named in the path. The old flat routes are deprecated with a Sunset date and a successor … ## September 2026 - [Province is only required for addresses in Spain](https://docs.beel.es/changelog/province-optional-outside-spain.md): `province` is no longer required on an `Address` outside Spain: a foreign customer or inline recipient without one is accepted. A Spanish… - [Simplified invoice exchanges are recorded with VeriFactu](https://docs.beel.es/changelog/simplified-exchange-recorded-with-verifactu.md): With VeriFactu, exchanging simplified invoices now issues the full invoice and records it as `F3`. `SIMPLIFIED_EXCHANGE_NOT_RECORDABLE` now… - [The VeriFactu status webhook says whether it reports the registration or the…](https://docs.beel.es/changelog/verifactu-status-webhook-operation.md): `verifactu.status.updated` now carries `operation`: `REGISTRATION` or `VOID`. AEAT's answer to a cancellation reaches you by webhook… - [Corrective invoices and voids follow the rules of the law](https://docs.beel.es/changelog/correctives-and-voids-follow-the-law.md): A corrective can no longer rectify more than was invoiced, has a deadline, and can fix the recipient's data; a sent or paid invoice is… - [Series by type, and what AEAT would reject is refused before numbering](https://docs.beel.es/changelog/invoice-checks-before-numbering.md): A series numbers only its own type, and an invoice AEAT would reject answers `422` before a number is used. Zero-total invoices are… - [Exchange simplified invoices for a full invoice](https://docs.beel.es/changelog/simplified-invoice-exchange.md): A new operation issues a full invoice in exchange for simplified invoices when the customer asks for one with their details. With VeriFactu… - [Tax rates are judged by the operation date and the withholding by the issuer](https://docs.beel.es/changelog/tax-rates-by-date-and-issuer.md): Temporary VAT and surcharge rates only on operations of their period, `0.625` becomes `0.62`, companies cannot withhold individuals' IRPF… - [A new series needs its document type, and what else changes in this release](https://docs.beel.es/changelog/series-type-required-and-behaviour-changes.md): A new series needs `document_type`, several rejections now carry a specific code or status, and an issued invoice's PDF never changes. Plus… - [CLI 0.3.0: commands follow the routes under the NIF](https://docs.beel.es/changelog/cli-0-3-0.md): CLI 0.3.0 calls only the routes that name the company, so most commands change name: `beel companies list-invoices ` is now `beel invoices… - [Webhook retries now span about 3 days](https://docs.beel.es/changelog/webhook-retries-span-three-days.md): A failed webhook delivery is now retried 7 times over about 3 days instead of for about a minute, so a short outage of your endpoint no… - [A recurring template's history lists what did not happen too](https://docs.beel.es/changelog/recurring-history-every-entry.md): The history now includes failed runs, skipped periods and pauses, each with a `type`. For those entries `invoice_id` is `null`. - [A simplified invoice can no longer name an identified recipient](https://docs.beel.es/changelog/simplified-invoice-no-identified-recipient.md): Creating or updating a `SIMPLIFIED` invoice whose recipient has a NIF or an alternative identifier now answers `400… - [Where the contract and the API disagreed, they now agree](https://docs.beel.es/changelog/contract-and-api-realigned.md): A check of the published contract against the live API found a dozen differences. A few were fixed in the API, and the rest in the contract. - [Export lines take regime 02 on their own](https://docs.beel.es/changelog/export-lines-take-regime-02.md): A VAT line exempt under art. 21 or 22 that arrives with `regime_key: "01"` is stored with `"02"`, instead of being refused by AEAT after… - [Member grants carry the company's name](https://docs.beel.es/changelog/member-grants-company-name.md): Each grant in a member's response and in the grants list now carries `company_name` next to `company_id`, so you can name the company… - [A phone number in a response no longer promises the input rules](https://docs.beel.es/changelog/phone-in-responses.md): The contract stops declaring `minLength` and `pattern` on `phone` in responses; they move to `PhoneInput`. The server sends exactly what it… - [The VeriFactu records of an invoice, each with its own status](https://docs.beel.es/changelog/verifactu-records.md): `GET …/invoices/{invoice_id}/verifactu-records` lists the registration and, after a void, the cancellation — each with its own… - [chaining_hash leaves the documentation](https://docs.beel.es/changelog/chaining-hash-leaves-the-contract.md): `verifactu.chaining_hash` was declared but never sent, so it is being withdrawn. No response changes: the server behaves exactly as before. - [A customer used by a live recurring template cannot be deleted](https://docs.beel.es/changelog/customer-delete-blocked-by-recurring.md): Deleting a customer that an active or paused recurring template invoices is now rejected, on the single `DELETE` and row by row in the bulk… - [An OSS line keeps the destination country's VAT](https://docs.beel.es/changelog/oss-keeps-the-destination-vat.md): Our OSS examples set `percentage: 0`, which drops the destination VAT from the breakdown. The API never required it. Check your… - [A recurring template that emails its invoices needs someone to email](https://docs.beel.es/changelog/recurring-auto-send-needs-a-recipient.md): Saving a template with `send_automatically: true` and no recipient now answers `422 SIN_DESTINATARIO_RESOLUBLE`, and malformed recipient… - [Recurring templates say when they are failing, and which period they last…](https://docs.beel.es/changelog/recurring-is-failing-and-last-slot.md): `is_failing` flags a template from its first failed run, and `last_generated_scheduled_date` gives the latest period it has already… - [A recurring template cannot produce an invoice with a negative total](https://docs.beel.es/changelog/recurring-negative-totals-rejected.md): Negative line totals on a template, a generated invoice adding up below zero, and editing a draft to a negative total are now rejected. - [Discarding or resolving a payment event acts on the whole charge](https://docs.beel.es/changelog/payment-event-actions-cover-the-whole-charge.md): `discard`, `restore` and `resolve` on a payment event now also apply to the other events of the same charge: its failed attempts, its… - [Recurring templates: quarterly, yearly, and an invoice cap](https://docs.beel.es/changelog/recurring-invoices-cadence-and-cap.md): Templates gain quarterly and yearly cadences, an end after `max_invoices`, a `completion` reason, `draft_in_advance`, and the amount of the… - [Recurring writes reject what they used to swallow](https://docs.beel.es/changelog/recurring-writes-are-strict.md): Payment detail without a method, an inactive series, a window with no occurrence and a blank name are now rejected instead of silently… - [Stripe connections: faster correctives, disputes you can see, and exact amounts](https://docs.beel.es/changelog/stripe-refunds-disputes-and-shipping.md): A card refund gets its corrective at once, disputes and voided credit notes raise a review item, and correctives and shipping add up to the… - [Resuming a recurring template no longer re-invoices a period](https://docs.beel.es/changelog/resume-keeps-next-generation.md): Resuming keeps `next_generation` when it has not fallen due yet, instead of recalculating from today, which could issue a period twice or… - [The deprecated flat routes now retire on 9 December](https://docs.beel.es/changelog/flat-routes-retire-9-december.md): The retirement date of the deprecated flat routes moves from 10 September to 2026-12-09. Nothing stopped answering, and you have the whole… - [next_generation is null when there is no next invoice](https://docs.beel.es/changelog/next-generation-null.md): `next_generation` now carries only the date the system will honour, and `null` otherwise: a completed template, or a paused one whose date… - [Three response fields were never guaranteed](https://docs.beel.es/changelog/contract-drops-guarantees-it-never-had.md): `amount`, `currency` and `sending_history.sent_at` leave `required`. No response changes — the contract was promising something the server… - [A payment connection says which Stripe events it invoices](https://docs.beel.es/changelog/payment-connection-event-source.md): `event_source` (`PAYMENTS`, `INVOICES` or `BOTH`) picks which family of Stripe events a connection invoices. Existing connections are… - [New webhook event: invoice.pdf.generated](https://docs.beel.es/changelog/webhook-invoice-pdf-generated.md): `invoice.pdf.generated` tells you an invoice's PDF is stored and ready, so you can fetch it instead of polling. - [Clearer rejections, and updates that do not re-ask the census](https://docs.beel.es/changelog/clearer-rejections-and-cheaper-updates.md): A customer update only asks the AEAT census when the fiscal pair changes, the invitation `404` stops saying "pending", and readiness names… - [An import row without an address is a bad row](https://docs.beel.es/changelog/import-rows-without-address.md): A customer import row with an incomplete address is now reported as a bad row instead of being created with placeholder values. - [Payment connections are addressed by id](https://docs.beel.es/changelog/payment-connections-by-id.md): The `{provider}` path segment becomes `{connection_id}` on nine payment-connection paths. The old paths are gone, with no coexistence… - [Addresses can be missing, and accept more characters](https://docs.beel.es/changelog/addresses-can-be-missing.md): `issuer.address` is optional and is no longer filled with invented values, and one character set governs every address field. - [The API serves its own spec](https://docs.beel.es/changelog/openapi-spec-endpoint.md): `GET /v1/openapi.yaml` and `/v1/openapi.json` serve the public contract — the same document this reference is built from, no API key needed. - [The PDF download waits instead of asking you to poll](https://docs.beel.es/changelog/pdf-download-waits.md): `GET .../invoices/{id}/pdf` now waits for the PDF and answers `200`. `Prefer: wait=0` keeps the old pure polling behaviour. - [VeriFactu is a fact of the taxpayer, not a flag per invoice](https://docs.beel.es/changelog/verifactu-is-an-account-fact.md): Whether an invoice reaches the AEAT is now decided by the NIF's regime at issue time. The per-invoice flag and three response fields are… - [The street number is no longer required in an address](https://docs.beel.es/changelog/street-number-is-optional.md): `address.number` is now optional: omit it when the address has none, or when `street` already carries it. - [New webhook event: invoice.schedule_failed](https://docs.beel.es/changelog/webhook-invoice-schedule-failed.md): `invoice.schedule_failed` tells you a scheduled invoice could not be issued, so you find out without opening the dashboard. ## August 2026 - [A fully discounted line no longer kills the invoice](https://docs.beel.es/changelog/invoice-zero-amount.md): A line discounted to zero used to reject the whole invoice. Zero is now judged on the invoice total, with `INVOICE_ZERO_AMOUNT`. - [VeriFactu is always on in sandbox](https://docs.beel.es/changelog/verifactu-always-on-in-sandbox.md): A company created with a test key is born with VeriFactu on, and its NIF is registered on the first submission. Live is unchanged. - [Four collections paginate, and branding goes wrapped](https://docs.beel.es/changelog/collections-paginate-and-branding-wrapped.md): Four collections now paginate — without `limit` you get the first 20 — and the three branding responses come wrapped in `{success, data… - [The census is checked before the invoice is numbered](https://docs.beel.es/changelog/census-check-before-numbering.md): Issuing with VeriFactu on checks the recipient against the AEAT census first: an uncensused recipient answers `422`, and no number is spent. - [OAuth2 leaves the public contract](https://docs.beel.es/changelog/oauth2-out-of-the-contract.md): OAuth2 is gone from the spec. Each operation now states the scope it requires in its own description. API key auth is unchanged. - [Three filters returned the wrong rows](https://docs.beel.es/changelog/filters-that-were-silently-dropped.md): A literal `%` in a filter value dropped the filter. `series_code` matched any series containing the code. Sorting customers ignored the… - [Rate limits now count per IP](https://docs.beel.es/changelog/global-rate-limit.md): The published global ceiling drops to 1000 req/60 s to match what was already enforced. Strict and Global count per IP, not per credential. - [Request bodies limited to 2 MB](https://docs.beel.es/changelog/request-body-limits.md): Bodies above 2 MB answer `413 REQUEST_BODY_TOO_LARGE`. `411 LENGTH_REQUIRED` is gone — chunked encoding is accepted. - [Lost updates answer 409](https://docs.beel.es/changelog/concurrent-modification.md): Two overlapping updates: the second now answers `409 CONCURRENT_MODIFICATION` instead of silently discarding the first. - [Contract drops what was never sent](https://docs.beel.es/changelog/contract-declares-what-the-server-does.md): Several documented responses and one header were never actually sent. They are out of the contract; the server did not change. - [Breakdowns, series and schedules](https://docs.beel.es/changelog/invoicing-contract-detail.md): Tax breakdowns travel complete and add up. Series publish the next number they will assign. Recurring invoices declare `frequency` in the… - [Import managed accounts from a file](https://docs.beel.es/changelog/managed-account-imports.md): Create managed accounts in bulk from a spreadsheet — template, preview, apply — and see where each claim stands. - [Semantic rejections answer 422](https://docs.beel.es/changelog/semantic-rejections-are-422.md): A body that parses but breaks a rule now answers `422` with a code and populated `details`, not an empty `400`. - [Unknown query parameters rejected from 3 September](https://docs.beel.es/changelog/strict-query-parameters-and-rate-limits.md): From 2026-09-03 the flat routes reject an undeclared query parameter with `400` instead of ignoring it. Until then they answer `200` with a… - [Void cause on voided invoices](https://docs.beel.es/changelog/invoice-void-cause.md): Voided invoices now carry `void_cause`, `void_reason` and `voided_at`, so a direct void and a total corrective are told apart without a… - [One shape for lists and deletes](https://docs.beel.es/changelog/canonical-surface-consistency.md): Lists answer `data.`, deletes answer `204` unless the body informs, and every create returns `Location`. `DELETE products/bulk` takes… - [A webhook URL on a private network is rejected when you register it](https://docs.beel.es/changelog/webhook-private-urls-rejected.md): Registering or changing a subscription URL that points to a private or internal network address now answers `422 URL_TARGET_NOT_ALLOWED`… - [Webhook subscriptions report their health, and pause when the endpoint is dead](https://docs.beel.es/changelog/webhook-endpoint-health.md): A subscription now says how its endpoint is doing, emails you when it keeps failing, and is paused after 25 failed deliveries over more… - [Filter invoices by several statuses](https://docs.beel.es/changelog/multi-status-invoice-filter.md): The `status` filter on `GET /v1/invoices` accepts a comma-separated list, so one request covers several statuses. ## July 2026 - [external_reference on invoices](https://docs.beel.es/changelog/invoice-external-reference.md): Invoices accept an `external_reference` — your own order id — that you can filter by and that is enforced as unique. - [Disbursements (suplidos): pass-through payments](https://docs.beel.es/changelog/suplidos.md): Invoice lines carry a `line_type`. Set `SUPLIDO` to pass through amounts paid in your client’s name, outside the taxable base. ## June 2026 - [Read your API request logs](https://docs.beel.es/changelog/request-logs.md): A Request Logs endpoint family lets you inspect what your own API keys have called — method, path, status, timing and the full detail. - [BeeL. CLI](https://docs.beel.es/changelog/cli.md): Official CLI on npm as `@beel_es/cli`. Run any endpoint from the terminal, sandbox by default, nothing to install. - [Node.js / TypeScript SDK](https://docs.beel.es/changelog/node-sdk.md): Official Node.js / TypeScript SDK on npm as `@beel_es/sdk`, fully typed from the spec. - [v1.3.0 — contract fixes](https://docs.beel.es/changelog/v1-3-0.md): Idempotency keys accept any string, `country` becomes optional, and webhook URLs must be HTTPS. - [Active-company header renamed](https://docs.beel.es/changelog/active-company-header.md): The header that selects the active company is now `Beel-Active-Company`, was `X-Active-Profile`. ## May 2026 - [v1.2.0 — VeriFactu validation pack](https://docs.beel.es/changelog/v1-2-0.md): Invalid fiscal combinations now fail at request time with specific `422`s. Adds a public error-code catalog, metadata filters, the RD-ley… - [v1.1.0 — recipient and payment_info](https://docs.beel.es/changelog/v1-1-0.md): Invoice `recipient` and `payment_info` become structured objects, and new series get sensible defaults. ## April 2026 - [v1.0.3 — exemptions and document types](https://docs.beel.es/changelog/v1-0-3.md): VeriFactu exemptions and document types, plus stricter validation on fiscal fields. ## March 2026 - [v1.0.1 — operation_date](https://docs.beel.es/changelog/v1-0-1.md): `issue_date` is now always today, and a new `operation_date` carries the date the service was actually rendered. - [BeeL. API v1.0 — public launch](https://docs.beel.es/changelog/api-launch.md): The BeeL. API is publicly available: invoicing, customers, products, tax configuration and VeriFactu, with a 7-day trial.