Import payments and payment allocations
This article lists the columns you can use when you import payments and their allocations to invoices from a CSV file, and how Kompass decides whether a row updates an existing record or adds a new one. For how the Import dialog works, see Import records from a CSV file. Developers using the API can find the same columns in the API reference.
Where to import
Open Payments, choose Actions, then Import for payments or Import Allocations for the invoice lines a payment pays.
How rows are matched
- Payments: a row with an
idupdates that payment. A row without one adds a new payment. - Payment allocations: there is no
idcolumn. Kompass finds the payment by its Kompass organization (org_id), organization (client_id), name and date and adds it if it does not exist yet, then updates the payment's allocation to the invoice line, or adds one. The payment's received amount follows the allocations.
Reading the column tables
Required marks a column a new record needs. A row that updates an existing record only changes the columns in your file, so you can leave the others out. Finds the record marks a column Kompass uses to find the existing record a row updates. Column names must match exactly, including underscores. Where a column only takes certain values, the description lists them. A column marked Needs an extra permission is only accepted from users who have that permission; for anyone else the import reports it as an unknown column. The Download template button in the Import dialog gives you the header row for your own permissions.
Payments
| Column | Required | Finds the record | Description |
|---|---|---|---|
id |
No | Yes | Kompass ID of the record to update. When empty, the row adds a new record unless its other columns match an existing one. |
amount_received |
No | No | Amount received in your organization's base currency. For a payment in another currency it is converted at the exchange rate unless amount_received_local is filled in. |
amount_received_local |
No | No | Amount received in the payment's currency. When filled in, it is used instead of amount_received. |
batch_reference |
No | No | Batch reference for grouping related payments. |
client_id |
No | No | Kompass ID of the client who made the payment. |
currency_code |
No | No | Three-letter currency code, such as EUR or USD. Leave empty for your base currency. New payments only. |
currency_rate |
No | No | How much of your base currency one unit of the payment currency is worth. Leave empty to use your saved exchange rates. New payments only. |
date |
No | No | Payment date, such as 2026-01-31. |
details |
No | No | Payment details or description. |
invoice_ids |
No | No | Kompass IDs of invoices to pay, separated by semicolons, such as 101;102;103. Each invoice is paid up to what it still owes, in the order listed; anything left over stays unallocated. All invoices must belong to the payment's client. New payments only. To choose which invoice lines are paid, use the payment allocation import. |
name |
No | No | Payment name or reference. |
notes |
No | No | Internal notes about the payment. |
org_id |
No | No | Kompass ID of the organization receiving the payment. |
sync |
No | No | Put yes to send the payment to your accounting system. |
tags |
No | No | Tag names separated by commas, or a list in square brackets such as ["Design, Build"] for a name that contains a comma. The record gets exactly these tags; an empty cell removes them all. |
udf |
No | No | Custom field values. Copy the format from an export of this list. Leave the column out to keep the current values. |
udf_schema_id |
No | No | ID of the custom field set to use. Leave empty for the default payment set. |
Payment allocations
| Column | Required | Finds the record | Description |
|---|---|---|---|
batch_reference |
No | No | Batch reference for grouping related payments. |
client_id |
No | Yes | Kompass ID of the client who made the payment. Used to find the payment. |
date |
Yes | Yes | Payment date, such as 2026-01-31. Used to find the payment this line belongs to. |
details |
No | No | Payment details or description. |
name |
Yes | Yes | Payment name or reference. Used to find the payment. |
notes |
No | No | Internal notes about the payment. |
org_id |
Yes | Yes | Kompass ID of the organization. Used to find the payment. |
tags |
No | No | Tag names separated by commas, or a list in square brackets such as ["Design, Build"] for a name that contains a comma. The record gets exactly these tags; an empty cell removes them all. |
amount_net |
Yes | No | Net amount of the line to pay, before tax. |
amount_tax |
Yes | No | Tax amount of the line to pay. |
invoice_id |
Yes | Yes | Kompass ID of the invoice the payment is allocated to. |
nominal_account_id |
Yes | Yes | Kompass ID of the nominal account. With invoice_id and quote_item_id, finds the invoice line the amount is allocated to. |
quote_item_id |
Yes | Yes | Kompass ID of the quote item. With invoice_id and nominal_account_id, finds the invoice line the amount is allocated to. |