Documentation Custom CSV

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 the 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:

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:

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):