Documentation Custom CSV

23. Juni 2026 07:58 Aktualisiert

What is Custom CSV?

The Custom CSV Importer allows you to import data from shops and marketplaces that are not natively supported by easybill.

It is based on a predefined CSV format that the importer expects. You must ensure that either the shop exports the data in the correct format or that you convert the file into the appropriate format yourself. An example of this format can be found here.

In this article, you will learn how to optimally prepare your data for the Custom CSV import and how to upload it into easybill Connect (formerly Import Manager).

CSV File Format

General Format

The general format forms the basis for importing your data. The following points are particularly important:

Character Encoding: CSV files should ideally be encoded in UTF-8 (alternatively, ISO-8859-1 is supported but not recommended).
Field Separator: The Custom CSV Importer accepts the semicolon (;) as a valid field separator. Please ensure that your CSV file uses this delimiter.
Header Row: The first row of the file must contain the field names. Our system uses these headers to correctly map the data to the corresponding internal fields—regardless of the column order.

These basics ensure that the import process runs smoothly and your data is imported into easybill completely and without errors.

Field Types

For a successful and error-free import, it is essential that the data in your CSV file matches the expected field types. Each field type defines how the contained values are interpreted and processed:

String:
This type is used for general text — including content with line breaks, as long as it is enclosed in quotation marks.
Example: "A SAMPLE TEXT"
Text:
This type is used for extensive text content — for example, detailed descriptions, comments, or longer notes.
Example:
"This is a longer text that can span multiple lines. It contains detailed information relevant for the import."
Decimal:
Decimal values are expected in the format XXX.YY. Values up to a defined precision (e.g., up to 9,999,999,999.9999) are supported.
Example: 100.00
Integer:
Whole numbers without decimal places.
Example: 1
Date:
Dates must be provided in the format YYYY-MM-DD.
Example: 2012-07-19
Datetime:
For combined date and time values, use the ISO 8601 format.
Example: 2012-07-19T19:29:20+02:00

Strict adherence to these formats ensures that our system can correctly interpret and assign the data. Deviations may result in import errors or incorrect data mapping.

Order-Specific Fields

This section describes the fields that explicitly relate to an order. Important to note: If an order is spread across multiple rows (e.g., due to multiple items), only the information from the first row is used for order processing. All subsequent rows serve solely to provide item-level details and are ignored with regard to the overarching order data.

Here is an overview of the most important fields:

Field Name	Description	Required	Format
`order_number`	The unique order number serves as the primary identifier and ensures that duplicate imports are avoided.	Yes	String (1..255)
`order_number_2`	Alternative or secondary order number.	No	String (0..255)
`email`	Customer's email address. Optional, but recommended for sending invoices to customers automatically.	No	String (0..255)
`name`	Full name of the customer or company name. Required if `firstname` and `lastname` are not provided.	See note	String (1..255)
`firstname`	Customer's first name. Not required if `name` is provided.	See note	String (1..255)
`lastname`	Customer's last name. Not required if `name` is provided.	See note	String (1..255)
`street`	Street name and, if applicable, house number.	Yes	String (1..255)
`address_1` to `address_3`	Additional address information.	No	String (0..255)
`zipcode`	Customer's postal code.	Yes	String (0..255)
`city`	Customer's city.	No	String (0..255)
`state`	Customer's state.	No	String (0..255)
`country`	Country code in ISO 3166-1 format (e.g., DE).	Yes	String (0..255) (ISO-3166 format)
`phone_number`	Customer's phone number. Might be required for delivery services (e.g., Hermes, DHL).	No	String (0..255)
`fax_number`	Customer's fax number.	No	String (0..255)
`currency`	Currency code (e.g., EUR, USD).	Yes	String (3) (ISO-4217 format)
`order_shipping_price`	General shipping cost for the order (not item-specific).	No	Decimal (16,5)
`purchase_date`	Purchase date or date and time.	No	Date or DateTime (ISO-8601)
`shipping_date`	Date when the order was shipped.	No	Date or DateTime (ISO-8601)
`estimated_arrival_date`	Estimated delivery date.	No	Date or DateTime (ISO-8601)
`shipping_tracking`	Shipping tracking number.	No	String (0..255)
`shipping_type`	Shipping method (e.g., DHL, Hermes). Free text, can be used via placeholders in documents.	No	String (0..255)
`payment_date`	Date of payment.	No	Date or DateTime (ISO-8601)
`payment_type`	Payment method used.	No	String (0..255)
`payment_reference`	Reference shown on the invoice. No further processing – passed through 1:1.	No	Text
`customer_number`	External customer number used in the shop.	No	String (0..255)
`customer_username`	External username used in the shop.	No	String (0..255)
`customer_since`	Date when the customer was registered.	No	Date or DateTime (ISO-8601)
`shipping_name` to `shipping_address_3`	Fields for a separate shipping address. Use them analogously to the corresponding billing fields.	No	String (0..255)
`invoice_number`	Pre-generated invoice number.	No	String (0..255)
`store_id`	Store identifier (e.g., for multi-store setups). Can control document texts and templates.	No	String (0..255)
`vat_id`	Customer's VAT ID.	No	String (0..255)
`tax_type`	Override automatic tax type detection. Allowed values: - `intra-community-trade` - `reverse-charge` - `not-taxable` - `not-taxable-eu` - `not-taxable-eu-no-vatid` - `export`	No	String (0..255)
`fulfillment_country`	Country of fulfillment, relevant for VAT calculation. Defaults to your settings if not provided.	No	String (0..255)
`comments`	Free text for additional information or specific notes regarding the order.	No	Text

