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’s vat_category, a Payment’s payment_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 status is 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 type you do not know, and answer it 2xx.

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. RefusalCode in the OpenAPI file gives each code’s words — the Action it refuses, then why — as one entry of x-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 reads x-enum-descriptions instead. The codes, their words and every answer are unchanged.
  • number_of_another_type is added. A Draft’s document_number that another document type’s numbering pattern forms — INV-2026-0002 on a Quote — is refused: create and update of a Draft refuse it invalid_request at document_number, and Issue and Send refuse a Draft that holds one with the new Refusal code number_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 subject holding a line break, a tab or another control character, invalid_request at subject in 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_percent or discount_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’s data and to the MCP server’s tools — carries discount_percent, discount_amount and subtotal_after_discount; a document without a Discount answers null, zero at its currency’s scale ("0.00" in EUR) and its subtotal. On a discounted document, total is subtotal_after_discount + total_vat, and a VAT group’s net is less the Discount: read them as before, and use subtotal_after_discount where you took subtotal as the amount VAT is computed on. A converted Proforma Invoice’s Discount is its Invoice’s. The MCP server’s essentio_create_draft and essentio_update_draft take 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_by answers them {"type": "bank_feed", "name": "Bank feed"}, a new value of type. Keep a type you 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 refused invalid_request at issue_date, and a due_date before the day at due_date; an update sending it null clears it, and one not sending it keeps it. A document answers it as requested_issue_date — null when it holds none and once it is issued — and issue_date stays null on a Draft. Issue and Send with no issue_date of their own issue a Draft holding one on that day, numbered for it; a Draft holding none is issued as before. The MCP server’s essentio_create_draft and essentio_update_draft take the same issue_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 code issue_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’s essentio_issue_document, essentio_send_document and essentio_convert_proforma take the same issue_date.
  • number_of_an_earlier_period is added. Under a yearly or monthly reset, a Draft’s document_number that belongs to an earlier year or month than the day it is issued on — INV-202612-5 typed in January — is refused: create and update of a Draft refuse it invalid_request at document_number, and Issue and Send refuse a Draft that holds one with the new Refusal code number_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_period is unchanged, and a numbering that does not reset is unaffected.
  • number_of_a_later_period is added. Under a yearly or monthly reset, a Draft’s document_number that belongs to a later year or month than the day it is issued on — INV-202611-1 typed in October — is refused: create and update of a Draft refuse it invalid_request at document_number, and Issue and Send refuse a Draft that holds one with the new Refusal code number_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: true also emails the Client a Cancellation notice, to whoever the document was last emailed to, else the Client’s address. Its answer adds cancellation_notice — null when 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 without notify_client, a cancel emails nobody and answers as before, with cancellation_notice: null. The MCP server’s essentio_cancel_document takes notify_client and answers the same.
  • issuing_limit_reached may come before a Business’s own fifth Invoice. On the Free plan, Issue and Send may be refused issuing_limit_reached before the Business has issued 5 Invoices this month itself; message then says the limit is shared, and never names another Business. The code, its remedy choose_plan and its HTTP answer are unchanged: handle it as before.
  • business_paused is no longer answered. A Business is Free or Pro on its own, so business_paused is answered by nothing and left the list of Refusal codes; a program that handles it loses nothing. The words of paid_plan_required, webhooks_need_a_paid_plan and sending_limit_reached name Pro as the one paid plan. Nothing else of the contract changed; is_test, a document's actions and every other code stand.
  • A document names its Supply date. A document — as the API answers it, in a Webhook’s data and to the MCP server’s tools — carries supply_date and supply_date_to: the day the supply it bills took place, or a supply period’s first and last day, each null when none was given. A create and an update of a Draft take both; supply_date_to needs supply_date and is on or after it, or the Draft is refused invalid_request at supply_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_exportable for 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_exportable for 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_number sent 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 keeps vat_verified. A number sent upper-case sees no change.
  • A Northern Ireland VAT number is checked with VIES. A Client’s vat_number typed with XI — Northern Ireland’s prefix, which VIES serves beside the EU’s member states, normally on a Client whose country is GB — is checked with VIES when the Client is created or its number or country changes, as an EU number is, and vat_verified says whether VIES confirmed it; it was stored unverified, never checked. One without VIES’s shape for XI (9 or 12 digits, or GD or HA and 3 digits) is refused invalid_request at vat_number, in words, and nothing is written. A GB number, or a number with no XI on a Client in GB, 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 VAT are dropped and the rest is upper-cased, a number stored without its country code takes the Business’s country first, and Greece’s code is EL — so a number stored 1012 3456X by a Business in Cyprus is written CY10123456X and exported, where it was written as stored or refused not_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’s vat_number is that same identifier, as its documents print it. A Client’s country sent 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_category O, vat_rate "0", vat_exemption_code VATEX-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 refused invalid_request at the Line, in the editor’s words, and nothing is written. The Business setup gains vat_payer (a boolean, added; a VAT payer’s answer is otherwise unchanged) and answers a Non-VAT Payer vat_rates as []. 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_code is one VAT category’s — VATEX-EU-AE is AE’s, VATEX-EU-IC is K’s, VATEX-EU-G is G’s, VATEX-EU-O is O’s and the rest are E’s (Business setup) — and a Line carries only a code of its own category; an S or Z Line carries none. A Line sent otherwise — through the API and the MCP tools as in the editor — is refused invalid_request at 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 VAT are dropped and the rest is upper-cased, so a stored de987654321 is written DE987654321 and exported, where it was refused not_exportable. Only two Latin letters make a country code; a Greek country code is EL, whether the number came with GR or EL. 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_exportable since 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 (EL for 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); for S, Z, E and AE Lines a VAT number or a TAX ID; for a document of O Lines 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: an O Line beside another VAT category, a VAT number (the Business’s or the Client’s) not starting with its two-letter country code in capitals, an AE document whose Client has no VAT number, and a K document whose Client has no VAT number or no country. error.message carries 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:CustomizationID is urn:cen.eu:en16931:2017 and it carries no cbc:ProfileID. A Business with no bank account is written with the payment means code 1 (not defined) where it was 30 (credit transfer) with no account. A document whose Lines are all not subject to VAT (O) carries neither party’s VAT number, and an O Line or breakdown no cbc:Percent. A Business whose VAT number is not written — a Non-VAT Payer, whose stored number the file no longer carries, or a document of O Lines — 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 its cbc:CustomizationID and cbc:ProfileID only. 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_number as null while 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 allowed null: 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", and price_without_vat and price_with_vat are computed from it ("10.125" and not "10.130"). A price of two decimals or fewer reads as before. A price sent with more decimals than its currency has, which was stored rounded, or with more than 15 digits before the point, is a 422 invalid_request with errors.price, and nothing is written. A currency changed alone to one the Product’s price has more decimals than is refused the same way, with errors.currency. A price, or a Payment’s amount, written with an exponent of more than three digits ("1e1000") is a 422 invalid_request too. 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 422 refusal with the new code numbering_at_its_end, nothing written — a Draft can still be issued with an unused earlier number sent as its document_number. A Client’s credit_limit with a third decimal is refused (invalid_request), where it was rounded to two. And these are a 422 invalid_request naming the field: payment_terms past 999999 days, on a Client and a document; a Product’s stock_quantity or minimum_stock past 2147483647; a Line whose Net amount (quantity × unit price) is not below 1,000,000,000,000,000, under its unit_price; and Lines whose Total is not below it, under lines.
  • A document says when, to whom and how it was last sent. A document — as the API answers it, in a Webhook’s data and to the MCP server’s tools — carries last_sent: {at, recipients, via}, the newest time it was sent while it is marked sent, or null. via is the provider that took the email (essentio, gmail, microsoft, smtp) or marked, a mark by hand with no recipients. 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 code sending_limit_reached refuses a Send past the Business's daily number of recipients through Essentio, with the remedy connect_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: one cbc:Note after the Line’s cbc:ID, in an Invoice’s cac:InvoiceLine and a Credit Note’s cac: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_draft and essentio_update_draft — takes notes, at most 500 characters, printed with the Line on the document; until now a Line’s notes was ignored. A document’s Lines — as the API answers them, in a Webhook’s data and to the MCP server’s tools — carry notes, null when 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 in errors did 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 no remedy_url with the remedy choose_plan; its code, words and remedy stay. The Public API still sends the link, and connect_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 carry TEST- in front of what its number patterns make; its XML is refused with the new code exports_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 data and to the MCP server’s tools — carries four more fields: is_overdue and days_overdue (null while it is not Overdue), as Essentio shows it, so an overdue Invoice no longer reads only issued; proforma_id, the Proforma Invoice it was converted from; and converted_into_id, the Invoice a Proforma Invoice was converted into. Nothing else changed: a field is only ever added within v1.
  • choose_plan says where to choose a plan. A document’s actions now carry remedy_url with the remedy choose_plan too, as they did with connect_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 422 refusal, draft_deleted ("This draft was deleted."): nothing is written and no number is taken. A delete of a Draft issued by another request is a 422 refusal, 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 a 422 invalid_request, where it was a refusal about the amount, with errors.payment: “Nothing to change: send at least one field.” Nothing is written, as before. MCP’s essentio_amend_payment given only payment_id answers 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’s actions answer 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 403 permission with the code paid_plan_required and the remedy choose_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, so plan_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 403 permission, now with the code plan_role_viewing and the remedy choose_plan; a document’s actions answer 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 a 422 refusal, 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 422 invalid_request in words alone are now a 422 refusal with a code, 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_request now 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.