Products
Products CSV Import
Simple products may be imported to the Ka-ching system through the Ka-ching Back Office using the CSV format.
Since the CSV format is by nature very -flat-, and our product model is basically a hierarchical structure, there is not a very good fit between what we can express in CSV and what our products can express.
The import itself is also a manual process, so this is only intended for getting started using the system real quick - or if you do not have an external PIM system and would like to use the Ka-ching system as the primary source for your products.
Product format
A product can be represented by as little as three values:
Required values
- Unique identifier
- Name
- Retail price
The unique identifier is used to identify the product, so that if you import the CSV file repeatedly, then the product matching the identifier will be overwritten with the new values.
The name is required in order to logically identify the product in the POS, and in statistics, etc.
The retail price is required since otherwise we cannot sell the product.
Optional values
- Bar code
- Product description
- Short description
- Cost price
- Sale price
- Image URL
The bar code can be used to represent the textual value of the bar code on the physical product. This may correspond to an EAN code, an ISBN number or a SKU. If this value is present, the product can be added to the basket by scanning the bar code.
The Product description is shown when long-pressing a product in the POS.
If a cost price is added, then we can calculate the contribution margin when selling the product. This value is always represented without any taxes added.
If a Sale price is added, then a discount will be added when the product is added to the basket. So if a product normally cost 100 DKK and the sale price is 80 DKK, then the POS will 'cross out' the 100 DKK and write 'New price: 80 DKK'
You may import images for the products as described below, but if you already know of publically accessible URLs for the images on a CDN, you may also include the image URL directly. The images should be in JPEG or PNG format.
Localizable values
The product name and product description is localizable data. This means that instead of giving a product a fixed name, you may specify it in any of the 13 languages that we currently support:
- Danish
- English
- French
- Norwegian (Bokmål)
To specify a field in multiple languages, you just postfix the field with a dot (.) and the language code. The codes for the languages are:
- da
- en
- fr
- nb
So for instance, the 'product name' field is called 'field'. So the following imports two products with no localization of the name:
id;name;retail_price
p001;Coffee;10.50
p002;Tea;9.50
These products could be localized into Danish and English as follows:
id;name.da;name.en;retail_price
p001;Kaffe;Coffee;10.50
p002;Te;Tea;9.50
Tags
You can tag a product with one or more categories. The identifiers for the tags can be seen under the 'Tags' editor in the Portal. To add two tags to your products you can use the fields tags.0 and tags.1.
Example:
id;name;retail_price;tags.0;tags.1
p001;Coffee;10.50;beverage;caffeinated
p002;Tea;9.50;beverage;popular
Attributes
You can add custom attributes to a product. Attributes are similar to tags, but you can define the attributes in the backend - thus creating custom properties on a product. For instance you could have a 'brand' attribute or a 'review'.
Example:
id;name;retail_price;attributes.brand;attributes.review
p001;Coffee;10.50;starbucks;A great coffee, and very cheap
p002;Tea;9.50;earlgray;Nice tea - very popular
Field names
Now we have described the overall product structure and the required and optional fields. Here is a list of all the currently supported field names:
- id
- name (localizable)
- description (localizable)
- short_description (localizable)
- retail_price
- cost_price
- sale_price
- image_url
- tags.0, tags.1, tags.2, etc.
- attributes.my_custom_attribute, attributes.*, etc.
Finally an example with all the above values represented:
id;name.da;name.en;description.da;description.en;retail_price;cost_price;sale_price;image_url;barcode;tags.0;tags.1
p001;Kaffe;Coffee;"Kaffe er en sund og dejlig drik.
Og denne beskrivelse strækker sig over flere linjer";"Coffee is a healthy and excellent beverage.
And this description spans several lines";10.50;3.00;9.00;http://example.com/coffee.jpg;ABCDEFG;beverage;caffeinated
p002;Te;Tea;"Te er en ""drik"" og dette er et eksempel på at bruge gåseøjne i et felt";"Tea is a ""beverage"" and this is an example of using quotes inside a field";9.50;1.50;8.00;http://example.com/tea.jpg;ABCDEFX;beverage;popular
Variants and dimensions
It is generally hard to represent hierarchical data in a 'flat' CSV file, but we have made it possible to describe variants and dimensions on a product by having multiple lines for the same product in the CSV:
Variants
General format:
id;variant_id;name;retail_price
p001;;Espresso;10
p001;single;Single shot;
p001;double;Double shot;15
The first line define the product with id: p001, name 'Espresso' and a default price of 10.
The second line defines a variant (through the inclusion of a non-empty variant_id) on the same product (by referring to the same id) with an override of the name, but no override of the price.
The third line defines a second variant that also overrides the price.
Dimensions
Dimensions and dimension values can be added in a similar fashion - using a special notation to refer to the dimensions and values from each variant:
id;variant_id;name;retail_price;dimension_id;dimension_value_id;dimension_values
p001;;Dress;190;;;
p001;small-red;;;;;size=s#color=red
p001;large-blue;;200;;;size=l#color=blue
p001;;Size;;size;;
p001;;S;;size;s;
p001;;M;;size;m;
p001;;L;;size;l;
p001;;Color;;color;;
p001;;Green;;color;green;
p001;;Red;;color;red;
p001;;Blue;;color;blue;
Here's the same data presented as a table:
| id | variant_id | name | retail_price | dimension_id | dimension_value_id | dimension_values |
|---|---|---|---|---|---|---|
| p001 | Dress | 190 | ||||
| p001 | small-red | size=s#color=red | ||||
| p001 | large-blue | 200 | size=l#color=blue | |||
| p001 | Size | size | ||||
| p001 | S | size | s | |||
| p001 | M | size | m | |||
| p001 | L | size | l | |||
| p001 | Color | color | ||||
| p001 | Green | color | green | |||
| p001 | Red | color | red | |||
| p001 | Blue | color | blue |
As in the previous example, the first line contains the product definition.
The following two lines contain variant definitions (by the presence of the variant_id). We'll return to the variant-specific field dimension_values later.
The fourth line defines the dimension named 'Size' with id 'size' (by the presence of the dimension_id).
The three lines after that define three different sizes (by the presence of both dimension_id and dimension_value_id).
Finally we repeat this concept to add the 'Color' dimension with the values 'Green', 'Red' and 'Blue'.
Now let's return to the dimension_values field. This field points out the dimension values for each variant. There needs to be a valid value for each dimension. The format is a #-separated list of dimension_id to dimension_value_id pairs separated by an = sign.
Batch uploading images
You may drag/drop multiple images to be imported in one go. The image names should identify which product they should be attached to, so in the above example we could batch import images for the Coffee and Tea by naming the images p001.jpg and p002.jpg and drag/dropping both images to the product image import.
Sample CSV files
To get started, you may experiment with the following files: