Documents
A document is an Invoice, a Proforma Invoice, a Credit Note or a Quote. On this page: the fields of a document, how to list and search a Business’s documents, how to create and change a Draft — held to the same rules as the document editor in Essentio — how to issue, send and cancel a document and convert a Proforma Invoice into its Invoice, and how to download a document’s PDF and its EN16931 XML.
Drafts and issued documents
A document starts as a Draft: it has no Document number and no issue date, it asks nobody for anything, and it can be changed freely. Issuing it takes the next number of the Business’s sequence, stamps the issue date and freezes its Lines and totals. The API creates, changes and deletes Drafts, and issues, sends and cancels documents as Essentio’s own buttons do.
- A Draft can carry the number it should be issued as,
document_number. It reserves nothing: the number is checked when the document is issued, and the issue is refused then if the number is taken, malformed or skips ahead. The document answers it asrequested_document_number, anddocument_numberstaysnulluntil the issue. - A Draft can carry the day it should be issued on,
issue_date: today or an earlier day, today being the Business’s own. It is not an issue date —issue_datestaysnulluntil the issue — and the document answers it asrequested_issue_date. An Issue or a Send that sends noissue_dateof its own issues the Draft on it. Without one, the Draft is issued on the day it is issued. - Anything that would issue a document on saving is refused: money received with it (
payments) and a Proforma Invoice it converts (proforma_invoice_id). - Only a Draft can be changed. An update of an issued document is refused with a
422refusal,issued_not_changed.
Refusals
Issuing, sending, cancelling, converting and deleting a Draft are Actions, and each is open or refused for a document as it stands, exactly as in Essentio: an issued document is not issued again, a Draft is not cancelled. A refused Action answers 422 with the error type refusal, a message in Essentio’s words and a Refusal code your program can branch on. Nothing was written.
Cancelling a Draft: 422
{
"error": {
"type": "refusal",
"code": "draft_not_cancelled",
"message": "A draft is deleted, not cancelled — it is not a document yet."
}
}
Some refusals carry a remedy: what the Business does in Essentio to open the Action. connect_mail_provider asks it to connect a mailbox of its own (or connect a lost account again) in Settings → Email — a Business with none sends through Essentio's own mail server, which needs the Business's email address and emails a limited number of recipients a day. Refusal codes are only ever added within v1: treat a code you do not know as a refusal you do not handle yet.
- Name
already_issued- Refused by
- Issue
- Description
Only a Draft is issued; this document already has its number.
- Name
number_taken- Refused by
- Issue, Send
- Description
The number the Draft asks for (
requested_document_number) is taken by another document. So arenumber_skips_ahead,number_beyond_the_counter,number_malformed,number_of_a_later_periodandnumber_of_an_earlier_period(a number of a later, or an earlier, year or month than the day it is issued on, under a yearly or monthly reset) andnumber_of_another_type(a number another document type’s numbering pattern forms), each named inmessage. The Draft stays a Draft: change or clear itsdocument_numberand try again.
- Name
numbering_at_its_end- Refused by
- Issue, Send
- Description
The next number of the document's type is the largest the numbering holds, which it never takes, because it cannot count past it;
messagenames it. The Draft stays a Draft: send an unused earlier number as itsdocument_numberand try again.
- Name
cancelled_not_sent- Refused by
- Send
- Description
A Cancelled document is not sent.
- Name
no_client_address- Refused by
- Send
- Description
The Client has no email address. Nothing is issued.
- Name
no_mail_provider- Refused by
- Send
- Description
The Business has nothing to send through: it sends through Essentio's own mail server unless it connected a mailbox, and it has no email address of its own for replies; remedy
connect_mail_provider. Nothing is issued.
- Name
mail_account_lost- Refused by
- Send
- Description
The Business’s connected mail account stopped renewing its access; remedy
connect_mail_provider. When the Send met it after issuing a Draft,document_numbernames the number it took.
- Name
sending_limit_reached- Refused by
- Send
- Description
The Business sends through Essentio's own mail server, which emails 20 recipients a day for it on the Free plan (and a Test business) and 100 on Pro — To, Cc and Bcc each count — and this email does not fit what is left; remedy
connect_mail_provider: its own mailbox has no such limit. Once none is left a Draft is not issued; when the Send met it after issuing a Draft,messagenames the number it took.
- Name
draft_not_cancelled- Refused by
- Cancel
- Description
A Draft is not a document yet: it is deleted instead.
- Name
paid_not_cancelled- Refused by
- Cancel
- Description
A Paid document is corrected with a Credit Note.
- Name
already_cancelled- Refused by
- Cancel
- Description
The document is already Cancelled.
- Name
holds_money- Refused by
- Cancel
- Description
The document holds Payments (or its Proforma’s): it is corrected with a Credit Note.
- Name
not_a_proforma- Refused by
- Convert
- Description
Only a Proforma Invoice converts into an Invoice.
- Name
draft_not_converted- Refused by
- Convert
- Description
A Draft Proforma Invoice is issued first.
- Name
cancelled_not_converted- Refused by
- Convert
- Description
A Cancelled Proforma Invoice converts into nothing.
- Name
already_converted- Refused by
- Convert
- Description
An Invoice was already made from this Proforma Invoice.
- Name
issued_not_deleted- Refused by
- Delete
- Description
Only a Draft is deleted; an issued document is cancelled instead.
- Name
draft_deleted- Refused by
- Issue, Send, Update
- Description
The Draft was deleted by another request while this one waited for it. Nothing is written and no number is taken.
- Name
issued_not_changed- Refused by
- Update
- Description
Only a Draft is changed through the API; an issued document is changed in Essentio.
- Name
proforma_deleted- Refused by
- Update
- Description
A Draft still linked to a Proforma Invoice is issued by its save, as that Proforma’s conversion. It is refused when the Proforma was deleted, and so are
cancelled_not_converted(the Proforma was cancelled),only_into_an_invoice(the Draft is no longer an Invoice),proforma_other_currencyandproforma_other_client, each named inmessage.
- Name
not_exportable- Refused by
- Download the XML
- Description
The document is not exported as EN16931 XML: a Draft, a Proforma Invoice or a Quote, or one the EN16931 check does not pass.
messagesays why.
- Name
exports_not_in_a_test_business- Refused by
- Download the XML
- Description
The Business is a Test business, which keeps no real books and exports no XML. Its PDFs stay, marked SAMPLE.
A key whose Role may not take the Action is answered 403 permission, never a refusal.
Money and decimals
- Money is a string. Every amount the API answers is an exact decimal at its currency’s scale —
"939.15"— never a floating-point number. Parse it with a decimal type. - Send decimals as strings too. A Line’s
quantity,unit_priceandvat_rate, andlate_fee_rate,discount_percentanddiscount_amount, are sent as strings:"95.00","19". A JSON number is refused, because it may be rounded before Essentio reads it. - Totals are Essentio’s. Each Line’s net amount is quantity × unit price, rounded to the currency’s minor unit. VAT is computed once per VAT group — the Lines sharing a VAT category, rate and exemption code — never per Line.
subtotal−discount_amount=subtotal_after_discount, andsubtotal_after_discount+total_vat=total; without a Discount,subtotal_after_discountissubtotal. - A Credit Note’s amounts are positive. Its type carries the sign: it reduces what the Client owes.
The document model
A document as the API answers it. A field that is null has not been filled in.
Properties
- Name
id- Type
- integer
- Description
The document’s identifier.
- Name
document_type- Type
- string
- Description
invoice,proforma(a Proforma Invoice),credit_noteorquote. Another value may be added within v1: keep one you do not know.
- Name
status- Type
- string
- Description
draft,issued,partially_paid,paidorcancelled. Whether the document reached its Client is not a state. Another value may be added within v1: keep one you do not know.
- Name
is_test- Type
- boolean
- Description
Whether it is a Test business’s document: a sample, not real books. Its PDF prints SAMPLE and its number carries
TEST-.
- Name
document_number- Type
- string or null
- Description
The Document number, taken when the document is issued.
nullon a Draft. A Test business’s carriesTEST-in front of what its number pattern makes, such asTEST-INV-2026-0007.
- Name
requested_document_number- Type
- string or null
- Description
The number a Draft asks to be issued as.
nullwhen it asks for none, and once it is issued.
- Name
requested_issue_date- Type
- date or null
- Description
The day a Draft is to be issued on, sent as its
issue_date: an Issue or a Send that sends no day issues it on this one. It is not an issue date.nullwhen it holds none, and once it is issued.
- Name
client_id- Type
- integer
- Description
The Client the document is for: a Client’s
id.
- Name
client- Type
- object
- Description
That Client’s
idandname, as it reads now, so the name needs no second request.
- Name
currency- Type
- string
- Description
ISO 4217:
EUR.
- Name
issue_date- Type
- date or null
- Description
The day the document was issued.
nullon a Draft.
- Name
due_date- Type
- date
- Description
The second date: an Invoice’s due date, a Proforma Invoice’s or a Quote’s valid-until date. A Credit Note shows none.
- Name
supply_date- Type
- date or null
- Description
The Supply date: the day the supply the document bills took place, or the first day of a supply period.
nullwhen none was given. Printed on the document and written in its EN16931 XML — one date as the Actual delivery date (BT-72), a period as the Invoicing period (BG-14). It moves no figure: reports count byissue_date. Frozen once the document is issued.
- Name
supply_date_to- Type
- date or null
- Description
The last day of a supply period, after
supply_date.nullfor one Supply date, or none.
- Name
payment_terms- Type
- integer
- Description
Days the due date is counted from.
- Name
is_overdue- Type
- boolean
- Description
Whether the document is Overdue, as Essentio shows it: issued or partially paid, asking for payment — an Invoice, or a Proforma Invoice never converted — and its
due_datebefore today. A Draft, a Paid or Cancelled document, a Credit Note, a Quote and a converted Proforma Invoice never are. Overdue is not astatus: the document keeps its own.
- Name
days_overdue- Type
- integer or null
- Description
How many days ago its
due_datewas, whileis_overdueistrue.nullwhenever it is not Overdue.
- Name
client_reference, purchase_order_number, project_reference- Type
- string or null
- Description
The Client’s references, written into the EN16931 XML.
- Name
notes- Type
- string or null
- Description
What the document says to its Client beside its Lines.
- Name
footer_text- Type
- string or null
- Description
The line printed at the foot of the document.
- Name
terms_and_conditions- Type
- string or null
- Description
The terms the document is issued under.
- Name
late_fee_rate- Type
- string or null
- Description
A percentage with two decimals:
"2.50".nullon a Credit Note or a Quote, which state none.
- Name
internal_notes- Type
- string or null
- Description
The Business’s own remark. Never shown to the Client.
- Name
lines- Type
- array
- Description
The document’s Lines, in order:
id,description,quantity("3.000"),unit,unit_price("95.0000", VAT excluded),vat_rate("19.00"),vat_category,vat_exemption_code,product_code,notes(the note printed with the Line, ornull) andnet_amount. A Line’sidchanges whenever the Lines are replaced.
- Name
subtotal- Type
- string
- Description
The sum of the Lines’ net amounts.
- Name
discount_percent- Type
- string or null
- Description
The Discount as the percentage of the Subtotal it was given as, with two decimals:
"10.00".nullwhen it was given as an amount, or there is none.
- Name
discount_amount- Type
- string
- Description
The Discount taken off the Subtotal before VAT, given as an amount or worked out from the percentage (rounded half away from zero, to the currency’s minor unit). Zero at the currency’s scale (
"0.00"in EUR) when there is none. Only a document whose Lines all share one VAT category, rate and exemption code (one VAT group) carries one.
- Name
subtotal_after_discount- Type
- string
- Description
Subtotal − Discount: what VAT is computed on. Equal to
subtotalwhen there is no Discount.
- Name
total_vat- Type
- string
- Description
The VAT of every VAT group.
- Name
total- Type
- string
- Description
Subtotal after discount + Total VAT.
- Name
vat_groups- Type
- array
- Description
The Lines grouped by VAT category, rate and exemption code:
category,rate,exemption_code,net(the group’s net amounts, less the Discount on a document that carries one) andvat.
- Name
bank_account_ids- Type
- array of integers
- Description
The Business’s bank accounts the Client pays into, by
id, in the order the document shows them.
- Name
proforma_id- Type
- integer or null
- Description
The Proforma Invoice this document was converted from, by
id.nullwhen it was made from none. That Proforma Invoice’sconverted_into_idnames this document.
- Name
converted_into_id- Type
- integer or null
- Description
On a Proforma Invoice, the Invoice it was converted into, by
id— a Draft included: a Draft made from it already converts it, so it takes no Payment of its own.nullon a Proforma Invoice never converted, and on every other document. That Invoice’sproforma_idnames this Proforma Invoice.
- Name
last_sent- Type
- object or null
- Description
The newest time it was sent, while it is marked sent:
at(when),recipients(the To list the email went to — a Test business’s goes to its Owner; empty when it was marked as sent by hand) andvia—essentio(Essentio’s own mail server),gmail,microsoft(Outlook),smtp, ormarked(marked as sent by hand in Essentio).nullwhen it was never sent, once its sent mark is cleared in Essentio, whose History keeps every send it recorded, and on a document sent before Essentio recorded sends (October 2026): nobody knows to whom or how it went.
- Name
public_url- Type
- string or null
- Description
The page in Essentio where the Client opens the document.
nullon a Draft, which has none.
- Name
amount_due- Type
- string or null
- Description
Total − Prepaid − Payments: what the Client still owes.
nullwhere the document asks nobody for money — a Draft, a Cancelled document, a Credit Note, a Quote, and a Proforma Invoice converted into an Invoice, whose Invoice carries the debt. A Paid document still states it.
- Name
prepaid- Type
- string
- Description
What the Proforma Invoice this Invoice was converted from was paid.
"0.00"for any other document.
- Name
payments_total- Type
- string
- Description
The sum of the document’s own Payments; a reversed Payment counts nowhere.
- Name
shows_amount_due, shows_prepaid, shows_payments- Type
- boolean
- Description
Whether the document’s page, PDF and email state its Amount due, its Prepaid and its Payments.
- Name
still_takes_payment- Type
- boolean
- Description
Whether a Payment can be recorded against it now.
- Name
actions- Type
- object
- Description
What your key may do with the document now:
issue,send,cancel,convert,record_paymentanddelete, each{ "open": true, "code": null, "remedy": null }when taking it would be done, or with the Refusal code taking it would answer —role_forbiddenwhen your key’s Role may not take it — and itsremedy. With the remedyrecord_on_its_invoice,invoice_idnames the Invoice to record the Payment on; with the remedyconnect_mail_provider,remedy_urlis the page in Essentio where the Business connects its mail account, and withchoose_planthe page where its Owner chooses a plan, for a person signed in to Essentio who belongs to it.
- Name
created_at- Type
- timestamp
- Description
When the document was created, in UTC.
- Name
updated_at- Type
- timestamp
- Description
When the document last changed, in UTC.
List documents
Lists the Business’s documents of every type, Drafts included, a page at a time, oldest first — paged as every list is (Pagination). Send the same filters with every page. Every Role may read them, a Viewer’s key included.
Query parameters
- Name
limit- Type
- integer
- Description
How many documents a page holds: 1 to 100. Not sent: 25.
- Name
cursor- Type
- string
- Description
The
next_cursorof the page before. Not sent: the first page.
- Name
document_type- Type
- string
- Description
Only documents of this type:
invoice,proforma,credit_noteorquote.
- Name
status- Type
- string
- Description
Only documents in this state:
draft,issued,partially_paid,paid,cancelled, oroverdue— issued Invoices and Proforma Invoices never converted, past their due date, neither paid nor cancelled — orawaiting_payment: every document that still takes a Payment, those whosestill_takes_paymentistrue. That is the issued and partially paid Invoices and Proforma Invoices never converted with an amount due, overdue ones included, in one list; never a Draft, a Credit Note, a Quote, a converted Proforma Invoice, a paid or a cancelled document.
- Name
client_id- Type
- integer
- Description
Only the documents of this Client.
- Name
issued_from- Type
- date
- Description
Only documents issued on or after this day,
YYYY-MM-DD. A Draft has no issue date, so a period leaves every Draft out.
- Name
issued_to- Type
- date
- Description
Only documents issued on or before this day,
YYYY-MM-DD, not beforeissued_from.
- Name
search- Type
- string
- Description
Only the documents whose number or notes, or whose Client’s name, legal name or email, contains this text, in any case.
Answers
- Name
200- Type
- DocumentList
- Description
data: the page’s documents.next_cursor: where the next page starts, ornullon the last.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
422- Type
- Error
- Description
A filter the list cannot read — an unknown type or state, a day not written
YYYY-MM-DD, a period ending before it starts — alimitout of range, or acursorthis API did not give. A filter is refused, never ignored.
Request
curl -G https://api.essentio.pro/v1/documents \
-H "Authorization: Bearer ess_your_api_key" \
-d document_type=invoice \
-d status=overdue
Create a Draft
Creates a Draft of any of the four types, held to the same rules as the document editor in Essentio, in its words. An Admin’s or Member’s key may create; a Viewer’s may not. Send an Idempotency-Key to retry safely (see Idempotency).
Body
- Name
document_type- Type
- string
- Description
Required.
invoice,proforma,credit_noteorquote.
- Name
client_id- Type
- integer
- Description
Required. One of the Business’s Clients.
- Name
currency- Type
- string
- Description
Required. ISO 4217, one Essentio computes documents in.
- Name
due_date- Type
- date
- Description
Required. The second date,
YYYY-MM-DD. A Draft still waiting past it is given a fresh one when it is issued.
- Name
supply_date, supply_date_to- Type
- date
- Description
Optional,
YYYY-MM-DD: the day the supply took place, or a supply period’s first and last day.supply_date_toneedssupply_dateand is on or after it; sent equal to it, it is one date. A value that is not a date is refused at its own key; an end with no start, or before its start, atsupply_date_to.
- Name
lines- Type
- array
- Description
Required, at least one. Each Line:
description,quantity,unit_price(VAT excluded) andvat_rate, required;vat_category(not sent:S; onlyScarries a rate above 0),vat_exemption_code(required for a category other thanSandZ),unit(not sent:pcs),product_codeandnotes(at most 500 characters, printed with the Line). Decimals as strings. An error in a Line is keyed by its index,lines.0.quantity, and its words name the Line by its place, counted from 1: “Line 1: Quantity must be greater than 0.” A Line’s Net amount (quantity × unit price) and the document’s Total stay below 1,000,000,000,000,000, which is the most an amount is stored to: past it, the Line is refused under itsunit_price, the Total underlines.
- Name
document_number- Type
- string
- Description
The number the Draft asks to be issued as, instead of the next one. It reserves nothing.
- Name
issue_date- Type
- date
- Description
Optional,
YYYY-MM-DD: the day the Draft is to be issued on, today or an earlier day, today being the Business’s own, in its time zone. A later day is refused atissue_date, and adue_datebefore it atdue_date. Kept asrequested_issue_date; not sent, the Draft is issued on the day it is issued.
- Name
payment_terms- Type
- integer
- Description
Days the due date is counted from, at most 999999. Not sent: the Client’s.
- Name
terms_and_conditions, footer_text, late_fee_rate- Type
- string
- Description
Not sent: the Business’s defaults. Sent as
null: none. A Credit Note or a Quote stores nolate_fee_rate.
- Name
discount_percent, discount_amount- Type
- string
- Description
Optional: a Discount on the whole document, taken off its Subtotal before VAT —
discount_percenta percentage of the Subtotal above 0, at most 100 and two decimals ("10"), ordiscount_amountan amount in the document’s currency above 0, at its minor units and never above the Subtotal ("50.00"). Send one, never both. Only a document whose Lines all share one VAT category, rate and exemption code (one VAT group) takes a Discount. A refusal comes atdiscount, in the editor’s words: “Give the Discount as a percentage or as an amount, not both.”, “A Discount needs all Lines at the same VAT rate and category. Remove the Discount or the other Lines.”, “Discount must not be above the Subtotal.”; a JSON number at its own key.
- Name
notes, internal_notes, client_reference, purchase_order_number, project_reference- Type
- string
- Description
Optional, as in the editor.
- Name
bank_account_ids- Type
- array of integers
- Description
The Business’s bank accounts the Client pays into, by
id, in the order to show them. Another Business’s is refused at its index (bank_account_ids.0).
Answers
- Name
201- Type
- Document
- Description
The Draft created — or, for a retry under the same
Idempotency-Key, the one the first request created.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
403- Type
- Error
- Description
A Viewer’s key.
- Name
422- Type
- Error
- Description
A field the rules refused (
invalid_request, each field inerrors), or anIdempotency-Keysent with another body (idempotency).
Request
curl https://api.essentio.pro/v1/documents \
-H "Authorization: Bearer ess_your_api_key" \
-H "Idempotency-Key: order-10427" \
-H "Content-Type: application/json" \
-d '{
"document_type": "invoice",
"client_id": 42,
"currency": "EUR",
"due_date": "2026-10-27",
"bank_account_ids": [3],
"lines": [
{"description": "Design", "quantity": "3", "unit": "hour", "unit_price": "95.00", "vat_rate": "19"},
{"description": "Print", "quantity": "500", "unit_price": "1.20", "vat_rate": "0", "vat_category": "Z"}
]
}'
Response: 201
{
"id": 118,
"document_type": "invoice",
"status": "draft",
"is_test": false,
"document_number": null,
"requested_document_number": null,
"requested_issue_date": null,
"client_id": 42,
"client": {"id": 42, "name": "Acme Trading"},
"currency": "EUR",
"issue_date": null,
"due_date": "2026-10-27",
"supply_date": null,
"supply_date_to": null,
"is_overdue": false,
"days_overdue": null,
"payment_terms": 30,
"client_reference": null,
"purchase_order_number": null,
"project_reference": null,
"notes": null,
"footer_text": "Registered in Cyprus, HE 123456",
"terms_and_conditions": "Payment within 30 days.",
"late_fee_rate": "1.00",
"internal_notes": null,
"lines": [
{
"id": 301,
"description": "Design",
"quantity": "3.000",
"unit": "hour",
"unit_price": "95.0000",
"vat_rate": "19.00",
"vat_category": "S",
"vat_exemption_code": null,
"product_code": null,
"notes": "Two rounds of revisions",
"net_amount": "285.00"
},
{
"id": 302,
"description": "Print",
"quantity": "500.000",
"unit": "pcs",
"unit_price": "1.2000",
"vat_rate": "0.00",
"vat_category": "Z",
"vat_exemption_code": null,
"product_code": null,
"notes": null,
"net_amount": "600.00"
}
],
"subtotal": "885.00",
"discount_percent": null,
"discount_amount": "0.00",
"subtotal_after_discount": "885.00",
"total_vat": "54.15",
"total": "939.15",
"vat_groups": [
{"category": "S", "rate": "19.00", "exemption_code": null, "net": "285.00", "vat": "54.15"},
{"category": "Z", "rate": "0.00", "exemption_code": null, "net": "600.00", "vat": "0.00"}
],
"bank_account_ids": [3],
"proforma_id": null,
"converted_into_id": null,
"last_sent": null,
"public_url": null,
"amount_due": null,
"prepaid": "0.00",
"payments_total": "0.00",
"shows_amount_due": false,
"shows_prepaid": false,
"shows_payments": false,
"still_takes_payment": false,
"actions": {
"issue": {"open": true, "code": null, "remedy": null},
"send": {"open": true, "code": null, "remedy": null},
"cancel": {"open": false, "code": "draft_not_cancelled", "remedy": null},
"convert": {"open": false, "code": "not_a_proforma", "remedy": null},
"record_payment": {"open": false, "code": "draft_takes_no_payments", "remedy": null},
"delete": {"open": true, "code": null, "remedy": null}
},
"created_at": "2026-09-27T10:15:00+00:00",
"updated_at": "2026-09-27T10:15:00+00:00"
}
Retrieve a document
One document of the Business, of any type and state, by its id. Every Role may read it. A document of another Business, or one that was deleted, is not found.
Answers
- Name
200- Type
- Document
- Description
The document.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
404- Type
- Error
- Description
The Business has no document with this
id.
Request
curl https://api.essentio.pro/v1/documents/118 \
-H "Authorization: Bearer ess_your_api_key"
Update a Draft
Changes the fields sent of a Draft and nothing else, held to the same rules as a create. An Admin’s or Member’s key may update; a Viewer’s may not.
lines, when sent, replaces every Line. Not sent, the Lines stay.due_dateandpayment_termssent asnullkeep their values.supply_date_tosent asnullleaves one date.supply_datesent asnullclears the Supply date of a Draft that holds no end; one that holds asupply_date_tois refused atsupply_date_tounless that is sent asnulltoo. Asupply_date_tosent alone is held to the Draft’ssupply_date, asupply_datesent alone to itssupply_date_to.document_numbersent asnullclears the number the Draft asks for.issue_datesent asnullclears the day the Draft is to be issued on; not sent, it stays. Adue_datesent alone is held on or after the day it holds.bank_account_ids: a list replaces them, in its order;[]clears them.discount_percentordiscount_amount, when either is sent, replaces the Discount — the other read as none — andnullremoves it. Neither sent, the Discount stays, and is held to the Lines sent: Lines in two VAT groups under a kept Discount are refused atdiscount.- A document that is not a Draft is refused with a
422refusal,issued_not_changed: an issued document is changed in Essentio. - A Draft still linked to a Proforma Invoice is issued by its save, and refused when the Proforma does not convert into it:
proforma_deleted,cancelled_not_converted,only_into_an_invoice,proforma_other_currencyorproforma_other_client.
Answers
- Name
200- Type
- Document
- Description
The Draft as it now stands.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
403- Type
- Error
- Description
A Viewer’s key.
- Name
404- Type
- Error
- Description
The Business has no document with this
id.
- Name
422- Type
- Error
- Description
A field the rules refused, each named in
errors(invalid_request); or arefusal: the document is not a Draft (issued_not_changed), the Draft was deleted meanwhile (draft_deleted), the Business became a Non-VAT Payer meanwhile and a Line carries VAT (lines_not_subject_to_vat), or the Proforma Invoice it is linked to does not convert into it.
Request
curl -X PATCH https://api.essentio.pro/v1/documents/118 \
-H "Authorization: Bearer ess_your_api_key" \
-H "Content-Type: application/json" \
-d '{"notes": "Thank you for your order.", "purchase_order_number": "PO-7731"}'
Delete a Draft
Deletes a Draft, as Delete does in Essentio: it leaves the Business’s documents at once, and it took no Document number. Only a Draft is deleted: an issued document keeps its number for good and is cancelled instead. The document’s actions.delete says beforehand whether it would be done. An Admin’s or Member’s key may delete; a Viewer’s may not.
Answers
- Name
204- Type
- none
- Description
The Draft was deleted. No body.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
403- Type
- Error
- Description
A Viewer’s key.
- Name
404- Type
- Error
- Description
The Business has no document with this
id, or it was deleted already.
- Name
422- Type
- Error
- Description
A
refusal:issued_not_deleted.
Request
curl -X DELETE https://api.essentio.pro/v1/documents/118 \
-H "Authorization: Bearer ess_your_api_key"
Issue a Draft
Issues a Draft as Essentio’s Issue does: it takes its Document number — the one it asks for (requested_document_number), else the next of its type’s sequence, stepped past a number another document already holds (the sequence then has a gap there) — and its issue date, and its Lines and totals are frozen. A Draft whose due date is before the day it is issued on is issued due that day plus its payment terms. Nothing is emailed: Send does that. An Admin’s or Member’s key may issue; a Viewer’s may not. Send an Idempotency-Key to retry safely.
issue_date(date,YYYY-MM-DD, optional): the day it 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: with a number pattern that starts again each year or month, a day in an earlier year or month takes the next number of that period’s series. Without it, the Draft is issued on the day it holds (requested_issue_date), else today.- A day after the Business’s today is refused
issue_date_in_the_future, and the Draft stays a Draft.
Answers
- Name
200- Type
- Document
- Description
The document as issued — or, for a retry under the same
Idempotency-Key, what the first request answered.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
403- Type
- Error
- Description
A Viewer’s key.
- Name
404- Type
- Error
- Description
The Business has no document with this
id.
- Name
422- Type
- Error
- Description
A
refusal:already_issued,issue_date_in_the_future,draft_deleted(deleted meanwhile, no number taken), or anumber_*code for the number the Draft asks for — it stays a Draft. Or anissue_datenot writtenYYYY-MM-DD(invalid_request).
Request
curl -X POST https://api.essentio.pro/v1/documents/118/issue \
-H "Authorization: Bearer ess_your_api_key" \
-H "Idempotency-Key: issue-118" \
-H "Content-Type: application/json" \
-d '{"issue_date": "2026-09-21"}'
Send a document
Emails the document to its Client’s address, with its PDF, through the Business’s mailbox, or Essentio’s own mail server when it connected none — as Essentio’s Send does. Through Essentio the email is sent once it is accepted into Essentio’s queue; one Essentio then fails to deliver is listed on the document’s History in Essentio and told to the Business’s Owner. A Draft is issued first. Without a body the email takes the Business’s own subject and message for the type. An Admin’s or Member’s key may send; a Viewer’s may not.
subject(string, one line, at most 255 characters) andmessage(string, at most 2000 characters) replace the Business’s.issue_date(date,YYYY-MM-DD, optional): for a Draft, the day it is issued on before it is sent, as Issue takes it. Without it, the day the Draft holds, else today. An issued document is sent as it is.- A send that could never go out — no Client address, no mail provider, a Cancelled document — is refused before the Draft is issued, so no number is taken.
- Send it with an
Idempotency-Key. A retry of a Send that went out answers the first response and sends nothing again. A Send that did not go out keeps no key, so the retry sends. - A test business’s email goes to its Owner, never the Client.
- A
not_deliveredis rarely final. When the connection to the mail provider failed — it did not answer in time, or dropped — the provider may have taken the email before the connection was lost. A retry then sends it a second time. Check the Client’s inbox, or your provider’s sent mail, before you send again.
Answers
- Name
200- Type
- Document
- Description
The document as it now stands, issued if it was a Draft.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
403- Type
- Error
- Description
A Viewer’s key.
- Name
404- Type
- Error
- Description
The Business has no document with this
id.
- Name
422- Type
- Error
- Description
A
refusal:cancelled_not_sent,no_client_address,no_mail_provider,mail_account_lost,sending_limit_reached,draft_deleted(a Draft deleted meanwhile, nothing sent),issue_date_in_the_future(nothing issued or sent), or anumber_*code for a Draft. Or asubject,messageorissue_datethe rules refused (invalid_request).
- Name
409- Type
- Error
- Description
idempotency_in_flight: a Send under the sameIdempotency-Keyis still being performed.
- Name
502- Type
- Error
- Description
not_delivered: the mail provider did not accept the email, or could not be reached. A Draft the Send issued first stays issued, anderror.document_numbernames its number.
Request
curl -X POST https://api.essentio.pro/v1/documents/118/send \
-H "Authorization: Bearer ess_your_api_key" \
-H "Idempotency-Key: send-118" \
-H "Content-Type: application/json" \
-d '{"subject": "Invoice INV-0042", "message": "Thank you for your order."}'
Cancel a document
Cancels an issued document as Essentio’s Cancel does: it keeps its Document number and leaves every figure. A Draft is deleted instead, and a document holding money is corrected with a Credit Note. An Admin’s or Member’s key may cancel; a Viewer’s may not.
notify_client(boolean, defaultfalse):truealso sends the Client a Cancellation notice once the document is cancelled — an email saying it is cancelled and no longer asks anything of them, with no PDF and a link to its public page. It goes to whoever the document was last emailed to, else the Client’s own address. Without it nobody is emailed, as before.- The notice does not make the document sent:
last_sentis unchanged by it. A test business’s notice goes to its Owner. - A notice that cannot go out leaves the document cancelled. The answer is still
200, and itscancellation_noticesays why:{"sent": false, "code": "no_client_address", "message": "…"}— orno_mail_provider,mail_account_lost,sending_limit_reached, ornot_deliveredwhen the mail provider did not take it.
Answers
- Name
200- Type
- Document
- Description
The document as cancelled, with
cancellation_notice:nullwhen none was asked,{"sent": true, "recipients": […]}when it went, or{"sent": false, "code", "message"}when it did not.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
403- Type
- Error
- Description
A Viewer’s key.
- Name
404- Type
- Error
- Description
The Business has no document with this
id.
- Name
422- Type
- Error
- Description
A
refusal:draft_not_cancelled,paid_not_cancelled,already_cancelledorholds_money.
Request
curl -X POST https://api.essentio.pro/v1/documents/118/cancel \
-H "Authorization: Bearer ess_your_api_key" \
-H "Idempotency-Key: cancel-118" \
-H "Content-Type: application/json" \
-d '{"notify_client": true}'
Convert a Proforma Invoice into its Invoice
Makes the Invoice an issued Proforma Invoice becomes — as Create Invoice from Proforma does in Essentio — and issues it. An Admin’s or Member’s key may convert; a Viewer’s may not.
- The Invoice takes the Proforma’s Client, currency, Lines, notes, footer, Terms & Conditions, Late fee rate and bank accounts, and is due the day it is issued on plus the Client’s payment terms.
issue_date(date,YYYY-MM-DD, optional): the day the Invoice is issued on, as Issue takes it. Without it, the day the Proforma was last paid — its latest Payment’spayment_date, no later than the Business’s today — or today when it holds none. A day after the Business’s today is refusedissue_date_in_the_future, and no Invoice is made.- The Proforma’s Payments are the Invoice’s Prepaid: an Invoice they cover is
paidthe moment it is issued, one they cover in partpartially_paid. - A Proforma converts once. Send an
Idempotency-Key: a retry answers the Invoice the first request made.
Answers
- Name
201- Type
- Document
- Description
The Invoice, issued.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
403- Type
- Error
- Description
A Viewer’s key.
- Name
404- Type
- Error
- Description
The Business has no document with this
id.
- Name
422- Type
- Error
- Description
A
refusal:not_a_proforma,draft_not_converted,cancelled_not_converted,already_convertedorissue_date_in_the_future. Or anissue_datenot writtenYYYY-MM-DD(invalid_request).
Request
curl -X POST https://api.essentio.pro/v1/documents/118/convert \
-H "Authorization: Bearer ess_your_api_key" \
-H "Idempotency-Key: convert-118"
Download a document’s PDF
The document’s PDF — the same file the document page in Essentio downloads, in the Business’s template and with its Branding. A Draft’s PDF reads “No number yet” and “Not issued yet”. A Test business’s documents are marked SAMPLE. Every Role may download it.
Answers
- Name
200- Type
- application/pdf
- Description
The PDF, as an attachment named after the document.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
404- Type
- Error
- Description
The Business has no document with this
id.
Request
curl https://api.essentio.pro/v1/documents/118/pdf \
-H "Authorization: Bearer ess_your_api_key" \
-o invoice.pdf
Download a document’s EN16931 XML
The document as EN16931 UBL 2.1 XML — an Invoice as a UBL Invoice, a Credit Note as a UBL CreditNote — the same file the document page in Essentio exports. Only an issued Invoice or Credit Note that passes the EN16931 check is exported. Every Role may download it.
The file follows EN 16931 itself, and no CIUS or network profile: its cbc:CustomizationID is urn:cen.eu:en16931:2017, and it carries no cbc:ProfileID. What it writes follows the document’s VAT categories, as the standard asks:
- The Business’s identifiers. A VAT payer’s VAT number as
PartyTaxSchemeVAT (BT-31). Where no VAT number is written — a Non-VAT Payer, or a document whose Lines are all not subject to VAT — its TAX ID, when it has one, asPartyIdentification(BT-29) andPartyTaxSchemeTAX (BT-32). Its Registration Number, when it has one, asPartyLegalEntity/CompanyID(BT-30). - The Client’s VAT number. As
PartyTaxSchemeVAT (BT-48) on every document but one whose Lines are allO, when the Client has one. Essentio stores a Client’s VAT number without its country code, as the Client form takes it, so the file writes the Client’s country first, in capitals —ELfor Greece — as inDE987654321. A number stored with two Latin letters first, as an import may store it, has them as its country code, upper-cased (de987654321is writtenDE987654321,GR…asEL…); spaces, dashes and dots and a leadingVATare dropped. - Not subject to VAT (
O). When every Line isO, neither the Business’s nor the Client’s VAT number is written. AnOLine and anOVAT breakdown carry nocbc:Percent; every other category carries its own. - Intra-community supply (
K). A document with aKLine carriescac:Delivery: itssupply_date, else its issue date, as the Actual delivery date (BT-72), and the Client’s country as the Deliver to country (BT-80). One with a supply period carries the period instead (BG-14) and no BT-72. AKdocument whose Client has no country is refusednot_exportable. - The Supply date. On any document, one
supply_dateis the Actual delivery date (BT-72); a period,supply_dateandsupply_date_to, is the Invoicing period (BG-14). The issue date stays the VAT date: BT-7 and BT-8 are not written. - Payment means.
30, credit transfer, with the Business’s bank account (BT-84);1, not defined, when the Business has none.
Answers
- Name
200- Type
- application/xml
- Description
The XML, as an attachment named after the document.
- Name
401- Type
- Error
- Description
No API key, an unknown one or a revoked one.
- Name
404- Type
- Error
- Description
The Business has no document with this
id.
- Name
422- Type
- Error
- Description
A
refusal,not_exportable: the document is not exported — a Draft, a Proforma Invoice or a Quote, or an Invoice or Credit Note the EN16931 check does not pass — anderror.messagesays why, in the words the document page shows. A Test business’s document is refusedexports_not_in_a_test_business.
Request
curl https://api.essentio.pro/v1/documents/118/xml \
-H "Authorization: Bearer ess_your_api_key" \
-o invoice.xml