Disbursements

A suplido is a sum paid in the name and on behalf of the customer, under their express mandate (art. 78.Tres.3 of the Spanish VAT act). It is not part of what you charge for your service: you advance it, you pass it on at cost, and it never becomes your taxable base.

Invoiced as an ordinary line, the same amount inflates your taxable base, your output VAT, the total you declare to the AEAT and the base you report for that customer in the annual third-party return (Modelo 347). Invoiced as a disbursement, it appears on the document, the customer pays it, and it stays outside all four.

When this applies

Only on issued invoices. Quotes, pro-formas, delivery notes, purchase invoices and recurring templates do not model disbursements at all — their line tables have no such column (BR-INV-037). A recurring template in particular could not carry the mandatory origin reference, so the line would silently degrade into an ordinary operation and every generated invoice would declare it as your own revenue.

Two further restrictions:

• A simplified invoice cannot carry one. The mandatory content of a simplified invoice does not identify the recipient, so it cannot prove on whose behalf the amount was paid, and the tax authority would treat it as your taxable base. Its corrective is refused for the same reason. Issue a complete invoice or drop the line (BR-INV-040).
• An invoice cannot be made of disbursements alone. At least one ordinary line is required (BR-INV-046).

What the API sends

Four optional line fields on POST /v1/invoices, PUT /v1/invoices/{id} and POST /v1/invoices/{id}/corrective:

curl -X POST https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer fact_live_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "0197a2a8-4cf0-7a31-9a5e-3f2b8c1d6e42",
        "series_id": "019e5584-7a72-7038-a8f6-561ed180b699",
        "issued_on": "2026-06-01",
        "due_on": "2026-07-01",
        "lines": [
          { "description": "Honorarios de constitución de sociedad", "quantity": 1, "unit_price": 1000, "tax_rate": 21 },
          { "description": "Tasa del Registro Mercantil",
            "quantity": 1, "unit_price": 150,
            "line_type": "SUPLIDO",
            "source_invoice_reference": "RM-2026-0451" }
        ]
      }'

POST /v1/invoices has no type field, so it cannot issue a simplified invoice; the simplified-invoice refusal is therefore reachable only through the corrective endpoint on a simplified original. See Simplified or full invoices.

The origin reference is mandatory, and it is text

It is free text rather than a foreign key because the supporting document — a court fee, a registry duty, a visa — is rarely registered as a purchase invoice in Factuarea. Without it you cannot prove the expense belongs to the customer (BR-INV-038).

source_invoice_ids is the optional structured counterpart, and the rule of thumb is worth internalising:

If the supporting document is in your name, it is not a disbursement. Invoice it as an ordinary line.

The canonical disbursement has the document issued to the customer, so it is not a purchase of yours and the list stays empty. Link purchase invoices only when you genuinely registered the payment in your own books as support for the advance — and remember that the input VAT on such an invoice must not be deducted.

A disbursement line carries no tax of its own

Eight fields are refused on a SUPLIDO line with a non-zero or non-null value (BR-INV-039):

The error names the offending field, and carries it as offending_field in the error details.

Because a disbursement line cannot reference a product, the stock ledger ignores it by construction: the persisted row has no product and is already filtered out.

The line checksum

lines[].line_total is an optional input checksum. When present it is compared against the total the engine has just calculated, and the request is rejected if the deviation exceeds one cent (BR-INV-044). The error details carry the expected and received values so you can locate a rounding mismatch with your ERP without parsing the message.

Three properties, all deliberate:

• Never persisted, never returned. There is no such column and no resource emits it. The amount invoiced is always the one Factuarea computes.
• Never mandatory, in any scenario. Requiring it would force you to replicate our calculation engine, which is explicitly out of scope.
• The one-cent tolerance is inclusive. A deviation of exactly 0,01 € passes; 0,02 € fails. The comparison is done in arbitrary-precision arithmetic, not floating point — float error is precisely what this field exists to diagnose.

Errors

All 422:

The index in the message is zero-based over the complete line collection, so it matches the lines.{i} path of your payload.

What the totals look like

The totals calculator partitions lines by type (BR-INV-041):

For the invoice above: subtotal 1000, VAT 210, total 1210, disbursements 150, amount to pay 1360.

There is exactly one place in the code where those two terms are added, and every consumer — API resources, the PDF, the public document link — reads the derived value instead of recomposing the sum. Two columns called "total" would drift.

Every per-invoice figure that measures debt uses the payable amount, not the fiscal total (BR-INV-045): pending_amount is total_to_pay − paid_amount, the payment ledger accepts a payment covering the full payable amount without answering "exceeds pending", the transition to paid needs the payable amount covered — paying only the fiscal total leaves the invoice unpaid with the disbursement outstanding — and the three online payment links charge the payable amount.

