NewConnections and customer replies to invoices
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog

Changelog

Every change to the BeeL. API, newest first — what moved, when the old way stops working, and how to tell whether it affects you.


Most changes are one entry here. A few are big enough to need the old-to-new route table, the retirement calendar and a way to check your own integration against it — those keep their entry in this list and link to the full note.

Every deprecated route also tells you the same thing in its own responses — Deprecation: true, a Sunset date and Link: <successor>; rel="successor-version" — so you never have to trust a page over your own traffic.

Improved

Recurring invoices: `series_id` is optional

Creating a recurring invoice without series_id no longer answers VALIDATION_ERROR: the template uses the company's default series for invoice_type. A STANDARD template with no default standard series is rejected with SERIES_DEFAULT_NOT_FOUND.

New

Invoices and emails without the BeeL. mark

With the branding removal add-on, available on Enterprise plans, PDFs generated from then on drop the "Generated with BeeL." footer and invoice emails drop the BeeL. mark.

Breaking
Breaking
Improved

NIF validation in sandbox answers with simulated data

In sandbox the NIF validation endpoint no longer queries the AEAT register. A well-formed NIF comes back VALID with the legal_name you sent, legal_name_verified: false and no census_status; a malformed one still comes back INVALID. With a Live key nothing changes. Only this endpoint is simulated: creating a company or a customer, and issuing, still check the NIF against the real AEAT census in sandbox.

  • POST/v1/nif/validateSimulated in sandbox (test keys and the MCP server connected to Test)
Improved

Company stats count voided invoices by how they were voided

The documents counted by invoice_count in the company stats change for voided invoices. Drafts, scheduled invoices and proformas still never count, and a corrective still counts as a document of its own.

  • Do not count: an invoice voided with the void endpoint (issued by mistake), a simplified invoice replaced by a standard one, and any corrective of an invoice voided that way.
  • Count: an invoice voided by a total corrective keeps counting, together with that corrective, so the pair counts as two.
  • Still not a cursor. Voiding an invoice lowers the count and rectifying one for its full amount raises it by one. last_invoice_at follows the same set and can move backwards.
  • GET/v1/accounts/{account_id}/companies/statsNew rule for invoice_count and last_invoice_at
New

Exports add a Suplidos sheet for disbursements

The sheet goes at the end of the workbook, after the sheets of the formats you asked for. Columns: «Número factura», «Fecha expedición», «Cliente», «NIF cliente», «Factura origen», «NIF emisor origen» and «Importe factura origen». The amount is the total_to_pay of the source invoice, or the line total for a manual disbursement with no linked invoice.

  • It is not a format. It is added whatever formats you send, and you cannot request it or opt out of it. Code that reads sheets by position is unaffected; code that expects a fixed number of sheets may need a change.
  • A source invoice you cannot see shows only its number, when known, with the issuer NIF and amount empty.
  • POST/v1/companies/{company_id}/invoices/exportsAdds the Suplidos sheet when there are disbursement lines
Breaking

The invoice list date range uses the operation date when there is one

Before, date_from and date_to always matched the issue date. Now they match the operation date (operation_date) of invoices that have one, and the issue date of the rest. Both bounds stay inclusive.

  • Who notices: anyone issuing invoices whose operation date falls in a different period from the issue date. Those invoices now appear in the range of their operation date.
  • Exports are not affected: the filters.date_from and filters.date_to of an export still match the issue date.
  • GET/v1/companies/{company_id}/invoicesdate_from / date_to match the operation date when set
  • GET/v1/invoicesSame change on the deprecated route
Improved

Sorting by invoice number is numeric, and payment_date survives a correction

Small corrections to the invoice list and the invoice resource.

  • sort_by=invoice_number sorts by series code and then by the number within the series, compared numerically. Ties on any sort field are broken by series code, then number, then id, in the requested direction, so pages are stable.
  • payment_date is present once a payment has been recorded and stays through later status changes (RECTIFIED, VOIDED). Before, the contract said it only appeared on PAID invoices.
  • GET/v1/companies/{company_id}/invoicesNumeric order for invoice_number and a stable tie-break
Breaking

