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 as requested_document_number, and document_number stays null until 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_date stays null until the issue — and the document answers it as requested_issue_date. An Issue or a Send that sends no issue_date of 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 422 refusal, 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 are number_skips_ahead, number_beyond_the_counter, number_malformed, number_of_a_later_period and number_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) and number_of_another_type (a number another document type’s numbering pattern forms), each named in message. The Draft stays a Draft: change or clear its document_number and 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; message names it. The Draft stays a Draft: send an unused earlier number as its document_number and 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_number names 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, message names 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_currency and proforma_other_client, each named in message.

  • 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. message says 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_price and vat_rate, and late_fee_rate, discount_percent and discount_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, and subtotal_after_discount + total_vat = total; without a Discount, subtotal_after_discount is subtotal.
  • 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_note or quote. Another value may be added within v1: keep one you do not know.

  • Name
    status
    Type
    string
    Description

    draft, issued, partially_paid, paid or cancelled. 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. null on a Draft. A Test business’s carries TEST- in front of what its number pattern makes, such as TEST-INV-2026-0007.

  • Name
    requested_document_number
    Type
    string or null
    Description

    The number a Draft asks to be issued as. null when 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. null when 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 id and name, 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. null on 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. null when 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 by issue_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. null for 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_date before today. A Draft, a Paid or Cancelled document, a Credit Note, a Quote and a converted Proforma Invoice never are. Overdue is not a status: the document keeps its own.

  • Name
    days_overdue
    Type
    integer or null
    Description

    How many days ago its due_date was, while is_overdue is true. null whenever 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". null on 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, or null) and net_amount. A Line’s id changes 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". null when 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 subtotal when 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) and vat.

  • 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. null when it was made from none. That Proforma Invoice’s converted_into_id names 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. null on a Proforma Invoice never converted, and on every other document. That Invoice’s proforma_id names 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) and via — essentio (Essentio’s own mail server), gmail, microsoft (Outlook), smtp, or marked (marked as sent by hand in Essentio). null when 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. null on a Draft, which has none.

  • Name
    amount_due
    Type
    string or null
    Description

    Total − Prepaid − Payments: what the Client still owes. null where 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_payment and delete, each { "open": true, "code": null, "remedy": null } when taking it would be done, or with the Refusal code taking it would answer — role_forbidden when your key’s Role may not take it — and its remedy. With the remedy record_on_its_invoice, invoice_id names the Invoice to record the Payment on; with the remedy connect_mail_provider, remedy_url is the page in Essentio where the Business connects its mail account, and with choose_plan the 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.


GET/v1/documents

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_cursor of the page before. Not sent: the first page.

  • Name
    document_type
    Type
    string
    Description

    Only documents of this type: invoice, proforma, credit_note or quote.

  • Name
    status
    Type
    string
    Description

    Only documents in this state: draft, issued, partially_paid, paid, cancelled, or overdue — issued Invoices and Proforma Invoices never converted, past their due date, neither paid nor cancelled — or awaiting_payment: every document that still takes a Payment, those whose still_takes_payment is true. 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 before issued_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, or null on 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 — a limit out of range, or a cursor this API did not give. A filter is refused, never ignored.

Request

GET/v1/documents
curl -G https://api.essentio.pro/v1/documents \
  -H "Authorization: Bearer ess_your_api_key" \
  -d document_type=invoice \
  -d status=overdue

/v1/documents

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_note or quote.

  • 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_to needs supply_date and 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, at supply_date_to.

  • Name
    lines
    Type
    array
    Description

    Required, at least one. Each Line: description, quantity, unit_price (VAT excluded) and vat_rate, required; vat_category (not sent: S; only S carries a rate above 0), vat_exemption_code (required for a category other than S and Z), unit (not sent: pcs), product_code and notes (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 its unit_price, the Total under lines.

  • 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 at issue_date, and a due_date before it at due_date. Kept as requested_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 no late_fee_rate.

  • Name
    discount_percent, discount_amount
    Type
    string
    Description

    Optional: a Discount on the whole document, taken off its Subtotal before VAT — discount_percent a percentage of the Subtotal above 0, at most 100 and two decimals ("10"), or discount_amount an 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 at discount, 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 in errors), or an Idempotency-Key sent with another body (idempotency).

Request

POST/v1/documents
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"
}

GET/v1/documents/{document}

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

GET/v1/documents/118
curl https://api.essentio.pro/v1/documents/118 \
  -H "Authorization: Bearer ess_your_api_key"

