Working with invoices

Issued is not sent

Issuing and delivering an invoice are two separate facts. Issuing is the fiscal act: the invoice gets its definitive series number, its VeriFactu record and its stock movements, and its status becomes issued. Sending means the customer received it: an email accepted by the mail server or a delivery you record yourself. It lives in its own fields (is_sent, sent_at, sent_via), independent of the status and of payment.

• Issue a draft without emailing it with POST /v1/companies/{company}/invoices/{invoice}/issue, or issue and email it in one step with POST /v1/companies/{company}/invoices/{invoice}/send.
• Record a delivery made through your own channel with POST /v1/companies/{company}/invoices/{invoice}/mark-sent, and clear it with POST /v1/companies/{company}/invoices/{invoice}/unsend.
• Filter the invoices still to be delivered with GET /v1/companies/{company}/invoices?status=issued&is_sent=false.
• Choose what each run of a recurring invoice does with generation_mode: draft, issue or issue_and_send.

This vocabulary requires the API version 2026-10-01. Earlier versions, including the default one, publish an issued invoice as sent and put the issuance instant in sent_at. See Versioning and the release notes.

VAT of a line without a rate

A sales line takes its VAT from the first source that has one: the tax_rate you declare (a 0 is a real 0 % rate), the tax the line references, the tax of its product and, if there is none, the default VAT of the company for that kind of document (invoice, quote, proforma, delivery note or recurring invoice). If the company has no default either, the request is rejected with 422 missing_required_param, error.param: lines.2.tax_rate and error.line_index: 2, the zero-based position of the line.

Domain errors that come from one line of a document carry the same line_index (error.line_index in the API, error.data.line_index in MCP), so you know which line to fix without reading the message.

Prices with VAT included

When the amounts you hold are the final prices your customer paid, send prices_include_tax: true in POST /v1/companies/{company}/invoices. Each unit_price is then the final price, and Factuarea computes the net base to the cent so that the total of the invoice equals the sum of the amounts you sent. When the cents cannot be absorbed by a line, the largest one is split in two and the total stays exact; if it cannot be reached at all (a withholding or a surcharge moves it), the request is rejected with 422 amount_reconciliation_failed and nothing is issued. Catalog lines (product_id) are not accepted in this mode. The details are in Unattended checkout invoicing.

The shipping cost of a proforma is also an amount with VAT included: it is not added to the base, and when the proforma is converted to an invoice it becomes a line whose base is shipping_cost / (1 + r), with VAT r, so that the invoice total equals the total with shipping shown on the proforma.

Record the payment with the invoice

payment (method, and optionally paid_at and reference, for example the transaction of the card terminal) registers the payment of the whole amount right after issuing. It implies issuing, and the invoice ends up paid. With options.register_verifactu the VERI*FACTU registration is generated in the same call, before the response.

An invoice that was issued by mistake and already has payments cannot be annulled unless you ask for it: POST /v1/companies/{company}/invoices/{invoice}/annul with revert_collections: true reverts every live payment (with the reserved reason issued_in_error) and annuls the invoice in one atomic operation. If a step fails, nothing is reverted. It is an annulment, not a refund: when the customer has to get the money back, issue a corrective invoice. GET /v1/companies/{company}/invoices/{invoice}/can-annul reports requires_collection_reversal and the active_collections_amount beforehand.

Date of the operation

When the operation took place on a day other than the issue date, send operation_on (operation_date in the app). It follows articles 6.1.f and 7.1.c of RD 1619/2012:

• You can set or change it while the invoice is a draft, and it is immutable once issued.
• It cannot be later than issued_on (422 operation_date_after_issue_date), unless the first line that declares a regime_key uses 14 or 15.
• A corrective invoice inherits the date of the invoice it corrects.
• It is printed next to the issue date on the PDF and on the public page, and declared in the VeriFactu record as FechaOperacion. It does not change the fingerprint of any existing record.
• The invoice resource returns it as operation_on.