Unpaid invoices past their due date now move to OVERDUE

OVERDUE was already in the status enum, but nothing ever set it: an unpaid invoice past its due date kept ISSUED or SENT. Now a daily process moves it to OVERDUE. It applies to unpaid ISSUED or SENT invoices with a total above zero whose due_date is earlier than the current day in Europe/Madrid, including invoices issued before this change.

  • A filter on status=SENT or status=ISSUED returns fewer invoices. The overdue ones now carry OVERDUE. To list everything still waiting for payment, use the new pending_collection_only=true filter instead of a list of statuses.
  • No webhook is sent when an invoice becomes OVERDUE. Read the status from the invoice or the list.
  • It can lag behind the due date, because the process runs once a day. Marking the invoice paid moves it to PAID as before.
  • What to do: if your code treats an unknown status as an error, or maps statuses to your own, add OVERDUE.
  • GET/v1/companies/{company_id}/invoicesOverdue invoices come back with status: OVERDUE
New

Filter invoices pending collection

The company invoice list accepts pending_collection_only. With true it returns only STANDARD, SIMPLIFIED or CORRECTIVE invoices in ISSUED, SENT, OVERDUE or RECTIFIED with no payment_date. A corrective invoice whose original is VOIDED and unpaid is left out, because nothing is owed or refunded for that pair; if the original was paid, the corrective is included.

  • It combines with the other filters, so a status or type outside that set returns an empty list.
  • false, the default, does not filter. Existing requests are unchanged.
  • GET/v1/companies/{company_id}/invoicesNew query parameter pending_collection_only
Breaking

VeriFactu records accepted with errors get their own status: ACCEPTED_WITH_ERRORS

Until now a record the AEAT accepted while reporting errors in it was published as ACCEPTED, with an error_code alongside. It now has its own value, ACCEPTED_WITH_ERRORS, and ACCEPTED means accepted without remarks. This applies to records accepted before this change too.

  • verifactu_status=ACCEPTED returns fewer invoices: the ones accepted with errors match ACCEPTED_WITH_ERRORS.
  • verifactu.status.updated can carry ACCEPTED_WITH_ERRORS in new_status and previous_status. The record stands at the AEAT and its QR is valid, but the flagged data must be reviewed.
  • error_code is now described once, as VeriFactuErrorCode. It is still a string: the AEAT's numeric code (for example 1105) or a BeeL. code such as RECIPIENT_VAT_NOT_IN_VIES when the submission was refused before reaching the AEAT. Generated clients may get a new type name.
  • What to do: if you validate the status against a closed enum, add ACCEPTED_WITH_ERRORS and treat any value you do not recognise as unknown, since more may be added.
  • GET/v1/companies/{company_id}/invoicesverifactu_status accepts ACCEPTED_WITH_ERRORS
  • GET/v1/companies/{company_id}/invoices/{invoice_id}verifactu.submission_status can be ACCEPTED_WITH_ERRORS
Improved

The VeriFactu status webhook reports a new rejection reason and the real previous status

Two changes to verifactu.status.updated. The payload keeps its shape.

  • A new reason for a rejection sends a webhook. While a record stays REJECTED, a different error_code or public error_message now triggers a delivery with previous_status and new_status both REJECTED. Handlers that assume the status always changes should accept this case.
  • previous_status follows the invoice, not only the record. It is the status of the invoice's record of the same operation just before the change, also when a new submission replaces a rejected one. It is omitted only on the first notification of each operation, so the first notification of a cancellation still has no previous_status.
Improved

Stripe: a buyer with a NIF always gets a standard invoice, and the simplified threshold is deprecated

Three changes to how a connected Stripe account is invoiced. None of them changes an invoice that already exists, and no request or response changes shape.

  • A buyer with a NIF (or foreign identifier) and a complete address always receives a STANDARD invoice, whatever the amount. Before, a charge below the connection's threshold was issued as SIMPLIFIED, which never carries the buyer's NIF. Without that data the charge still gets a SIMPLIFIED invoice up to 3 000 €.
  • A charge that cannot be invoiced is saved as a draft instead of waiting as a skipped event: a charge above 3 000 € whose buyer has no NIF or address, and a charge whose NIF the AEAT definitively rejects. The draft appears in Needs attention, and on Live connections BeeL. emails the issuer. Complete the recipient and issue it.
  • simplificada_threshold is deprecated. The API still accepts and returns it, with the same validation, but its value no longer affects the invoice type. You can stop sending it.
  • What to do: nothing is required. If you relied on the threshold to keep small sales to identified buyers as simplified invoices, those sales are now standard invoices. To avoid drafts, collect tax IDs and the full billing address in Stripe.
  • GET/v1/companies/{company_id}/payment-connectionssimplificada_threshold is returned but deprecated and ignored
  • PATCH/v1/companies/{company_id}/payment-connections/{connection_id}simplificada_threshold is still accepted but deprecated and ignored
Improved

Stripe: manual 0 % rates and the buyer's country on paid invoices

Two changes to how a connected Stripe account is invoiced. Neither one changes an invoice that already exists.

  • A manual 0 % tax rate in Stripe no longer leaves the charge without an invoice when the buyer is in the peninsula or the Balearic Islands. This is the rate some platforms create by default. BeeL. applies the default exemption reason your company declared, or asks you to declare it. Buyers in the Canary Islands, Ceuta or Melilla, buyers from other countries, and payments with no postal code still wait in Needs attention.
  • invoice.paid now sees the buyer's country. When neither the Stripe invoice nor its customer carries one, BeeL. takes it from the billing address of the payment that paid the invoice, so both events of the same charge see the same buyer.
  • A buyer outside Spain with an incomplete address is no longer invoiced as if the sale were Spanish. If the sale cannot go on a simplified invoice, the charge waits with a draft to complete, as it already did for the payment event.
  • What to do: if you sell exempt with a 0 % rate in Stripe, declare your default exemption reason in BeeL. under Settings > Taxes. If you sell outside Spain, collect the full billing address (street, city, postal code and country) at checkout.
Breaking
Breaking
Breaking
Breaking
Breaking
Breaking
New

Exchange simplified invoices for a full invoice

When a customer who paid with a simplified invoice asks for an invoice with their details, POST /v1/companies/{company_id}/invoices/simplified-exchanges issues a STANDARD invoice with the lines of up to 50 simplified invoices and the recipient you send. It is not a corrective invoice: it documents the same operations again, identifying the customer.

The new invoice lists the ones it replaces in replaced_invoice_ids, and each simplified invoice becomes VOIDED with the new void_cause value EXCHANGED, in the same act. The exchange invoice cannot be voided afterwards; if it is wrong, correct it with a corrective invoice.

When the invoice would be recorded with VeriFactu, the request answered 422 SIMPLIFIED_EXCHANGE_NOT_RECORDABLE and nothing was issued.

Update: with VeriFactu the exchange invoice is now issued and recorded as F3, and SIMPLIFIED_EXCHANGE_NOT_RECORDABLE only names a simplified invoice issued without VeriFactu. An F3 exchange invoice cannot be corrected yet. See Simplified invoice exchanges are recorded with VeriFactu.

  • Rejections: 422 EXCHANGE_REQUIRES_SIMPLIFIED when an id is not a simplified invoice; 422 SIMPLIFIED_NOT_EXCHANGEABLE when it is not issued, or was already voided, exchanged or corrected; voiding the exchange invoice answers 422 EXCHANGE_INVOICE_NOT_VOIDABLE.
  • If you read void_cause with a strict enum, add EXCHANGED; replaced_invoice_ids is a new optional field on every invoice response.
  • POST/v1/companies/{company_id}/invoices/simplified-exchangesNew: a full invoice in exchange for simplified invoices
Breaking
Breaking
Breaking
Breaking
Breaking
New

Member grants carry the company's name

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 without resolving every id against the account's companies. It is optional and may be null for a company that has no name yet. It never falls back to the id.

  • GET/v1/accounts/{account_id}/members/{member_id}/grantsEach grant carries company_name
Breaking
Breaking
Breaking
Breaking
Breaking
Breaking

Two never-documented payment-connection operations are gone today; on 11 December 2026 charges_only defaults to true and three counts fields and four schema aliases retire.