Item-Specific Fields

If an order contains multiple items, each item must be recorded in a separate row within the CSV file. The item-specific fields provide detailed information about each individual product, such as item number, description, quantity, price, and other supplementary details. Providing correct and complete information for these fields is essential to ensure that each item can be clearly identified and properly processed during the import.

Below you will find an overview table that summarizes all relevant fields, their descriptions, whether they are required, and the expected format:

Field Name	Description	Required	Notes / Format
`item_number`	Internal item number used to identify a product.	No	String (0..255)
`item_number_2`	Secondary item number for the product.	No	String (0..255)
`sku`	The SKU of the ordered product. If defined in the external system, it should be included in the CSV file, as we use the SKU for certain features (e.g., automatic VAT calculations based on the product).	No	String (0..255)
`title`	Product description displayed on the document.	Yes	String (0..255)
`title_2`	Additional optional product description.	No	String (0..255)
`quantity`	Quantity of the item ordered.	Yes	Integer
`item_price`	Gross price per unit of the item.	Yes	Decimal (16,5)
`item_shipping_price`	Shipping costs assigned specifically to this item.	No	Decimal (16,5)
`vat_percent`	VAT percentage applied to this item (e.g., 19.00 for 19%). If not specified, we will try to determine the VAT based on the merchant's default settings, SKU-specific rules, or the `vat_rate` field if provided.	No	Decimal (5,2)
`vat_rate`	Instead of `vat_percent`, a textual VAT rate can be used. EU-wide we support the following values: `default`, `discount`, `digital_discount`, `reduced`, `reduced_1`, `reduced_2`, `super_reduced`, `parking`.	No	String (0..255)
`discount_percent`	Discount applied to the item.	No	Decimal (5,2)
`item_type`	Type of the item, e.g., `discount` or `virtual`.	No	Values: `product`, `discount`, `virtual`
`item_weight`	Weight of the item. Can be used in templates with the variable `{{item_weight}}`.	No	String (0..255)
`variant_yourKey`	You can define as many additional variant details as needed. These are not processed internally but can be used in templates (e.g., `{{item_variant.color}}`).	No	Example: `variant_color, variant_size, variant_model` The second part of the `variant_yourKey` name may only contain letters, dashes (-), underscores (_), and numbers.

Note on Multiple Items in a Single Order

If an order contains multiple items, each item must be listed in its own row. All rows belonging to the same order must be placed consecutively. The order of rows is crucial for our system to correctly associate the items with the corresponding order.

Correct Example (two items in order order-1, then one item in order order-2):

Incorrect Example (rows for order-1 are interrupted by a row from order-2):

order-1;john doe;...;first-item;...

order-2;peter pan;...;first-item;...

order-1;john doe;...;second-item;...

Comments in the CSV File

You have the option to include comment lines in your CSV file. These can be used, for example, to indicate the source of the data or to add internal notes for developers.

Ignored Lines:
All lines starting with #! are ignored by our system and are not processed.
Developer Recommendation:
To assist with error analysis or to help identify the data source more easily, we recommend inserting at least one line that contains the export or system name, for example:
#! exported-by: NAME-OF-YOUR-SYSTEM
This allows both you and our support team to quickly identify the system from which the CSV file originated.

Importing Data

easybill offers several flexible methods for uploading your CSV files. Choose the option that best fits your workflow:

Direct File Upload

Upload your CSV file directly via our web interface. This allows you to test the import beforehand – our system automatically checks the file format and flags any potential errors.

Automated FTP File Retrieval

If you want to import your CSV files fully automatically into easybill, you can use our automated FTP polling feature. Our system regularly checks a predefined FTP server for new CSV files. Once new files are found, they are processed automatically.

Note: Since FTP transfers are unencrypted, we strongly recommend using FTPS to ensure secure data transmission.

Accessing FTP Polling Settings

You can configure the FTP polling settings directly within easybill Connect. To do this, navigate to Settings > More Shops.

In the Shop Overview, search for Custom CSV and click on Set Up to access the Custom CSV settings.

Then scroll down to enter your FTP credentials.

Settings

Storing FTP Access Credentials
In your easybill account, you can enter the login credentials for your FTP server under the import settings. Here you can define the path and file name(s) so that our system can correctly identify the files.
Time Interval
Our system checks the FTP server at regular intervals to see if new files are available. This eliminates the need for manual uploads.
Optional URL (HTTP Ping)
Additionally, you can specify a URL that will be called by our system before the actual download begins. This can be useful if the CSV file still needs to be generated first.

REST API

Use our new REST API to trigger the import directly and automatically. You can find the API documentation at:

https://connect-api-docs.easybill.com/#post-/orders/upload