> ## Documentation Index
> Fetch the complete documentation index at: https://api.basedock.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices: Issue in Base.com or Attach from Your ERP

> Issue invoices in Base.com or attach a PDF from your external ERP. Covers addInvoice, addOrderInvoiceFile, getSeries, and the 4-step integration flow.

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`](https://api.baselinker.com/index.php?method=addInvoice) issues an invoice for an order using a chosen numbering series configured in your Base account.

| Parameter   | Type | Description                                                                                                                                                                          |
| ----------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `order_id`  | int  | Order ID.                                                                                                                                                                            |
| `series_id` | int  | Numbering series ID — list available series with [`getSeries`](https://api.baselinker.com/index.php?method=getSeries).                                                               |
| `vat_rate`  | text | Optional. `"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. |

```json theme={null}
{ "order_id": 4553562, "series_id": 1 }
```

The response returns `invoice_id`, which you then use to download the file via [`getInvoiceFile`](https://api.baselinker.com/index.php?method=getInvoiceFile) or list invoices via [`getInvoices`](https://api.baselinker.com/index.php?method=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`](https://api.baselinker.com/index.php?method=addOrderInvoiceFile). It replaces the standard Base invoice with your own PDF (or XML, for countries where that's required, such as Brazil).

| Parameter                 | Type        | Description                                                               |
| ------------------------- | ----------- | ------------------------------------------------------------------------- |
| `invoice_id`              | int         | Base invoice ID — must already exist, e.g. created via `addInvoice`.      |
| `file`                    | text        | PDF (or XML) encoded as base64, with a required `"data:"` prefix.         |
| `external_invoice_number` | varchar(30) | Invoice number from your system — overwrites the number assigned by Base. |

```json theme={null}
{
  "invoice_id": 153845,
  "file": "data:4AAQSkZJRgABA[...]",
  "external_invoice_number": "FV/2024/001"
}
```

## Recommended flow

When using an external ERP, follow these steps for each order:

<Steps>
  <Step title="Issue the invoice in your ERP">
    Your ERP generates the invoice — producing both the invoice number and the PDF.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/orders/automation-and-webhooks).
  </Step>
</Steps>

<Tip>
  If you have complex numbering-series logic — different cost centers, countries, or VAT regimes — consider driving it via [extra fields](/orders/extra-fields) rather than hardcoded rules in your integration. Updating a rule then only requires a change in Base, not a code deployment.
</Tip>