Skip to main content
Base can either issue an invoice itself, or take a ready-made invoice issued externally (typically in your ERP/accounting system) and attach it to an order.

​
Issuing an invoice in Base

addInvoice issues an invoice for an order using a chosen numbering series.
ParameterTypeDescription
order_idintOrder ID.
series_idintNumbering series ID — list available series with getSeries.
vat_ratetextOptional. "DEFAULT" (per numbering series), "ITEM" (rate from the order line item), "EXPT"/"ZW" (VAT exempt), "NP", "OO" (reverse charge), or a specific number 0–100.
{ "order_id": 4553562, "series_id": 1 }
The response returns invoice_id, which you then use for downloading the file (getInvoiceFile) or listing invoices (getInvoices).

​
Replacing it with an invoice from an external system

If you issue invoices in your own ERP (and don’t want to duplicate numbering in both Base and your system), use addOrderInvoiceFile — it replaces the standard Base invoice with your own PDF (or XML, for countries where that’s allowed, e.g. Brazil).
ParameterTypeDescription
invoice_idintBase invoice ID (must already exist — e.g. created via addInvoice).
filetextPDF (or XML) in base64, with a required "data:" prefix.
external_invoice_numbervarchar(30)Invoice number from your system — overwrites the number assigned by Base.
{
  "invoice_id": 153845,
  "file": "data:4AAQSkZJRgABA[...]",
  "external_invoice_number": "FV/2024/001"
}
  1. Your ERP issues an invoice (number, PDF).
  2. In Base, create an invoice for the order via addInvoice (you just need a valid series_id — the specific number/rate doesn’t matter much since you’ll overwrite it shortly).
  3. Call addOrderInvoiceFile with the invoice_id from step 2, attach the PDF from your ERP, and set external_invoice_number to the real number from your system.
  4. Forwarding the invoice further to the marketplace (if the integration supports it) is typically tied to a specific order status — configured per integration, similar to tracking numbers. Timing (batches, not instant) is described in Automation and webhooks.
If you have more complex numbering-series logic (different cost centers, countries, VAT regimes), consider driving it via extra fields rather than hardcoded rules in the integration — it’s easier to maintain. Discuss non-trivial scenarios with the implementation team.