Skip to main content
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 use case first.
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. Call Get journals.
  • 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. Call Get VAT codes.
  • 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: a revenue account for a sale, an expense account for a purchase. Call Get chart of accounts 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):
  • 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.
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 of the accounting software.
  2. When no partner matches, create it.
Synchronize partners explains the matching criteria that Chift advises, and how to create a missing partner.
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.

3. Create the invoice

Create one invoice for each invoice of your software. Call Create sale/purchase entry (Multiple plans): 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).
  • 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.
  • 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.

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.
  • 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.
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.
  • 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).
  • 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:
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. 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 gives the full validation rules.

Example: customer invoice

POST /consumers/{consumer_id}/accounting/invoices/multi-analytic-plans?regroup_lines=false
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
The values between < and > come from the mapping data of step 1 and from step 2. 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

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). 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.
  • 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. To read one invoice, call Get one invoice (Multiple analytic plans) with its id.