Retired today: GET …/payment-connections/{connection_id} (now 405) and POST …/payment-connections/{connection_id}/reactivations (now 404)No operation is deprecated: listing, opening an authorization and reading a single event stay documented and servedOn 11 December 2026 omitting charges_only on the event listing reads as charges_only=true; until then a request that omits it answers with Deprecation, Sunset and Linkcounts.ignored, counts.needs_action, counts.by_failure_reason and the four *ManagedPaymentEventResponse aliases retire the same day

Breaking
Breaking
Breaking
Breaking
Breaking
Improved

VeriFactu is always on in sandbox

Creating a company in sandbox is asking for a VeriFactu test bench, so the configuration is now born enabled and the NIF is registered with the provider on the first submission — no explicit step. In Live nothing changes: enabling VeriFactu there is still a deliberate act by the taxpayer.

No existing configuration was touched.

Breaking
Breaking
Breaking
Breaking
Breaking
Breaking
Breaking

Lists answer data.<plural>, deletes answer 204 unless the body informs, and every create returns Location. DELETE products/bulk takes ?ids= instead of a body.

Lists: data is never a bare array anymore. Six lists that answered data: [...] + root pagination (companies of an account, series, recurring invoices, payment events, request logs, sent emails) now answer data.<plural> + data.pagination — deprecated flat aliases included, since they share the schema. Five unpaginated lists (company stats, email indicators, payment connections, recurring history, series defaults) are wrapped in data.{plural} with no pagination block.Deletes: DELETE .../customers/{id} and DELETE .../representation now answer 204 with no body — their old 200 bodies carried nothing you could not already know. Bulk deletes and DELETE .../activations keep their 200 body (partial results and the computed effective_at are only knowable from the response).DELETE /v1/companies/{company_id}/products/bulk no longer takes a request body — a body on DELETE has no defined semantics and intermediaries may drop it. Send ?ids= (comma-separated, max 100 per request), same as customers/bulk.Every single-resource 201 now carries a Location header pointing at the created resource's canonical GET — including actions that produce a resource (corrective, convert, derivations, generate, payment-event draft). Claim tokens point at their claim_url. Bulk creations carry none: there is no single URI to point at.PUT /v1/configuration/series/{series_id} is now deprecated like the rest of the flat series routes. It has no drop-in successor: the canonical PATCH /v1/companies/{company_id}/series/{series_id} behaves the same for every body except an explicit description: null, which the old PUT ignored and the PATCH honours by clearing the field.Declarative sweep: every live operation now documents 429 and 500, every tag is declared, and the account companies operations moved from the PublicCompanies tag to AccountCompanies.These changes ship without a grace window: measured traffic on the affected shapes was test-mode only. If your integration reads any of the old list shapes, adapt the paths above — everything else about each operation is unchanged.

Improved

A webhook URL on a private network is rejected when you register it

Registering or changing a subscription URL that points to a private or internal network address now answers 422 URL_TARGET_NOT_ALLOWED, instead of creating a subscription that would never receive a delivery. A host that does not resolve yet is still accepted, so you can register before your DNS is live.

Breaking

The invoice field first announced as external_reference is now called external_ref. Responses already emit the new name; the old one is still accepted when you write, as a deprecated alias.

Responses emit external_ref — the old name is no longer returnedWrites still accept external_reference, as a deprecated aliasAffects the request body of the create-invoice routes and the GET /v1/invoices query filterNothing has stopped working, and no removal date is announced yet

Breaking

New: an account can hold several NIFs, each addressed in the path. As a result the old flat routes are deprecated — 82 operations gain a Sunset date, and all but three a successor route, and keep answering until then.

82 operations are deprecated, each with a Sunset date and, for all but three, a successor routeNothing is removed — every deprecated route keeps answering until its Sunset dateDeprecated routes carry Deprecation: true, Sunset and, where a successor is declared, Link: <successor>; rel="successor-version"The three replacing PUTs (customer, product, recurring invoice) declare no successor: the canonical PATCH merges instead of replacing, so it is not a drop-in

Breaking
Breaking
Breaking
Breaking
Breaking