How To Import Your Invoices In Companio With The Automatic CSV Invoice Import Functionality
The CSV Invoice Import Functionality allows our PREMIUM users to add all their invoices from a CSV file directly from the dashboard.
Our system will parse a specially crafted CSV file and generate the invoices contained therein in PDF, adding them to your sales invoices automatically.
First, you need to prepare the CSV document. There is a specific format you need to follow to define your invoice entries. You can find the CSV template here. Download and open it with your favorite CSV or Spreadsheet editor.
The CSV file has the following columns:
These are the fields that need to be included in each row (fields marked with § are mandatory):
customer_name (String): name of the customer or business name of your client.
customer_email (String): email of your customer (§)
customer_address (String): physical address of your customer
customer_city (String): City of your customer
customer_zipcode (String): ZIP Code of your customer, including the country (§)
customer_country (String): country of residence of your customer (§)
customer_vat (String): the customer's VAT number, if any (this is an optional field, if the customer does not have a VAT number, you leave the field empty).
invoice_number (String): invoice number for the invoice. If not specified, a random one will be generated.
issue_date (Date): issue date of the invoice in ISO 8601, example: 2024-05-16T18:44:57Z (§).
due_date (Date): due date of the invoice in ISO 8601. If not present, the system will set the due date of the invoice to exactly one week after the issue date.
subtotal (Number, decimal point as separator): the subtotal amount without VAT in the currency of the invoice, ex: 1200.30 (§).
vat_rate (Number, decimal point as separator): percentage of VAT to apply to the invoice from 0 to 100 (§).
vat_amount (Number, decimal point as separator): amount of VAT in the currency of the invoice (§).
total (Number, decimal point as separator): total amount in the currency of the invoice with VAT amount added (§).
currency (String): currency of the invoice in ISO 4217, example: EUR, USD, GBP (§).
This is an example of a correctly formatted archive:
Go to the "Sales" section in Companio and click on "Add New > Automatic CSV Invoices Import". If you are not in our PREMIUM plan, the system will propose you to switch to that plan to start enjoying benefits such as the import functionality. Then choose a CSV file with the correct headers. The system will allow you to download a template ready for you to add columns.
![](https://storage.crisp.chat/users/helpdesk/website/6b9fcea44e196000/image8_1y431tt.png)
Now drag and drop or select your file. The importing process will start. If everything goes well, all invoices will be generated and the system will display a summary of the process, including how many invoices were generated.
![](https://storage.crisp.chat/users/helpdesk/website/6b9fcea44e196000/image1_1tvihqr.png)
You will be able to see this invoices in the Sales section now. Please note, these invoices will be added to the corresponding issue date month and year.
![](https://storage.crisp.chat/users/helpdesk/website/6b9fcea44e196000/image7_w3c6r4.png)
If there is an mistake, validation error, or the system can't generate some of the invoices, you will get a notification explaining what happened, and a report where you can get details about these errors.
![](https://storage.crisp.chat/users/helpdesk/website/6b9fcea44e196000/image5_b9m6bh.png)
The system validates every row to make sure it will be able to generate a valid invoice. These are the checks to keep in mind:
Amount verification: The system will verify the amounts of vat_amount and total, based on subtotal and vat_rate, with an error margin of 1% to account for potential rounding errors. If the total or vat_amount don't match, the invoice will not be generated.
Possible duplicated invoice: The system verifies the SHA256 hash from the generated .pdf file to prevent duplicates, and will refuse to generate a duplicated invoice.
Fields type checking: All fields (both required and optional) are type-checked.
Our system will parse a specially crafted CSV file and generate the invoices contained therein in PDF, adding them to your sales invoices automatically.
Prepare the CSV report
First, you need to prepare the CSV document. There is a specific format you need to follow to define your invoice entries. You can find the CSV template here. Download and open it with your favorite CSV or Spreadsheet editor.
The CSV file has the following columns:
customer_name | customer_email | customer_address | customer_city | customer_zipcode | customer_country | customer_vat | invoice_number | issue_date | due_date | subtotal | vat_rate | vat_amount | total | currency |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
These are the fields that need to be included in each row (fields marked with § are mandatory):
customer_name (String): name of the customer or business name of your client.
customer_email (String): email of your customer (§)
customer_address (String): physical address of your customer
customer_city (String): City of your customer
customer_zipcode (String): ZIP Code of your customer, including the country (§)
customer_country (String): country of residence of your customer (§)
customer_vat (String): the customer's VAT number, if any (this is an optional field, if the customer does not have a VAT number, you leave the field empty).
invoice_number (String): invoice number for the invoice. If not specified, a random one will be generated.
issue_date (Date): issue date of the invoice in ISO 8601, example: 2024-05-16T18:44:57Z (§).
due_date (Date): due date of the invoice in ISO 8601. If not present, the system will set the due date of the invoice to exactly one week after the issue date.
subtotal (Number, decimal point as separator): the subtotal amount without VAT in the currency of the invoice, ex: 1200.30 (§).
vat_rate (Number, decimal point as separator): percentage of VAT to apply to the invoice from 0 to 100 (§).
vat_amount (Number, decimal point as separator): amount of VAT in the currency of the invoice (§).
total (Number, decimal point as separator): total amount in the currency of the invoice with VAT amount added (§).
currency (String): currency of the invoice in ISO 4217, example: EUR, USD, GBP (§).
This is an example of a correctly formatted archive:
customer_name | customer_email | customer_address | customer_city | customer_zipcode | customer_country | customer_vat | invoice_number | issue_date | due_date | subtotal | vat_rate | vat_amount | total | currency |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ACME Corporations OÜ | [email protected] | Secret lab underground, 2 | Tokio | 23890 | Japan | 12839 | 2024-05-16T18:44:57Z | 1500.50 | 22 | 330.11 | 1830.61 | EUR |
Start the import process
Go to the "Sales" section in Companio and click on "Add New > Automatic CSV Invoices Import". If you are not in our PREMIUM plan, the system will propose you to switch to that plan to start enjoying benefits such as the import functionality. Then choose a CSV file with the correct headers. The system will allow you to download a template ready for you to add columns.
![](https://storage.crisp.chat/users/helpdesk/website/6b9fcea44e196000/image8_1y431tt.png)
Now drag and drop or select your file. The importing process will start. If everything goes well, all invoices will be generated and the system will display a summary of the process, including how many invoices were generated.
![](https://storage.crisp.chat/users/helpdesk/website/6b9fcea44e196000/image1_1tvihqr.png)
You will be able to see this invoices in the Sales section now. Please note, these invoices will be added to the corresponding issue date month and year.
![](https://storage.crisp.chat/users/helpdesk/website/6b9fcea44e196000/image7_w3c6r4.png)
If there is an mistake, validation error, or the system can't generate some of the invoices, you will get a notification explaining what happened, and a report where you can get details about these errors.
![](https://storage.crisp.chat/users/helpdesk/website/6b9fcea44e196000/image5_b9m6bh.png)
Validation and security checks
The system validates every row to make sure it will be able to generate a valid invoice. These are the checks to keep in mind:
Amount verification: The system will verify the amounts of vat_amount and total, based on subtotal and vat_rate, with an error margin of 1% to account for potential rounding errors. If the total or vat_amount don't match, the invoice will not be generated.
Possible duplicated invoice: The system verifies the SHA256 hash from the generated .pdf file to prevent duplicates, and will refuse to generate a duplicated invoice.
Fields type checking: All fields (both required and optional) are type-checked.
Updated on: 13/06/2024
Thank you!