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

# Create invoices in accounting

> The API calls to book customer and supplier invoices in your end-users' accounting software with the Accounting API.

This guide explains the API calls to book customer and supplier invoices in the accounting software of your end-users. For the business context (what an invoice becomes in the books, and who configures what), read the [Invoices to accounting](https://docs.chift.eu/use-cases/invoices-to-accounting.md) use case first.

> [!NOTE]
>
> Your end-user, or their accountant, makes the accounting choices: which journal, VAT code and ledger account each invoice uses. You build the mapping screen where they make these choices, and the logic that sends the invoices.

## 1. Fetch the mapping data

Fetch these lists when the end-user connects their accounting software. Show them in your mapping screen. Store the selections of the end-user for each consumer.

### Journals

Every invoice belongs to a [journal](https://docs.chift.eu/unified-apis/accounting/concepts/journal.md). Call [Get journals](https://docs.chift.eu/api-reference/endpoints/accounting/get-journals.md).

* Store the `id`. You send it as `journal_id` on the invoice.
* Show the `name` and the `code`.
* Filter on `journal_type`. Your end-user selects one journal for each invoice type: `customer_invoice`, `customer_refund`, `supplier_invoice` and `supplier_refund`.
* Hide the journals where `blocked` is `true`. Entries cannot be created in a blocked journal.

### VAT codes

Accounting software does not record a VAT rate directly. It uses a [VAT code](https://docs.chift.eu/unified-apis/accounting/concepts/vat-codes.md). Call [Get VAT codes](https://docs.chift.eu/api-reference/endpoints/accounting/get-vat-codes.md).

* Store the `id`. You send it as `tax_code` on each invoice line.
* Show the `label` and the `rate`.
* Filter on `type`. Show the codes of type `sale` or `both` for customer invoices, and the codes of type `purchase` or `both` for supplier invoices.
* Hide the codes where `active` is `false`.

Your end-user maps each VAT rate of your software to a sales code and to a purchase code.

### Ledger accounts

Each invoice line books on a [ledger account](https://docs.chift.eu/unified-apis/accounting/concepts/ledger-account.md): a revenue account for a sale, an expense account for a purchase. Call [Get chart of accounts](https://docs.chift.eu/api-reference/endpoints/accounting/get-chart-of-accounts.md) with the `type` filter:

* `type=income` for the revenue accounts.
* `type=expense` for the expense accounts.

Store the `number`. You send it as `account_number` on each invoice line. Hide the accounts where `active` is `false`.

Your end-user selects at least one default revenue account and one default expense account. They can also map each of your product or expense categories to its own account.

### Rounding correction

Your end-user also selects the data that Chift uses to correct a rounding difference of 0.01 (see [Amounts](#amounts)):

* a credit account and a debit account, from the chart of accounts;
* a 0% VAT code of type `sale` and a 0% VAT code of type `purchase`.

## 2. Link your customers and suppliers

Each invoice references its client or supplier in the accounting software with `partner_id`. Chift uses this partner to book the receivable or payable line. So get the `partner_id` before you book an invoice:

1. Match your customer or supplier with an existing [partner](https://docs.chift.eu/unified-apis/accounting/concepts/partner.md) of the accounting software.
2. When no partner matches, create it.

[Synchronize partners](https://docs.chift.eu/unified-apis/accounting/concepts/partner/synchronize-partners.md) explains the matching criteria that Chift advises, and how to create a missing partner.

> [!NOTE]
>
> Some accounting software cannot create partners through the API. For these connectors, send `partner_info` on the invoice, with the `account_number` and the `account_name` of the partner. The accounting software then creates the partner. See for example the [Tiime connector](https://docs.chift.eu/connectors/accounting/tiime.md).

## 3. Create the invoice

Create one invoice for each invoice of your software. Call [Create sale/purchase entry (Multiple plans)](https://docs.chift.eu/api-reference/endpoints/accounting/create-salepurchase-entry-multiple-plans.md):

`POST /consumers/{consumer_id}/accounting/invoices/multi-analytic-plans?regroup_lines=false`

### Invoice fields

* `invoice_type`: `customer_invoice`, `customer_refund`, `supplier_invoice` or `supplier_refund`.
* `journal_id`: the journal mapped for this invoice type. If you leave it empty, Chift selects the journal only when one journal exists. Otherwise, the request fails.
* `partner_id`: the client or the supplier (see [step 2](#2-link-your-customers-and-suppliers)).
* `invoice_date` and `due_date`: the accounting date and the due date (`YYYY-MM-DD`).
* `currency`: the ISO 4217 code, for example `EUR`. For another currency than the one of the folder, see [Multi-currency](https://docs.chift.eu/unified-apis/accounting/concepts/multi-currency.md).
* `untaxed_amount`, `tax_amount` and `total`: the totals of the invoice.
* `pdf` and `pdf_name`: the PDF of the invoice in base64, and its file name. The file name accepts letters, digits, `-`, `_` and spaces, and can end with `.pdf`. See [Attachments](https://docs.chift.eu/unified-apis/accounting/concepts/attachments.md).

### Invoice number and reference

* `invoice_number`: the number of the entry in the accounting software. It does not need to match the number printed on the invoice. Each accounting software has its own format and length rules. See [Number restrictions](https://docs.chift.eu/unified-apis/accounting/concepts/number-restrictions.md).
* `reference`: a free-text reference. For a supplier invoice, put the number that the supplier printed on the invoice here, not in `invoice_number`.

Send a unique `invoice_number` and use it as your idempotency key, to avoid booking the same invoice twice.

> [!WARNING]
>
> `invoice_number` is not idempotent on every connector. Some accounting software generates its own number. On supplier invoices, some software stores the supplier's number in this field.

### Lines

Each line has:

* `account_number`: the revenue or expense account mapped for this line. It is always a general account, never the account of the partner. See [Accounts in invoices](https://docs.chift.eu/unified-apis/accounting/concepts/invoice/accounts.md).
* `tax_code`: the VAT code mapped for the rate of this line.
* `tax_rate`: the VAT rate, for example `21.0`. Send it even when the VAT code already defines it.
* `unit_price`, `quantity`, `untaxed_amount`, `tax_amount` and `total`: the amounts of the line (see [Amounts](#amounts)).
* `description`: the text of the line.

### Amounts

Your invoice is the original document: you know the untaxed amount of each line. Compute the amounts of each line as follows:

```text theme={null}
untaxed_amount = unit_price × quantity
tax_amount     = round(untaxed_amount × tax_rate / 100, 2)
total          = untaxed_amount + tax_amount
```

Send these values with the settings below. They work whatever the accounting software:

* Set the header `total` to the total printed on your invoice.
* Set `regroup_lines=false`. With `true`, Chift checks that the `tax_amount` of each line equals `untaxed_amount × tax_rate / 100` at 4 decimals. A `tax_amount` rounded to 2 decimals then fails.
* Always send `invoice_correction`, with both accounts and both VAT codes from [Rounding correction](#rounding-correction). Your invoice can compute its VAT on the whole invoice instead of each line. Then its total can differ by 0.01 from the sum of the line totals. In that case, Chift adds a 0% VAT correction line that keeps the entry on the total of your invoice.

[Amounts validation](https://docs.chift.eu/unified-apis/accounting/concepts/invoice/amounts-validation.md) gives the full validation rules.

### Example: customer invoice

`POST /consumers/{consumer_id}/accounting/invoices/multi-analytic-plans?regroup_lines=false`

```json theme={null}
{
  "invoice_type": "customer_invoice",
  "invoice_number": "INV-2026-0042",
  "invoice_date": "2026-11-17",
  "due_date": "2026-12-17",
  "currency": "EUR",
  "journal_id": "<id of the journal mapped for customer_invoice>",
  "partner_id": "<id of the client>",
  "untaxed_amount": 149.99,
  "tax_amount": 31.50,
  "total": 181.49,
  "pdf": "<PDF in base64>",
  "pdf_name": "INV-2026-0042.pdf",
  "invoice_correction": {
    "sale_invoice_correction_tax_code": "<id of the 0% sales VAT code>",
    "purchase_invoice_correction_tax_code": "<id of the 0% purchase VAT code>",
    "invoice_correction_credit_account_number": "<credit correction account>",
    "invoice_correction_debit_account_number": "<debit correction account>"
  },
  "lines": [
    {
      "description": "Consulting, 3 hours",
      "account_number": "<revenue account>",
      "tax_code": "<id of the 21% sales VAT code>",
      "tax_rate": 21.0,
      "unit_price": 33.33,
      "quantity": 3,
      "untaxed_amount": 99.99,
      "tax_amount": 21.00,
      "total": 120.99
    },
    {
      "description": "Software licence",
      "account_number": "<revenue account>",
      "tax_code": "<id of the 21% sales VAT code>",
      "tax_rate": 21.0,
      "unit_price": 50.00,
      "quantity": 1,
      "untaxed_amount": 50.00,
      "tax_amount": 10.50,
      "total": 60.50
    }
  ]
}
```

On the first line, 99.99 × 21% gives 20.9979, rounded to 21.00. This is why the request sets `regroup_lines=false`.

### Example: supplier invoice

`POST /consumers/{consumer_id}/accounting/invoices/multi-analytic-plans?regroup_lines=false`

```json theme={null}
{
  "invoice_type": "supplier_invoice",
  "invoice_number": "PUR-2026-0108",
  "reference": "<number printed on the supplier invoice>",
  "invoice_date": "2026-11-17",
  "due_date": "2026-12-17",
  "currency": "EUR",
  "journal_id": "<id of the journal mapped for supplier_invoice>",
  "partner_id": "<id of the supplier>",
  "untaxed_amount": 212.35,
  "tax_amount": 42.74,
  "total": 255.09,
  "pdf": "<PDF in base64>",
  "pdf_name": "PUR-2026-0108.pdf",
  "invoice_correction": {
    "sale_invoice_correction_tax_code": "<id of the 0% sales VAT code>",
    "purchase_invoice_correction_tax_code": "<id of the 0% purchase VAT code>",
    "invoice_correction_credit_account_number": "<credit correction account>",
    "invoice_correction_debit_account_number": "<debit correction account>"
  },
  "lines": [
    {
      "description": "Office furniture",
      "account_number": "<expense account>",
      "tax_code": "<id of the 21% purchase VAT code>",
      "tax_rate": 21.0,
      "unit_price": 200.00,
      "quantity": 1,
      "untaxed_amount": 200.00,
      "tax_amount": 42.00,
      "total": 242.00
    },
    {
      "description": "Books",
      "account_number": "<expense account>",
      "tax_code": "<id of the 6% purchase VAT code>",
      "tax_rate": 6.0,
      "unit_price": 12.35,
      "quantity": 1,
      "untaxed_amount": 12.35,
      "tax_amount": 0.74,
      "total": 13.09
    }
  ]
}
```

The values between `<` and `>` come from the mapping data of [step 1](#1-fetch-the-mapping-data) and from [step 2](#2-link-your-customers-and-suppliers). Account numbers and VAT codes differ per country and per chart of accounts.

### Refunds

For a credit note, set `invoice_type` to `customer_refund` or `supplier_refund`, and send the journal mapped for this type. The other fields follow the same rules.

### Specific cases

* [Analytical accounting](https://docs.chift.eu/unified-apis/accounting/concepts/analytical-accounting/multiple-plans.md): split the lines across cost centers, projects or other dimensions with `analytic_distribution`.
* [Multi-currency](https://docs.chift.eu/unified-apis/accounting/concepts/multi-currency.md): invoices in another currency than the one of the folder.
* [Reversed VAT](https://docs.chift.eu/unified-apis/accounting/concepts/reversed-vat.md): reverse-charge invoices.
* [Spanish withholding taxes](https://docs.chift.eu/unified-apis/accounting/concepts/spanish-withholding-taxes.md): withholding taxes on Spanish invoices.
* [Multi-folder](https://docs.chift.eu/unified-apis/accounting/concepts/folder/multi-folder.md): when one connection gives access to several folders.

## 4. Follow the invoice status

To follow the invoices you created (for example, to know which ones are paid), call [Get invoices by type (Multiple analytic plans)](https://docs.chift.eu/api-reference/endpoints/accounting/get-invoices-by-type-salepurchase-entries--multiple-analytic-plans.md). Each call returns one invoice type.

* `updated_after`: returns only the invoices created or updated after this UTC date and time. Pass the date of your last successful call. See [Incremental synchronization](https://docs.chift.eu/unified-apis/guides/incremental-synchronization.md).
* `payment_status`: `all` (default), `paid` or `unpaid`.

The `status` field of each invoice gives its state: `draft`, `posted`, `paid` or `cancelled`.

Not every connector supports `updated_after`. Without it, filter on `date_from` and `date_to`, and compare the result with the invoices you stored. A changed `status` shows an update. Check the [coverage matrix](https://docs.chift.eu/connectors/accounting/coverage.md).

To read one invoice, call [Get one invoice (Multiple analytic plans)](https://docs.chift.eu/api-reference/endpoints/accounting/get-one-invoice-salepurchase-entry--multiple-analytic-plans.md) with its `id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.