The aggregate portfolio figures are the documented exception: they measure invoiced volume rather than amount owed. That boundary, and the one affecting the Facturae and UBL documents, are listed in Scope and limitations.

An invoice without disbursements has total_disbursements: 0 and total_to_pay == total, to the cent, including every historical invoice.

What appears on the PDF

The disbursement is printed — the customer paid it and the invoice is the legal representation of that — but marked as what it is (BR-INV-042): the line shows a dash in the VAT column, and the totals block gains a Suplidos row and a Total a pagar row below the fiscal total.

The public document link shows the same. The line-level spreadsheet export adds a line-type column, because without it a disbursement is indistinguishable from a 0% VAT operation and summing the line-total column would give the amount collected rather than the declarable revenue.

Two presentation-only line fields help here and have no fiscal effect at all (BR-INV-043): unit, a free-text unit of measure printed next to the quantity, and exemption_reason_text, free text printed under the description for the exemption wording when the catalogued cause does not cover it.

What reaches the AEAT

Nothing. A disbursement line never reaches the VeriFactu billing record: not in the tax breakdown, not in the declared total (BR-VFC-036).

The exclusion happens at a single point, the read gateway, upstream of the breakdown builder — so the same filtered set feeds every consumer: the line array, the aggregate VAT rate, the operation description, the regime key and the XML generator. Filtering only the line array would have left the other paths open: a disbursement in first position donated a 0% rate to the aggregate of an invoice that does charge VAT, and described the operation to the AEAT as "Registry fee…".

The declared total is unchanged in formula and excludes disbursements by construction, because the fiscal total aggregates ordinary lines only. The AEAT validates that total against the sum of the breakdown; adding the disbursement would unbalance the record and get it rejected. The amount to pay is presentation and is never transmitted.

In the annual third-party operations return, the base declared for each counterparty is (BR-TXR-023):

base = total invoiced (VAT included) + IRPF withholding − disbursements

The withholding adds — the counterparty received an invoice for the gross amount — and the disbursement subtracts, because you only passed it on for your customer's account. Inverting either sign misdeclares the counterparty. While the disbursement term was a hard-coded zero, the return over-declared every customer to whom fees or duties had been passed on, risking a mismatch against their own cross-declaration.

Purchase invoices model neither withholding nor disbursements, so both terms are structurally zero on the received side.

Whether a counterparty is declared at all is decided on the contact, not on the invoice. accumulate_347 on the customer — writable over v1 on POST /v1/clients and PUT /v1/clients/{id}, default true — excludes every operation of that customer when set to false, and it is read live when the return is computed rather than frozen at issue time (BR-TXR-037).

The older per-invoice flag survives as a dormant override, exposed read-only in the v1 invoice object as exclude_347: it can force the exclusion of a single invoice, never re-include a counterparty already marked as non-accumulating, and the public API does not set it (BR-TXR-024). Neither flag re-includes what the automatic rules already excluded — intra-community operations, exports, and simplified invoices with no tax ID.

Traceability

Derived from the domain rules of the Factuarea backend:

• BR-INV-037 — the closed NORMAL|SUPLIDO line-type catalogue, its backward-compatible default, and why it exists only on issued invoices.
• BR-INV-038 — the mandatory origin reference, the optional purchase-invoice traceability, and the two legal conditions the software cannot enforce.
• BR-INV-039 — the eight fields a disbursement line may not carry.
• BR-INV-040 — no disbursements in a simplified invoice or its corrective.
• BR-INV-041 — disbursements outside base, VAT and total; the persisted aggregate and the single derived payable-amount formula.
• BR-INV-042 — which surfaces exclude the disbursement and which show it marked.
• BR-INV-043 — unit and exemption_reason_text as presentation-only fields.
• BR-INV-044 — line_total as an optional, never-persisted input checksum with an inclusive one-cent tolerance.
• BR-INV-045 — outstanding balance measured against the payable amount.
• BR-INV-046 — an invoice may not consist of disbursements alone.
• BR-VFC-036 — disbursements never reach the billing record, and the identical fingerprint invariant for invoices without them.
• BR-TXR-023 — the third-party return base: invoiced total plus withholding minus disbursements.
• BR-TXR-037 — accumulation in that return decided on the contact, read live, with the per-invoice flag reduced to a dormant override.
• BR-TXR-024 — the per-document exclusion flag, superseded by BR-TXR-037 and preserved as that override.