Versioning
The version is in the path — https://api.essentio.pro/v1 — and it is the only one there is. What v1 answers is a promise: within v1 the API only grows, so a program written against it today keeps working.
v1 only grows
Within v1 these may be added:
- endpoints, and optional parameters and fields of a request;
- fields of an answer;
- values of a field that lists its values — a document’s
status, a Line’svat_category, a Payment’spayment_method; - error types, Refusal codes and remedies;
- Webhook events.
Nothing is renamed or removed: no endpoint, field, value, error type, Refusal code or event. There are no versions pinned by date, and nothing to send to choose one.
So write a program that expects more than it knows:
- Ignore a field you do not know. Never refuse an answer because it holds one — don’t validate answers against a closed schema.
- Keep a value you do not know rather than failing on it, and treat it as “something else”: an unknown
statusis a state your program does not handle yet. - Treat an unknown error type by its HTTP status, and an unknown Refusal code as a refusal you do not handle yet, showing its
message. - Ignore a Webhook event whose
typeyou do not know, and answer it2xx.
Open value sets
The contract, the OpenAPI file, is written to be read that way. It closes no object — an answer may carry fields the file you downloaded does not list — and it lists an answer’s values as they are today under x-known-values, never as an enum, with each description saying: “Within v1 another value may be added: keep a value you do not know.” A client generated from the file therefore takes a new value as a string instead of failing to parse the answer.
What you send is held to the rules: a request’s parameters and fields keep their enums, and a value the API does not take is refused with a 422 invalid_request.
The API is tested against the file: every answer the test suite receives is checked against it, and a field the server sends that the file does not declare fails the build. Download the file again to see what was added.
A breaking change is a v2
A change that could break a program written against v1 — a field renamed, removed or given another type, a value no longer answered — is never made to v1. It is made in a v2, at https://api.essentio.pro/v2, and v1 keeps answering beside it for at least twelve months after v2 is announced, so you move when it suits you. There is no v2 today.
Changelog
November 2026
- The OpenAPI file words each Refusal code in
x-enum-descriptions.RefusalCodein the OpenAPI file gives each code’s words — the Action it refuses, then why — as one entry ofx-enum-descriptions, keyed by the code, where its description listed them; the description keeps what holds for every code. A program that read a code’s words off the description readsx-enum-descriptionsinstead. The codes, their words and every answer are unchanged. number_of_another_typeis added. A Draft’sdocument_numberthat another document type’s numbering pattern forms —INV-2026-0002on a Quote — is refused: create and update of a Draft refuse itinvalid_requestatdocument_number, and Issue and Send refuse a Draft that holds one with the new Refusal codenumber_of_another_type, the Draft kept. And an Issue whose next number another document already holds steps past it, so that type’s sequence has a gap there.- A Send’s subject is one line. Send a document and the MCP tool Send Document refuse a
subjectholding a line break, a tab or another control character,invalid_requestatsubjectin the words “The subject must be one line.”, and nothing is issued or sent. Send the subject on one line. - A document may carry a Discount. A create and an update of a Draft take
discount_percentordiscount_amount, a decimal string: one Discount on the whole document, taken off its Subtotal before VAT, on a document whose Lines all share one VAT category, rate and exemption code (one VAT group). A document — as the API answers it, in a Webhook’sdataand to the MCP server’s tools — carriesdiscount_percent,discount_amountandsubtotal_after_discount; a document without a Discount answersnull, zero at its currency’s scale ("0.00"in EUR) and itssubtotal. On a discounted document,totalissubtotal_after_discount+total_vat, and a VAT group’snetis less the Discount: read them as before, and usesubtotal_after_discountwhere you tooksubtotalas the amount VAT is computed on. A converted Proforma Invoice’s Discount is its Invoice’s. The MCP server’sessentio_create_draftandessentio_update_drafttake the same two fields.
October 2026
- A Payment may be recorded by the Bank feed. A Business that lets its Bank feed settle exact matches by itself has Payments no API key, Connected app or person recorded: a Payment’s
recorded_byanswers them{"type": "bank_feed", "name": "Bank feed"}, a new value oftype. Keep atypeyou do not know, as the contract says; every other Payment answers as before. - A Draft keeps the day it is to be issued on. Create and update of a Draft take an optional
issue_date(YYYY-MM-DD), which was refused before: the day the Draft is to be issued on, today or an earlier day, today being the Business’s own. A later day is refusedinvalid_requestatissue_date, and adue_datebefore the day atdue_date; an update sending itnullclears it, and one not sending it keeps it. A document answers it asrequested_issue_date—nullwhen it holds none and once it is issued — andissue_datestaysnullon a Draft. Issue and Send with noissue_dateof their own issue a Draft holding one on that day, numbered for it; a Draft holding none is issued as before. The MCP server’sessentio_create_draftandessentio_update_drafttake the sameissue_date. - Issue, Send and Convert take the issue date. Issue a Draft, Send a document and Convert a Proforma Invoice take an optional
issue_date(YYYY-MM-DD): the day the document is issued on, today or any earlier day, today being the Business’s own, in its time zone. Its Document number is formed for that day, and a converted Invoice is due that day plus the Client’s payment terms. A day after the Business’s today is refused with the Refusal codeissue_date_in_the_future, and nothing is issued. Without it, Issue and Send issue a Draft today, as before; a conversion issues its Invoice on the day the Proforma was last paid (no later than today), or today when it holds no Payment, and dates it due that day plus the Client’s terms. The MCP server’sessentio_issue_document,essentio_send_documentandessentio_convert_proformatake the sameissue_date. number_of_an_earlier_periodis added. Under a yearly or monthly reset, a Draft’sdocument_numberthat belongs to an earlier year or month than the day it is issued on —INV-202612-5typed in January — is refused: create and update of a Draft refuse itinvalid_requestatdocument_number, and Issue and Send refuse a Draft that holds one with the new Refusal codenumber_of_an_earlier_period, the Draft kept. To number a document in an earlier year or month, issue it on a day in that period: it takes that period’s next number.number_of_a_later_periodis unchanged, and a numbering that does not reset is unaffected.number_of_a_later_periodis added. Under a yearly or monthly reset, a Draft’sdocument_numberthat belongs to a later year or month than the day it is issued on —INV-202611-1typed in October — is refused: create and update of a Draft refuse itinvalid_requestatdocument_number, and Issue and Send refuse a Draft that holds one with the new Refusal codenumber_of_a_later_period, the Draft kept. A number of the day’s own period, and a numbering that does not reset, are taken as before; an earlier period’s number is refused too (number_of_an_earlier_period, above).- Cancel can tell the Client. Cancel a document takes an optional
notify_client:truealso emails the Client a Cancellation notice, to whoever the document was last emailed to, else the Client’s address. Its answer addscancellation_notice—nullwhen none was asked, else whether the notice went and to whom, or why not; the document is cancelled either way, and the cancel’s own status and codes are unchanged. Sent withoutnotify_client, a cancel emails nobody and answers as before, withcancellation_notice: null. The MCP server’sessentio_cancel_documenttakesnotify_clientand answers the same. issuing_limit_reachedmay come before a Business’s own fifth Invoice. On the Free plan, Issue and Send may be refusedissuing_limit_reachedbefore the Business has issued 5 Invoices this month itself;messagethen says the limit is shared, and never names another Business. The code, its remedychoose_planand its HTTP answer are unchanged: handle it as before.business_pausedis no longer answered. A Business is Free or Pro on its own, sobusiness_pausedis answered by nothing and left the list of Refusal codes; a program that handles it loses nothing. The words ofpaid_plan_required,webhooks_need_a_paid_planandsending_limit_reachedname Pro as the one paid plan. Nothing else of the contract changed;is_test, a document'sactionsand every other code stand.- A document names its Supply date. A document — as the API answers it, in a Webhook’s
dataand to the MCP server’s tools — carriessupply_dateandsupply_date_to: the day the supply it bills took place, or a supply period’s first and last day, eachnullwhen none was given. A create and an update of a Draft take both;supply_date_toneedssupply_dateand is on or after it, or the Draft is refusedinvalid_requestatsupply_date_to. A document’s EN16931 XML writes one date as the Actual delivery date (BT-72) and a period as the Invoicing period (BG-14); an intra-community supply’s BT-72 is its Supply date when it has one, else its issue date as before. A document with neither answers and exports as before: a field is only ever added within v1. - A Credit Note’s and a Cancelled document’s refusal say what fits them. A document’s EN16931 XML refused
not_exportablefor a detail of the Business or the Client now ends, on an issued Credit Note, “…, then issue a new Credit Note: this one keeps the details it was issued with.”, and on a Cancelled document, which nothing corrects, says the fault alone (“The Client has no address.”). An issued Invoice’s refusal, a Draft’s, the code and the JSON answers are unchanged. - An issued document’s refusal says how it is corrected. An issued Invoice or Credit Note keeps its Business’s and its Client’s details as they were when it was issued, so a document’s EN16931 XML refused
not_exportablefor a detail of either now says so after where the detail is set: “The Client has no address. Add it on the Client, then correct this document with a Credit Note and a new document: it keeps the details it was issued with.” A Draft’s refusals, the code and the JSON answers are unchanged. - A VAT number is stored upper-case. A Client’s
vat_numbersent with lower-case letters is stored and answered upper-case (de987654321→DE987654321), on create and update, through the API and the MCP tools as in Essentio’s screens; its spaces, dashes and dots and a missing country code are kept as sent. A number sent back in lower case is the number stored: it is not checked with VIES again and keepsvat_verified. A number sent upper-case sees no change. - A Northern Ireland VAT number is checked with VIES. A Client’s
vat_numbertyped withXI— Northern Ireland’s prefix, which VIES serves beside the EU’s member states, normally on a Client whosecountryisGB— is checked with VIES when the Client is created or its number or country changes, as an EU number is, andvat_verifiedsays whether VIES confirmed it; it was stored unverified, never checked. One without VIES’s shape forXI(9 or 12 digits, orGDorHAand 3 digits) is refusedinvalid_requestatvat_number, in words, and nothing is written. AGBnumber, or a number with noXIon a Client inGB, is stored unverified, as before. - The Business’s VAT number is read as a Client’s. A document’s EN16931 XML writes the Business’s VAT number (BT-31) as it writes a Client’s: spaces, dashes and dots and a leading
VATare dropped and the rest is upper-cased, a number stored without its country code takes the Business’s country first, and Greece’s code isEL— so a number stored1012 3456Xby a Business in Cyprus is writtenCY10123456Xand exported, where it was written as stored or refusednot_exportable. Still refused: a number whose first two letters are no country code, in the new words “This business’s VAT Number has no country code the export can use: enter it with its country code first, such as CY10123456X. Set it in Settings → General, under VAT Status.” The Business setup’svat_numberis that same identifier, as its documents print it. A Client’scountrysent in lower case is stored and answered upper-case (de→DE), as the contract’s pattern already said. A VAT number stored with its country code and no separators is written as before. - A Non-VAT Payer’s Lines are not subject to VAT. A Business set to Non-VAT Payer charges no VAT, so every Line of every document it creates or changes — through the API and the MCP tools as in the editor — is not subject to VAT:
vat_categoryO,vat_rate"0",vat_exemption_codeVATEX-EU-O. A Line sent with none of the three takes them; one sent with a rate above 0, another category or another exemption code is refusedinvalid_requestat the Line, in the editor’s words, and nothing is written. The Business setup gainsvat_payer(a boolean, added; a VAT payer’s answer is otherwise unchanged) and answers a Non-VAT Payervat_ratesas[]. A Non-VAT Payer’s existing Drafts take the same three values; its issued documents keep their Lines, and a Proforma it issued with VAT converts into an Invoice whose Lines are not subject to VAT. A VAT payer’s documents, rates and Lines are unchanged. - A Line’s VAT category and its exemption code agree. Each
vat_exemption_codeis one VAT category’s —VATEX-EU-AEisAE’s,VATEX-EU-ICisK’s,VATEX-EU-GisG’s,VATEX-EU-OisO’s and the rest areE’s (Business setup) — and a Line carries only a code of its own category; anSorZLine carries none. A Line sent otherwise — through the API and the MCP tools as in the editor — is refusedinvalid_requestat the Line, in the editor’s words (“Line 1: VAT category S takes no VAT exemption code.”), and nothing is written. A Line whose code is its category’s, and every document already issued, are unchanged. - A Client’s VAT number is read one way. A document’s EN16931 XML writes a Client’s VAT number (BT-48) as VIES is asked for it: spaces, dashes and dots and a leading
VATare dropped and the rest is upper-cased, so a storedde987654321is writtenDE987654321and exported, where it was refusednot_exportable. Only two Latin letters make a country code; a Greek country code isEL, whether the number came withGRorEL. The refusal for a number with no usable country code now reads “The Client’s VAT Number has no country code the export can use: enter the number with the Client’s country set, or with its code first, such as DE123456789. Fix it on the Client.” The JSON answers are unchanged. - A Client’s VAT number is written with its country code. A document’s EN16931 XML to a Client whose VAT number Essentio stores without its country code — as the Client form stores every one — was refused
not_exportablesince the EN 16931 check below, saying the number does not start with its country code; it is now exported, the number written as the Client’s VAT identifier (BT-48) with the Client’s country first, in capitals (ELfor Greece). A number stored with two letters first is written as stored, as before. Still refused: a Client’s number whose two first letters are not a country code in capitals, or one stored without a code for a Client with no country, in the new words “The Client’s VAT Number has no country code the export can use: enter the number with the Client’s country set, or with its code first in capitals, such as DE123456789. Fix it on the Client.” The JSON answers are unchanged. - The EN 16931 check asks for what the standard asks for. A document’s EN16931 XML is refused
not_exportable(the same code, in new words) by the standard’s own rule table: a VAT number of the Business only for an intra-community supply (K) or an export (G); forS,Z,EandAELines a VAT number or a TAX ID; for a document ofOLines a Registration Number or a TAX ID — so a Business with a TAX ID and no VAT number, or a Non-VAT Payer, now exports where it was refused. Newly refused, before any file is written: anOLine beside another VAT category, a VAT number (the Business’s or the Client’s) not starting with its two-letter country code in capitals, anAEdocument whose Client has no VAT number, and aKdocument whose Client has no VAT number or no country.error.messagecarries each reason as one sentence saying where it is fixed. The JSON answers, and the XML of a document that passed before, are unchanged. - A document’s XML follows EN 16931 itself. A document’s EN16931 XML no longer claims Peppol BIS Billing 3.0: its
cbc:CustomizationIDisurn:cen.eu:en16931:2017and it carries nocbc:ProfileID. A Business with no bank account is written with the payment means code1(not defined) where it was30(credit transfer) with no account. A document whose Lines are all not subject to VAT (O) carries neither party’s VAT number, and anOLine or breakdown nocbc:Percent. A Business whose VAT number is not written — a Non-VAT Payer, whose stored number the file no longer carries, or a document ofOLines — is identified by its TAX ID (BT-29, BT-32) when it has one. A document with an intra-community supply (K) carries its delivery: the issue date and the Client’s country. Any other file of a VAT payer changes in itscbc:CustomizationIDandcbc:ProfileIDonly. The JSON answers are unchanged. - A Non-VAT Payer’s VAT number is printed nowhere. A Business set to Non-VAT Payer keeps the VAT number it stored and prints none: its documents’ From block and PDFs, the public page, Receipts and Statements leave it out, and the Business setup answers
vat_numberasnullwhile it is a Non-VAT Payer. A VAT payer’s answers are unchanged. The one place that still carries the stored number is the document’s EN16931 XML, until a later change. The field already allowednull: nothing was added. - A Product’s price is read to its last decimal, and held to its currency. A Product’s
price— as the API answers it and to the MCP server’s tools — is the price as stored: in a currency of three decimals a price of 10.125 is"10.125", where it read"10.13", andprice_without_vatandprice_with_vatare computed from it ("10.125"and not"10.130"). A price of two decimals or fewer reads as before. Apricesent with more decimals than itscurrencyhas, which was stored rounded, or with more than 15 digits before the point, is a422invalid_requestwitherrors.price, and nothing is written. Acurrencychanged alone to one the Product’s price has more decimals than is refused the same way, witherrors.currency. Aprice, or a Payment’samount, written with an exponent of more than three digits ("1e1000") is a422invalid_requesttoo. MCP’s tools answer the same. - A number or an amount no column can hold is refused in words. An issue, a send or a Payment whose next number is the largest the numbering holds is a
422refusalwith the new codenumbering_at_its_end, nothing written — a Draft can still be issued with an unused earlier number sent as itsdocument_number. A Client’scredit_limitwith a third decimal is refused (invalid_request), where it was rounded to two. And these are a422invalid_requestnaming the field:payment_termspast 999999 days, on a Client and a document; a Product’sstock_quantityorminimum_stockpast 2147483647; a Line whose Net amount (quantity × unit price) is not below 1,000,000,000,000,000, under itsunit_price; and Lines whose Total is not below it, underlines. - A document says when, to whom and how it was last sent. A document — as the API answers it, in a Webhook’s
dataand to the MCP server’s tools — carrieslast_sent:{at, recipients, via}, the newest time it was sent while it is marked sent, ornull.viais the provider that took the email (essentio,gmail,microsoft,smtp) ormarked, a mark by hand with norecipients. Nothing else changed: a field is only ever added within v1.
September 2026
- Essentio sends a Business's mail. A Business with no mailbox connected now sends through Essentio's own mail server, so Send is open for it where it was refused
no_mail_provider; that code now means a Business with no email address of its own. The new codesending_limit_reachedrefuses a Send past the Business's daily number of recipients through Essentio, with the remedyconnect_mail_provider. - A document’s XML carries its Lines’ notes. A Line’s
notes, downloaded as the document’s EN16931 XML, is written in that Line as BT-127, Invoice line note: onecbc:Noteafter the Line’scbc:ID, in an Invoice’scac:InvoiceLineand a Credit Note’scac:CreditNoteLine. A Line with no note exports as before, and nothing is written as the Item’s description (BT-154). - A Line takes a note, and a Line’s errors are in plain words. A Line sent to create or update a Draft — through the API or the MCP server’s
essentio_create_draftandessentio_update_draft— takesnotes, at most 500 characters, printed with the Line on the document; until now a Line’snoteswas ignored. A document’s Lines — as the API answers them, in a Webhook’sdataand to the MCP server’s tools — carrynotes,nullwhen the Line has none. And an error about a Line now names the Line by its place, counted from 1, and its field by name: “Line 1: Unit must not be longer than 50 characters.”, where it read “The lines.0.unit field must not be greater than 50 characters.”. Every Line error has the new words, a decimal sent as a JSON number included; the keys inerrorsdid not change (lines.0.unit). - The MCP server's answers no longer link to a plan. A document's
actions, as the MCP server's tools answer them, carry noremedy_urlwith the remedychoose_plan; its code, words and remedy stay. The Public API still sends the link, andconnect_mail_provider's link stays on both. - A Test business keeps no real books. The Business setup and every document carry
is_test. A Test business’s numbers carryTEST-in front of what its number patterns make; its XML is refused with the new codeexports_not_in_a_test_business; and it meets the Free plan’s Issuing limit (issuing_limit_reached), which a reset clears. An ordinary Business’s answers are unchanged. - A document says whether it is Overdue, and names its conversion. A document — as the API answers it, in a Webhook’s
dataand to the MCP server’s tools — carries four more fields:is_overdueanddays_overdue(nullwhile it is not Overdue), as Essentio shows it, so an overdue Invoice no longer reads onlyissued;proforma_id, the Proforma Invoice it was converted from; andconverted_into_id, the Invoice a Proforma Invoice was converted into. Nothing else changed: a field is only ever added within v1. choose_plansays where to choose a plan. A document’sactionsnow carryremedy_urlwith the remedychoose_plantoo, as they did withconnect_mail_provider: the page in Essentio where the Business’s Owner chooses a plan (Settings → Billing), for a person signed in to Essentio who belongs to the Business.- A Draft deleted or issued by another request is refused. An issue, a send or an update of a Draft deleted by another request is a
422refusal,draft_deleted("This draft was deleted."): nothing is written and no number is taken. A delete of a Draft issued by another request is a422refusal,issued_not_deleted, and the document stays. A delete of a Draft already deleted is answered as done. - An amendment that sends no field says there is nothing to change.
PATCH /v1/payments/{id}with a body that sends none of a Payment’s fields —{}— is a422invalid_request, where it was arefusalabout the amount, witherrors.payment: “Nothing to change: send at least one field.” Nothing is written, as before. MCP’sessentio_amend_paymentgiven onlypayment_idanswers the same. - On the Free plan the Owner’s own MCP Connected app is not cut to reading. The plan cuts a Connected app as it cuts the person who authorised it: on the Free plan the Owner’s own app does what the Role it was given lets it — creating Clients, issuing Invoices up to the Issuing limit, where it is refused
issuing_limit_reached— and an Admin’s or a Member’s still only reads (plan_role_viewing). A document’sactionsanswer the same. The Public API is unchanged. - The Public API needs a paid plan. While a Business is on the Free plan, every request of its API keys and Connected apps — a read included — is a
403permissionwith the codepaid_plan_requiredand the remedychoose_plan, and does nothing. The keys and apps are not revoked: the same credential works again once the Business is on Pro. The MCP server is not the Public API and keeps working on every plan, soplan_role_viewing(the entry below) is answered there and in Essentio, never by the Public API. - A Business’s plan cuts what a credential may do. On the Free plan every credential only reads. A change the plan does not let is still a
403permission, now with the codeplan_role_viewingand the remedychoose_plan; a document’sactionsanswer the same codes. - An update of a Draft linked to a Cancelled Proforma Invoice is refused.
PATCH /v1/documents/{id}of a Draft still linked to a Proforma Invoice that was cancelled is a422refusal,cancelled_not_converted: nothing is written, the Draft keeps its link and takes no number. - Every refusal carries a Refusal code. Three answers that were a
422invalid_requestin words alone are now a422refusalwith acode, in the same words: an update of an issued document (issued_not_changed), an update of a Draft linked to a Proforma Invoice that does not convert into it (proforma_deleted,only_into_an_invoice,proforma_other_currency,proforma_other_client), and the XML of a document that is not exported (not_exportable).invalid_requestnow means only that the request’s fields, parameters or headers were refused. The Refusal codes list every code Essentio has, including the ones no operation answers today.