PATCH/v1/documents/{document}

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_date and payment_terms sent as null keep their values.
  • supply_date_to sent as null leaves one date. supply_date sent as null clears the Supply date of a Draft that holds no end; one that holds a supply_date_to is refused at supply_date_to unless that is sent as null too. A supply_date_to sent alone is held to the Draft’s supply_date, a supply_date sent alone to its supply_date_to.
  • document_number sent as null clears the number the Draft asks for.
  • issue_date sent as null clears the day the Draft is to be issued on; not sent, it stays. A due_date sent alone is held on or after the day it holds.
  • bank_account_ids: a list replaces them, in its order; [] clears them.
  • discount_percent or discount_amount, when either is sent, replaces the Discount — the other read as none — and null removes it. Neither sent, the Discount stays, and is held to the Lines sent: Lines in two VAT groups under a kept Discount are refused at discount.
  • A document that is not a Draft is refused with a 422 refusal, 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_currency or proforma_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 a refusal: 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

PATCH/v1/documents/118
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/v1/documents/{document}

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

DELETE/v1/documents/118
curl -X DELETE https://api.essentio.pro/v1/documents/118 \
  -H "Authorization: Bearer ess_your_api_key"

/v1/documents/{document}/issue

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 a number_* code for the number the Draft asks for — it stays a Draft. Or an issue_date not written YYYY-MM-DD (invalid_request).

Request

POST/v1/documents/118/issue
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"}'

/v1/documents/{document}/send

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) and message (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_delivered is 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 a number_* code for a Draft. Or a subject, message or issue_date the rules refused (invalid_request).

  • Name
    409
    Type
    Error
    Description

    idempotency_in_flight: a Send under the same Idempotency-Key is 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, and error.document_number names its number.

Request

POST/v1/documents/118/send
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."}'

/v1/documents/{document}/cancel

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, default false): true also 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_sent is 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 its cancellation_notice says why: {"sent": false, "code": "no_client_address", "message": "…"} — or no_mail_provider, mail_account_lost, sending_limit_reached, or not_delivered when the mail provider did not take it.

Answers

  • Name
    200
    Type
    Document
    Description

    The document as cancelled, with cancellation_notice: null when 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_cancelled or holds_money.

Request

POST/v1/documents/118/cancel
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}'

/v1/documents/{document}/convert

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’s payment_date, no later than the Business’s today — or today when it holds none. A day after the Business’s today is refused issue_date_in_the_future, and no Invoice is made.
  • The Proforma’s Payments are the Invoice’s Prepaid: an Invoice they cover is paid the moment it is issued, one they cover in part partially_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_converted or issue_date_in_the_future. Or an issue_date not written YYYY-MM-DD (invalid_request).

Request

POST/v1/documents/118/convert
curl -X POST https://api.essentio.pro/v1/documents/118/convert \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: convert-118"

GET/v1/documents/{document}/pdf

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

GET/v1/documents/118/pdf
curl https://api.essentio.pro/v1/documents/118/pdf \
  -H "Authorization: Bearer ess_your_api_key" \
  -o invoice.pdf

GET/v1/documents/{document}/xml

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 PartyTaxScheme VAT (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, as PartyIdentification (BT-29) and PartyTaxScheme TAX (BT-32). Its Registration Number, when it has one, as PartyLegalEntity/CompanyID (BT-30).
  • The Client’s VAT number. As PartyTaxScheme VAT (BT-48) on every document but one whose Lines are all O, 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 — EL for Greece — as in DE987654321. A number stored with two Latin letters first, as an import may store it, has them as its country code, upper-cased (de987654321 is written DE987654321, GR… as EL…); spaces, dashes and dots and a leading VAT are dropped.
  • Not subject to VAT (O). When every Line is O, neither the Business’s nor the Client’s VAT number is written. An O Line and an O VAT breakdown carry no cbc:Percent; every other category carries its own.
  • Intra-community supply (K). A document with a K Line carries cac:Delivery: its supply_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. A K document whose Client has no country is refused not_exportable.
  • The Supply date. On any document, one supply_date is the Actual delivery date (BT-72); a period, supply_date and supply_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 — and error.message says why, in the words the document page shows. A Test business’s document is refused exports_not_in_a_test_business.

Request

GET/v1/documents/118/xml
curl https://api.essentio.pro/v1/documents/118/xml \
  -H "Authorization: Bearer ess_your_api_key" \
  -o invoice.xml