Skip to main content
Base gives you two ways to handle invoices. It can issue an invoice itself using its own numbering series, or it can accept a ready-made invoice issued by your external ERP or accounting system and attach it to an order. Both approaches are fully supported and can be mixed across different order sources.

​
Issuing an invoice in Base

addInvoice issues an invoice for an order using a chosen numbering series configured in your Base account.
This invoicing model is built around VAT concepts (numbering series, VAT-exempt/reverse-charge rates, and so on) and doesn’t have a dedicated US sales-tax model (no sales_tax_rate or state/county/city tax structure). If you need accurate US sales-tax handling, treat your own ERP or accounting system as the source of truth for invoicing rather than relying on Base’s VAT-oriented fields (see Replacing with an invoice from your ERP below).

​
Gross vs. net terminology

Base uses VAT-style field names throughout the API. In general pricing terms: net refers to a pre-tax amount, gross refers to a tax-inclusive amount, and vat_rate is the tax rate value stored for the product or order. This is field-naming and semantics only; Base does not confirm or provide a US-specific sales-tax model or a legal equivalence between VAT and US sales tax. Merchants remain responsible for determining how these values apply to their own tax obligations, including US sales-tax compliance. Treat your own ERP or accounting system as the source of truth where that matters (see Replacing with an invoice from your ERP above).
You may separately encounter numeric values like -1, -0.02, or -0.03 in tax-related data. These are internal encodings used at the product/order-line-item level (-1 = exempt, -0.02 = NP, -0.03 = OO), not valid input for vat_rate here. addInvoice’s vat_rate only accepts a numeric value 0–100 or one of the string sentinels listed above; use the strings, not the numeric encodings, when calling this method.
The response returns invoice_id, which you then use to download the file via getInvoiceFile or list invoices via getInvoices.

​
Replacing with an invoice from your ERP

If you issue invoices in your own ERP and don’t want to duplicate numbering across both systems, use addOrderInvoiceFile. It replaces the standard Base invoice with your own PDF (or XML, for jurisdictions that require it).
When using an external ERP, follow these steps for each order:
1

Issue the invoice in your ERP

Your ERP generates the invoice, producing both the invoice number and the PDF.
2

Create a placeholder invoice in Base

Call addInvoice for the order. You just need a valid series_id; the number and VAT rate don’t matter much here since you’ll overwrite them in the next step.
3

Attach your ERP invoice to Base

Call addOrderInvoiceFile with the invoice_id from step 2, the PDF from your ERP (base64 with "data:" prefix), and external_invoice_number set to your real invoice number.
4

Forward to the marketplace

Forwarding the invoice to the marketplace (where the integration supports it) is typically tied to a specific order status. This is configured per integration and runs in batches, not instantly. Timing follows the same pattern as tracking number delivery.
If you have complex numbering-series logic (different cost centers, states, or tax jurisdictions), consider driving it via extra fields rather than hardcoded rules in your integration. Updating a rule then only requires a change in Base, not a code deployment.