Skip to main content
Invoices, journal entries and payments reference their client or supplier in the accounting software with partner_id. This guide explains how to link each customer and supplier of your software to a partner of the accounting software, and how to keep this link up to date. The same logic applies to clients and to suppliers.

1. Load the partners

When the end-user connects their accounting software, fetch all the partners: Fetch every page of the result. See Pagination. Store the partners on your side.

2. Match your partners

For each customer or supplier of your software, look for its partner in the accounting software. Chift advises the criteria below, in this order. Compare each criterion with all the partners before you try the next one: the most specific criterion wins.
  1. Existing link. You already stored the id of the partner for this customer or supplier. Reuse it.
  2. Partner code. Compare the code of your customer or supplier (for example, its account number in your software) with third_party_account and with external_reference. Compare your own reference with external_reference.
  3. Company number. Compare it with company_number.
  4. VAT number. Compare it with vat. Compare the company number first: the members of a VAT group share one VAT number.
  5. Name. Compare it with third_party_account and with external_reference. For an individual, compare the full name (first name and last name) with the full name of the partner.
Follow these rules:
  • Compare only the active partners (active is true).
  • For the company number and the VAT number, remove the dots and the spaces, and ignore the case. For example, BE 0123.456.789 matches BE0123456789.
  • For the partner code, remove the spaces and ignore the case. Some accounting software pads the code with trailing zeros: compare the codes without them.
  • An empty value never matches.
  • Do not match on the account_number of the partner. It can be a shared control account, used by many partners.
When a partner matches, store its id with your customer or supplier. Send this id as partner_id on every invoice or entry for this customer or supplier.

3. Create the missing partners

When no partner matches, create it before you book its first invoice: Send at least:
  • name: the name shown in the accounting software. For an individual, set is_company to false and send first_name and last_name.
  • addresses: the list of addresses. Each address needs address_type, street, city, postal_code and country.
Also send the data that helps the next match: vat, company_number and external_reference (your own identifier of the customer or supplier). Store the id of the created partner, as for a match. Some accounting software keeps clients and suppliers in one list. When your customer is also a supplier there, send the id of the existing supplier in the force_merge parameter of Create client (or the id of the existing client in Create supplier). The accounting software then merges the two.
Some accounting software cannot create partners through the API. For these connectors, send the partner with partner_info on the invoice. See Create invoices.

4. Keep the partners up to date

Partners change in the accounting software: the accountant creates, edits or deactivates them. Refresh your stored partners at regular intervals:
  • Pass the date of your last refresh as updated_after. The API returns only the partners created or updated after this date. See Incremental synchronization.
  • To look up one partner, use the search parameter. It filters on name, email, first_name, last_name, external_reference, vat and company_number.
Not every connector supports updated_after. Without it, fetch all the partners again and compare them with the partners you stored. Check the coverage matrix.

5. Handle a deleted partner

If someone deletes a partner from the accounting software, the creation of its invoices fails. Remove the stored link, then match the customer or supplier again (step 2), or create the partner again (step 3).