General

This documentation describes the format and content of product data, inventory, category data and customer dependent prices that can be sent to the shop.

Transfer of import files

The import files described below can be transferred using the REST or SOAP interface:

Übertragung - Trigger: REST, SOAP & Co

Overview import files

Currently the following import files are supported:

Character set of the import files

It is recommended that all import files are supplied in the character set of the relevant subshop.

This ensures that all imported special characters are displayed correctly in the shop. As soon as character sets have to be converted, there is a risk that there is no equivalent in the shop's character set for certain characters.

The character set of the subshop is entered in the file "shop.config", in the section "Basic" at the parameter "Charset".

Character set conversion

If the ERP system cannot supply the character sets of the subshop, these must be converted accordingly.

Conversion of the "catcomplete.xml" character set

For the "catcomplete.xml", the character set in the header of the XML file is evaluated. A special configuration of the character set conversion is therefore not necessary.

Character set conversion of the files "wpupdate.csv", "wpcomplete.csv" and "*.prd".

If these files are to be converted, this must be set in the global.config file in the "configuration" directory of the shop.

Section:

ConvertCharset:

The "ConvertCharset" parameter determines whether the character set of the product data is converted at all. The other two parameters are optional.

ImportCharset:

ImportCharset" can be used to specify the character set of the import files if it differs from UTF-8.

UnknownCharacters:

The "UnknownCharacters" parameter controls how to handle characters that have no equivalent in the SubShop's character set:

ignore: The characters are omitted without replacement

stdreplace: Attempts to replace the character with one or more similar characters

mapreplace: The characters are converted using a mapping table in the global.config file

Conversion tables

If characters are used in the import data that are not present in the shop's character set, they can be converted to other characters using conversion tables in the global.config file.

The parameter "Charset" specifies the character set of the shop for which this table is to be used. All other entries in the section specify the desired substitutions: To the right of the "=" is the character string in the import file, to the left of it is the character string by which it is to be replaced. Both the original characters and the replacement must be encoded in the character set of the import file.

All characters can be URL encoded. In this case, a "%" character is followed by the hexadecimal code of the character. This encoding is recommended for all special characters (with a code >= 128), otherwise there is a risk that these characters will be saved in the wrong character set when editing the file.

Remarks
If a character string is not to be replaced by another one, but deleted, this can be achieved with the special value "$delete".

• The conversion tables are currently only used for converting product data, not category data.

• There can be any number of <+ImportCharsetConvertMap> sections in the global.config file. However, they must differ in the "Charset" parameter.

Formats of the import files

General

All files with the extensions "csv" and "prd" are stored in a "character separated values" format, i.e. the files consist of a header line with the field names and any number of data lines, as well as field separators between the fields of a data line. Field separators for the field values or the field names in the header line are tab characters. The lines are terminated with a CR or a CRLF.
Please pay attention to the upper/lower case of the field names.

Example:
HeaderField1<TAB>HeaderField2<TAB>HeaderField3<CRLF>
FieldValue1a<TAB>FieldValue2a<TAB>FieldValue3a<CRLF>
FieldValue1b<TAB>FieldValue2b<TAB>FieldValue3b<CRLF>

Data types

The following data types are used in the tables below:

Maximum length of fields

The maximum lengths specified in the tables are not checked during import. Fields where the maximum length is exceeded will not be shortened, neither during import nor later when displayed in the shop.

The reason for this is that fields (especially the product description) can contain HTML formatting. If, for example, a product description were now truncated after an opening <table> tag, but before the closing </table> tag, not only would the formatting of the field value itself be affected, but the formatting of the entire content of the HTML page that follows the description. In the worst case, not only would the display of the page be affected, but also the function, if, for example, the "Add to Cart" button is no longer displayed.

For this reason, fields where the maximum length is exceeded are not displayed in the shop or are displayed with empty content.

Product data (wpupdate.csv/wpcomplete.csv)

These files contain the product data to be changed or newly added to the shop.

List of fields (unstructured)

The file can contain the following fields:

Unused fields can be omitted, but you should use the same fields in the same order each time you import. If you add fields, delete fields, or change the order of fields, then the data already stored in the shop will need to be adjusted to the new fields during import, which can significantly lengthen the import process.

In addition to the fields listed above, the import file can contain the free fields created in the WSPManager for the subshop (Allowed characters/
max. length: S1/16000). The column headings in the import file must correspond to the "Technical field names" entered in the WSPManager.

Meta fields (structured)

In order to keep the table structure slim and clear, some fields have an additional inner structure. Thus, a number of parameters and values can be specified in a table field that varies from product to product. Example: Scale prices.

BulkDiscount/Staggered prices

Scale prices are passed in the following format in a table field:

<g><1>quantity type 1</1><2>quantity 1</2><3>price 1</3><4>price type 1</4><5>base price 1</5></g>.
<g><1>quantity type 2</1><2>quantity 2</2><3>price 2</3><4>price type 2</4><5>base price 2</5></g>

(The line break is not part of the format and is only for better readability)

Each record is framed by the tags "<g>" and "</g>". Within the record there are additional tags for price type, quantity and prices.

Example:
<g><1>0</1><2</2><3>3.5</3><4>0</4><5>5.00 EUR / kg</5></g>
<g><1>0</1><2>4</2><3>1.9</3><4>0</4><5>2.71 EUR / kg</5></g>

BulkDiscountPrices/PromotionalPrices

Promotional prices can be used if you want prices to be both quantity based and time based. For each time/quantity scale, this requires an entry in both the BulkDiscount field and the BulkDiscountPrices field.

BulkDiscount

For each time/quantity scale, in addition to any time-independent scale prices that may exist there, an additional entry must be added to the BulkDiscount field that has the following structure:

<g><1>quantity type 1</1><2>quantity 1</2><4>price type 1</4></g>.
<g><1>quantity-type 2</1><2>quantity 2</2><4>price-type 2</4></g>

(The line break is not part of the format and is only for better readability.)

The structure is largely the same as the "normal" scale prices, with the difference that the "<3>" tag is completely omitted, and the "<4>" tag contains other values.

Example:
<g><1>0</1><2>5</2><4>2</4>

BulkDiscountPrices

For each additional time-dependent price in the "BulkDiscount" field, at least one entry must be added to the "BulkDiscountPrices" field containing the actual time-dependency and price.

The field has the following structure:

<aQuantity><1>Start-Time</1><2>End-Time</2><3>Price</3><4>Type</4></aQuantity>
<gQuantity><1>start-time</1><2>end-time</2><3>price</3><4>type</4></gQuantity>

"Quantity" will be replaced by the quantity entered in the "<2>" tag of the corresponding entry in the "BulkDiscount" field.

For each entry in the BulkDiscountPrices field, there must be an entry in the BulkDiscount field that matches the entry in BulkDiscountPrices in quantity and in the value of the <4> tag.

<a5><1>1432652273</1><2>1432652283</2><3>10.00</3><4>2</4></a5>

Remark:

If multiple prices with overlapping time periods are imported, the lowest price will be used in the shop.

AltPrices

This field can be used to import additional, time-dependent prices. If there is no valid price for the current time, the price imported under "Price" will be used instead.

If several time periods are valid, the lowest price will be used.

If the start or end time is not to be used, "0" must be entered there as the time.

The alternative prices are passed in the following format in a table field:

<g><1>Start time</1><2>End time</2><3>Price</3></g>
<g><1>start-time</1><2>end-time</2><3>price</3></g>

(The line break is not part of the format and is only for better readability.)

Each record is framed by the tags "<g>" and "</g>", Within the record there are additional tags for start time, end time and price.

Analogous to the "alternative prices", the tag "a" can also be used to define "promotion prices". These are used preferentially (i.e. before the alternative prices) in the specified period.

Example:
<g><1>1210892400</1><2>1240892500</2><3>3.5</3></g>
<g><1>1240892401</1><2>1250892401</2><3>1.9</3></g>

(The line break is not part of the format and is only for better readability.)

OrgPrices

The format is the same as the AltPrices field, but there are no promotional prices in the OrgPrices field.

Beispiel:
<g><1>1210892400</1><2>1240892500</2><3>3.5</3></g><g><1>1240892401</1><2>1250892401</2><3>1.9</3></g>

AreaProductPriceScale/Scale prices for area products

This field can be used to define scale prices for area products. Scale prices for area products cannot be combined with customer dependent/price group dependent prices or time dependent prices.

The content of the field must be supplied in the following format:

(<from size>:<price>)(<from size>:<price>)....

Example:
(0:12.99)(100:11.99)(199:10.99)(1000:8.99)

TextInputFields/Text input fields

For this purpose, the orderer can store one or more inputs for the product (e.g. texts for flocking).

The text input fields are stored in the following format:

(The line breaks are not part of the format and serve only the better readability.)

The data of a single text input field is framed by the tags "<g>" and "</g>". Within the record there are further tags for label, number of visible characters, number of lines, the maximum number of characters and "input required".

Example:
<g><1>front imprint</1><2>30</2><3>1</3><4>50</4><5>y</5></g><g><1>rear imprint</1><2>30</2><3>2</3></g>

Variations "normal variants"

For the normal variants, only some product attributes may depend on the variant (size, color, height, width, etc.).

For the normal variants, the following format applies:

(The line breaks are not part of the format and are only for better readability.)

Example:
<g><vn>color</vn><ve><1>red</1></ve><ve><1>yellow</1><2>5.00</2><5>y</5></ve><ve><1>green</1><3>08-GR</3></ve></g>

DepVariations/DepVarFile, "dependent variants".

For the dependent variants, most of the product attributes like:

• Price

• Product number

• Stock

• Illustration

• Name/description

• etc.

can be dependent on the variant (size, color, height, width, etc.).

The main part of the data of dependent variants is stored in a separate "PRD file" for each product. The wpupdate.csv/ wpcomplete.csv files contain only the names of the variants used and a reference to the PRD file.

Names of the variants

The names of the variants are stored in the "DepVariations" field, it has the following structure:

<g><vn>variation name 1</vn></g><g><vn>variation name 2</vn></g><g>...

Example:
<g><vn>color</vn></g><g><vn>size</vn></g>

Order quantities as dependent variants

In certain cases, it may be useful to implement the possible order quantities using a dependent variation. In this case, the price specified in the PRD file is not multiplied by the quantity but displayed unchanged in the shop.

A disadvantage is that the size of the PRD files multiplies. Depending on how many other variants and variation entries the product has, several thousand lines can quickly add up, which can lead to a noticeable slowdown of the online shop. Also note that no more than 100000 dependent variations can be imported per product.

To mark a variation as a quantity it must be prefixed with "$1$".

Example:
<g><vn>color</vn></g><g><vn>size</vn></g><g><vn>$1$quantity</vn></g>.

Name of the PRD file

The reference to the PRD file is stored in the "DepVarFile" field. The content consists of the subdirectory where the file is located and the name of the file itself.

Example:
german_491.prd/PFLS744.prd

The names of the directories and the PRD files themselves are formed according to a fixed scheme.

The file name is formed from the product index + the extension ".prd". For example, if the product index is "ABCxyz", the name of the corresponding PRD file is "ABCxyz.prd". If the product index contains characters that are not permitted in file names (\,/,:,*,?,",<,>,|), these must be "escaped". The same applies to all characters with ASCII code>127 (especially umlauts) and the character "%".

The escape mechanism is the same as used for URLs, i.e. the illegal character is replaced by "%" + the two-character hex code (in lower case) of the character code.

So the product index "123/abc" would result in the PRD file name "123%2fabc.prd".

It is recommended to choose the product index in a way that no escaping is necessary.

Please note that the file system used by the shop is case sensitive. So if the product index is "abc", the PRD file must have the name "abc.prd". The name "ABC.PRD" would be invalid, for example, and would lead to errors when displaying the dependent variants.

The name of the directory is derived from the subshop of the product and a hash value formed from the product index.

Directory name = <subshop> + "_" + prodindex hash + ".prd".

First, the MD5 hash value is formed from the product index. The first two bytes of this hash value are interpreted as integer (byte1 + 256*byte2) and taken modulo 1000.

Example:

The content of the PRD files is described in a separate chapter ("PRD files").

CrossLinks

This field can contain the data for "CrossLinks" as well as for the related data of "CrossSellingLinks" and of "Substitutes".

The field has the following format:

<g><1>Product index</1><2>Category index</2><3>Link type</3><4>Product number (only when linking to variant)</4></g><g>...

Example:
<g><1>23110001</1><3>2</3></g><g><1>23474</1><2>3121-34</2><3>2</3></g>

Inventory/Stock

This field contains the static part of the inventory data, i.e. the part that does not depend on the number of pieces.

The field has the following structure:

(The line breaks are not part of the format and are just for better readability.)

Example:
<1>y</1><11>0</11><12>10</12><21>immediately available</21><22>immediately available</22><23>sorry out of stock</23>

Download articles

This field contains the data necessary for download articles, it has the following structure:

Example:
<1>y</1><2>download.zip</2><3>48</3><4>10</4>

Set

This field contains the set sub-items of a set, it has the following structure:

(The line breaks are not part of the format and are only for better readability.)

Example:
<g><1>DA634108</1><3>1</3><5>y</5></g><g><1>DA613740</1><2>y</2><3>2</3></g><g><1>AA650659</1><3>1</3></g>

SetConfiguration

This field contains a metadata structure that contains additional options about the set items.

Currently this field can only contain one tag:

Example:
<IgnoreChildInventory>y</IgnoreChildInventory>

ChildProducts

This field contains the grouping sub-article data. It has the same structure as the CrossLinks field, "0" is entered as the type.

ProductComparisonFields/Comparison fields

ProductComparisonFields is used to import the fields that can be used when comparing products in the shop. The comparison property is read from the (free) field with the technical name.

It has the following structure:

(The line breaks are not part of the format and are only for better readability.)

Example:
<g><1>Manufacturer</1></g><g><1>Width</1></g>

In parallel to the "old" logic, the ProductComparisonFields can be extended so that different comparison attributes can be maintained in the same free fields:

(The line breaks are not part of the format and are only for better readability.)

Example:
<g><1></1><2>alternative-ProducerName</2><3>Manufacturer</3></g>

If no technical field name is given in <1>, the description of the comparison field (in <3>) is used.

The comparison property is read from the free field with the technical name as given in<2>.

Old and new logic can also be mixed, both between different products and within the ProductComparisonFields field.

AreaProductRange/Options for area products

For area products, the customer can enter the dimensions of the product when ordering in the shop, for example, height 2m, width 1.5m. The shop calculates the area from the dimensions and multiplies it by the "unit price" of the product to determine the final price.

Whether a product is an "Area Product" is specified in the "AreaProduct" field (see "Standard Fields").

In the extended field "AreaProductRange" additional restrictions of the dimensions are imported, so that the customer can enter in the shop e.g. only widths which lie between 0.5 and 2.5m.

Since area products are usually not available in arbitrary dimensions, all four fields must be filled, otherwise the product cannot be ordered in the shop.

The field has the following structure:

(The line breaks are not part of the format and serve only the better readability.)

Example:
<minlen>1.5</minlen><maxlen>2.5</maxlen><minwidth>0</minwidth><maxwidth>3</maxwidth>

VariationsOverview/VariationsOverviewMatrix/clothing module

The data in these two fields allows the shop to display a matching image even if the dependent variations are only partially resolved. This is the case when searching for products (e.g. searching for "pants red"), for category filters (e.g. filtering for red products) and when searching for part numbers.

Furthermore, this data makes it possible to display images of the product when selecting variants, e.g. instead of a selection list with "red" and "green" two images on which the product is shown in "red" and "green" respectively.

The number of variations for this feature is limited to a maximum of 2.

VariationsOverview

This field contains the names and values of the variations, as well as for each value the images to be displayed and an (optional) text to be displayed.

Example:

(The line breaks are not part of the format and are only for better readability.)

VariationsOverviewMatrix

This field contains in compact form ("matrix") the allowed combinations of variation values and the corresponding product numbers. The values of the first variation correspond to the columns and the values of the second variation to the rows. The cells of the matrix contain either the number of the product belonging to the combination or an empty value if there is no matching product for the combination.

Example: The first variant is "size" and has the values "S", "M" and "L", the second variant is "color" and has the values "red" and "green".

Then the matrix could look like this:

In the actual field value of "VariationsOverviewMatrix", the variation values are omitted, the columns are separated by "|" characters, and the rows are separated by a ">" character.

So for the example above, the field value is as follows:

1234-s-r|1234-m-r|1234-l-r>1234-s-g|1234-l-g

An escape mechanism for the "|" and ">" characters is not provided, i.e. when using the "garment module", these characters must not appear in product numbers.

Garment module and PRD files

When using the garment module with two variants, the lines in the PRD file must be sorted according to the values of the first variant. The order (e.g. ascending or descending) is not relevant, it is only important that lines with the same variation values are together.

Example "correct":

Example "false":

InstantVoucherProduct/voucher products

In this field the data for voucher products are passed, i.e. of products with which a customer can buy vouchers in the shop.

Example:
<g><1>y</1><2>purchase vouchers</2><3>y</3><4>y</4></g>

Types of free fields

In addition to the name, a "type" can also be specified when creating a free field in the WSPManager.

For the types "Text Enumeration" and "Meta Field" the format of the fields must be observed, all other types can contain any text.

Text enumeration

The individual points of the enumeration must be framed with <g></g>.
Example:
<g>item 1</g><g>item 2</g>

Meta field

A meta field allows you to write multiple product attributes in a single field, these attributes can then be displayed individually in the shop.

The individual values are each framed by tags formed from the sequential number of the product attribute.

Example:
<1>Feature-Description</1><2>ImageToFeature.jpg</2><3>PDFToFeature.pdf</3>

Product data and variation values for dependent variants (PRD files)

A separate PRD file must be created for each product with dependent variants. The contents of the file are the values of the dependent variants and the variant product data. The name and directory of the file corresponds to the one entered in the "DepVarFile" field in the wpupdate.csv/wpcomplete.csv file.

Variation values

The variation values are passed in columns whose heading starts with the prefix "$Var_". So the different values for the variation "Size" would be in the column "$Var_ Size" for example.

For each variation specified in the "DepVariations" field of wpupdate.csv/wpcomplete.csv, there must be a corresponding column in the PRD file of the product.

Important: The order of the "$Var_" columns must be the same as in the "DepVariations" field of wpupdate.csv/wpcomplete.csv. So if "DepVariations" contains e.g. contains the value "<g><vn>vn1</vn></g><g><vn>vn2</vn></g>" then in the PRD file the column "$Var_vn1" must be before resp. left of the column "$Var_vn2".

Note that the order in which the variation values are placed in the PRD file also determines the order in which the values are offered for selection in the online shop.

"Unused" variation values

Occasionally, some of the variations may be skipped in the shop.

Ex: You offer cell phones in your shop, either with contract or without contract. One of the dependent variants would have the values "With contract" and "Without contract". Other variants would be "Network" (e.g. "T-Mobile") and "Color". As soon as the customer selects the variation entry "Without contract", it no longer makes sense to ask him for the desired network. In this case, this variation should not even be displayed in the shop; the customer should only have to select the desired color.

For such cases the special value "$_$" can be imported for a variation value to mark it as unused.

The relevant part of the PRD file for this case could look like this, for example:

Note that you cannot mix the "$_$" value with other, normal variation entries. So the following lines in the example file above would be incorrect:

The values for the first variation are the same in these two lines. Since the value "$_$" is used for the second variation, this value must be used for all lines that have "Without contract" as value for the first variation.

If "$_$" is to be used as value for the third or a following variation, this logic applies analogously.

Deviating product data

In addition to the variation values, the PRD file can also contain (from the data in the wpupdate.csv/wpcomplete.csv) deviating product data. The column headings and data formats in the PRD file correspond to those in the wpupdate.csv/wpcomplete.csv.

If there is a column with a product data field, the values specified there will overwrite those specified in the wpupdate.csv/wpcomplete.csv as soon as the customer has selected the corresponding variation entry in the shop. This is true even if the value is empty!

If you do not want the value from the wpupdate.csv/wpcomplete.csv to be overwritten for individual entries in the PRD file, you can achieve this by entering a hyphen ("-") as the value.

A few product data fields are excluded from use in PRD files:

• BestPrice

• ChildProducts

• DepVarFile/DepVariations

• Event

• EventDiscount

• EventProductNumber

• InsertList

• License

• SearchItems

• Test

• Variations

• ValidUntil

• ValidFrom

Finally, there is a field "VarIndex" in the PRD file whose meaning is analogous to the field "Prodindex" in the file wpupdate.csv/wpcomplete.csv. The content of this field must be unique subshop-wide.

Example:

In this example, the product numbers and the product images are adjusted to the selected variation entry. For the entry L/yellow "-" is entered as value, which means if this entry is selected, then the image entered in the wpupdate.csv/wpcomplete.csv file is displayed in the shop.

A maximum of 100000 dependent variants can be imported for a product. However, it is recommended to stay well below this limit, because the online shop already becomes noticeably slower with more than 10000 dependent variants, i.e. the customer in the shop has to wait more or less long after each selection until the displayed page is updated.

Deleting product data (wpdelete.csv)

This file contains products that should be deleted from the subshop. The file contains a single column named "ProdIndex".

Example:
ProdIndex
123-abc
789-xyz

Product category assignments

Create and modify (catupdate.csv/catcomplete.csv)

These files contain the assignments of the products to the categories in the subshop. When importing the catupdate.csv file, only the content of the categories listed in the file is updated. The content of all other categories remains unchanged. On the other hand, when importing the catcomplete.csv file, the content of the categories for which no data is provided in the file is deleted, i.e. this file must contain all the product-category assignments for the subshop.

The format of the two files is identical, they contain the following fields:

Example:

Remarks:

• If data is supplied for a category, then all mappings must be supplied. Assignments that are not present in the file will be deleted from the category.

• An explicit specification of the order is optional, if the field "Order" is missing the products will be read into the shop in the order they are in the file.

• For the products existing in a catcomplete.csv, the associated product data must be supplied in the wpcomplete.csv (and any necessary PRD files).

• For the products present in a catupdate.csv, the associated product data must be supplied in the wpupdate.csv and (possibly necessary PRD files), if the products are not already present in the shop.
  If possible it is recommended to import the data of the products existing in the catupdate.csv nevertheless always with the associated wpupdate.csv file. An advantage of this approach is that the import is faster, because access to individual products in the shop is slower than to the product data in the import files.
  Furthermore, it is a difficult task for the system that creates the import files to keep track of which products are already in the shop, so errors can easily occur that lead to missing products in the shop.

Deleting product category assignments (catdelete.csv)

This file makes it possible to delete all product assignments from a category without having to re-read all assignments with the file catcomplete.csv. This is not possible with catupdate.csv, because the content of categories that do not appear in this file remains unchanged.

The file contains a single column named "CatIndex", which contains the category index of those categories from which all products should be removed.

Example:
CatIndex
cat-1
cat-2

Category data (catcomplete.xml)

You can either maintain the category data in the WSPManager or import it via the "catcomplete.xml" file. Which of the two options is active is determined during activation. If you want to switch from manual maintenance to import (or vice versa), you have to contact WEBSALE AG.

In the case of the maintenance of the category data with the WSPManager this must take place on the same PC on which also the import takes place.

In case of the import solution the file "catcomplete.xml" must contain the complete category structure of the shop. Categories that are not in this file will be deleted during the import.

As the only import file, the "catcomplete.xml" has an XML format, because this format is more compact for hirarchical structures with many optional fields.

The root element of the file is called "categories", below it is the element "menucategories" and the optional element "nomenucategories". Below "menucategories" are the "category" elements with the actual category data.

Below "nomenucategories" the data of the "Happy Hour" categories can be passed. Other categories should not be there.

Category data is passed as attributes or as sub-elements of the "category" tag. Subcategories are also imported as subelements.

The "category" tag has the following attributes:

The following (optional) sub-elements can be included in the "category" tag:

Example:

Hidden categories

The import of hidden categories is done in the same way as the import of categories that should be displayed in the shop menu, with the one difference that for these categories in the sub-element "hide" the value "y" must be passed.

Example:

In this example the category "Show in Menu" is shown in the shop menu, the category "Do not show in Menu" is not shown.

Stocks (amountupdate.csv)

This file contains the stock levels for the products. Unlike most other import files, this file is imported only once per shop, so it applies to all subshops.

The background is the consideration that products offered in different subshops are usually in the same warehouse. If the stock would be managed per subshop, the shop would calculate with an incorrect stock.

Example:
A shop has the two subshops "German" and "English", the product "abc" has a stock of "5". If the stock in the two subshops were managed separately, 10 pieces of the product "abc" could be sold in the online shop, although only 5 pieces are available.

If the stock management is to be separated for different subshops, this can be achieved by giving the products different stock item numbers for each subshop, e.g. "abc-german" for the German subshop and "abc-english" for the English subshop.

The file contains the following fields:

Example:
StoreId<TAB>Amount<TAB>Notification<CRLF>
prod-1<TAB>25<TAB>10<CRLF>
prod-2<TAB>18<TAB>10<CRLF>

Customer dependent prices

Create and modify customer dependent prices (c-priceupdate.csv/c-pricecomplete.csv)

These two files contain the customer dependent prices of a subshop. Normally they are imported together with the product data, but they can also be read in independently of these files.

Optionally, this file can also be used to import the normal, non-customer-dependent prices and scale prices. This can be useful if the readout of the prices from the exporting system takes a lot of time and it therefore makes sense for performance reasons to import changed product data without the associated (unchanged) prices.

When importing the c-priceupdate.csv file, only the prices that appear in the import file are updated, the rest remains unchanged.

On the other hand, when importing a c-pricecomplete.csv, all customer-dependent prices that are not included in the file are deleted.

The files contain the following fields:

General remarks

• If for an item both prices for a specific customer number and prices for a price group are specified: In this case, the prices specified for the customer number will be used when a customer logs in who has the matching customer number and belongs to the corresponding price group.

• For each customer/prodindex combination in the file there should be an entry with Quantity=0.

• If customer-dependent prices for dependent variants are to be imported, then a price for the variants must also be specified in the associated PRD file.

• When a product is deleted, the (customer-dependent) prices of the product are always deleted as well.

Remarks to the optional import of non-customer dependent prices

• The import of non-customer dependent prices via the c-price* files must be enabled by WEBSALE AG.

• When importing non-customer dependent prices the field "Customer" must remain empty, for CustomerType the value "0" must be passed.

Remark for update of existing prices

For the update, all fields except "Price" are considered as key fields, i.e. if all these fields match an already existing entry in the price table, the price will be updated, otherwise a new entry will be created in the price table.

Example:
A c-pricecomplete.csv with the following content is imported:

Then a c-priceupdate.csv with this content is imported:

Then the price table of the shop would have the following content afterwards:

For the entry with Quantity "0", the price was changed from 9.99 to 10.00 because the import file contained a row where ProdIndex, Quantity, Customer and CustomerType matched an entry already in the price table.

The entry with Quantity "5" was newly added to the table because no matching entry was found.

Finally, the entry with Quantity "3" remained unchanged from the first import.

Deletion of customer dependent prices (c-pricedelete.csv)

The c-pricedelete.csv file contains the customer dependent prices to be deleted.

The file contains the following fields:

Remarks:
If the Customer field is empty, all prices of the specified product will be deleted, otherwise only those of the customer matching Customer/CustomerType.

• Deleting prices for a customer will delete all scale prices for the customer. Explicit deletion of a specific scale price (e.g. the price for quantity 5 of customer "abc") is not provided.

• If in an import file both a line with an empty customer field and a line with a filled customer field appear, all prices of the product will be deleted.

• The c-pricedelete.csv is read before the c-priceupdate.csv, so that prices can be deleted first and then inserted again.

Online prices

"Online prices" are intended for products whose price changes frequently, in the import files wpupdate.csv or wpcomplete.csv they are marked by setting the field "OnlinePrice" to the value "y".

similar to the customer-dependent prices, the online prices can be imported independently from the rest of the product data, furthermore the price changes that occur during the order process are handled specially by the shop.

As far as the import is concerned, there are the following differences between the "Online prices" and the "Customer dependent prices":

• Online prices cannot be customer dependent

• There is no quantity dependency

• The product number is used for addressing instead of the product index

All import files for online prices are stored in the import directory of the subshop.

Creating and changing online prices
(onlinepriceupdate.csv/onlinepricecomplete.csv)

When importing the onlinepriceupdate.csv file, only the prices that appear in the import file are updated, the rest remains unchanged.

On the other hand, when importing an onlinepricecomplete.csv, all customer-dependent prices that are not included in the file are deleted.

The files contain the following fields:

Deleting online prices (onlinepricedelete.csv)

When importing the onlinepricedelete.csv, all online prices that are in the file are deleted.

The file contains the following field:

Remarks:

• An implicit deletion of online prices does not take place, i.e. if a product is deleted from the shop via wpdelete.csv, the online prices are still preserved.

• The file onlinepricedelete.csv is read before the files onlinepriceupdate.csv and onlinepricecomplete.csv, so that prices can be deleted and created again during an import.

Combinations for the dependent search (depsearchcomplete.csv)

Note: It is generally not necessary to generate the import file described below if you want to use the "dependent search" function in your shop. Normally it is sufficient to configure the free fields to be used for the dependent search in the WSPManager and then import only the product data as usual.

You only need to import the dependent search if you want to specify yourself the possible combinations of field values that the customer can select in the shop.

Example:
You offer spare parts for cars in your shop, as free fields for the dependent search you use "Manufacturer" and "Model series". A certain spare part (e.g. a lamp) fits now for the manufacturer/model series "Alfa Romeo"/"145", "Alfa Romeo"/"146", "Seat"/"Ibiza" and "Seat"/"Malaga".

Since in the above example the values for the H4 lamp in the Manufacturer field are "Alfa Romeo, Seat" and in the Model Series field "145, 146", there is no apparent assignment of which combinations of manufacturer and model series are valid in each case. If you now let the shop generate the selection lists, then if you select the value "Alfa Romeo" in the "Manufacturer" list box, the "Model series" list box would contain the value "Alfa Romeo".if you now leave it to the shop to generate the selection lists, if you select the value "Alfa Romeo" in the "Manufacturer" list box, the values "145", "146", "Ibiza" and "Malaga" would be displayed in the "Model series" list box due to the missing assignment.

If you now want the selection of "Seat" to show only the model series matching this make

("Ibiza" and "Malaga") are displayed, you have to import permissible combinations yourself.

Structure of the import file

Unlike most other import files, the field names of this file are not fixed. Instead, the column headings correspond to the technical field names of the free fields to be used for the dependent search.

Example:
The import file for the above example might look like this:
Manufacturer<TAB>Model Series
Alfa Romeo<TAB>145
Alfa Romeo<TAB>146
Seat<TAB>Ibiza
Seat<TAB>Malaga

Activation of the import in the WSPManager

The WSPManager needs to know if you want the combination possibilities to be determined automatically or if you want to import the combination possibilities. For this reason, if you want to use the import, you must check the checkbox "Dependent search"/"Import of allowed combinations" in the WSPManager under "Shop settings"/"Divers".

Note
Even if you use the import function for the combination option, you must still import the associated values of the free fields in the product data, otherwise products will not be found in the shop!

Note that you can also enter (comma-separated) lists of values in the free fields, so that a product is found for several different search terms (in the example above, for example, the lamp is found when searching for "Alfa Romeo" and when searching for "Seat").

Product dependent delivery costs (deliveryupdate.csv/deliverydelete.csv)

With the help of these two import files it is possible to calculate your shipping costs by WEBSALE product-exactly.

The calculation refers to:

• The order quantity of a shipping group or article number

• The shipping costs (country-dependent and supplier-dependent)

• The postal code of the recipient (optional)

Structure of the file deliveryupdate.csv

Structure of the file deliverydelete.csv

The file contains the following fields:

Discount groups

With the help of discount groups, (groups of) products can be assigned quantity- or price-dependent discounts. Optionally, these discounts can also be made customer-dependent.

The associated files are stored in the import directory of the shop or subshop. If the file is in the import directory of the shop, it applies to all subshops. If it is in the directory of a subshop, it applies only to that subshop. If there is a discount.csv in both the shop directory and the subshop directory, the subshop file is used.

Customer independent discount groups (discount.csv)

The entries in this file are read by the shop from top to bottom, the last matching entry determines the discount to be used.

This specifically means that lines with higher "Amount" values must be written below lines with lower amounts. Similarly, lines where the ValidFrom or ValidUntil fields are filled must be written below lines where these fields are not filled.

Customer dependent discount groups
If you want to offer different discounts depending on which customer has logged in, you have to generate a separate file for each (customer) discount group.

The name of the file is "discount_" + customer discount group + ".csv". For example, if you have used the customer discount group "abc" in the customer data, then the file would be named "discount_abc.csv ".

How to assign customers to a customer discount group is explained in the documentation "Customer data PRO".

The structure of the files for customer-dependent discount groups is identical to the structure of the customer-independent files, as is the directory.

Deleting discount group files
Once imported, files cannot be deleted, but you can overwrite them with empty files or files that contain only one header line.

Customer dependent product numbers

Creating and changing customer dependent product numbers (custpnumbersupdate.csv/custpnumberscomplete.csv)

Customer-dependent product numbers can be used to display customer-dependent product numbers in the shop for registered customers, which differ from the product numbers in the product data.

When importing the custpnumbersupdate.csv file, only the product numbers that are in the import file are updated or created, the rest remains unchanged.
When importing a custpnumberscomplete.csv, on the other hand, all customer-dependent product numbers not contained in the file are deleted.

The files contain the following fields:

Example:
CustomerNumber<TAB>OrigProductNumber<TAB>CustomerProductNumber
12345671<TAB>1112223331<TAB>111a
12345671<TAB>1112223332<TAB>111b
12345671<TAB>1112223333<TAB>111c
12345672<TAB>1112223331<TAB>11133a
12345672<TAB>1112223332<TAB>11133b

Remarks:

• Only one customer-dependent product number (CustomerProductNumber) can be imported per customer number and per original product number (OrigProductNumber). If there are several lines for the same customer and the same product in the import file, only the last line will be taken over.

• The customer-dependent product numbers must also be imported in the "CustomerProductNumbers" field in the product data (wpupdate.csv/wpcomplete.csv).

Deleting customer dependent product numbers (custpnumbersdelete.csv)

The file "custpnumbersdelete.csv" can be used to delete entries that were created with the files "custpnumbersupdate.csv" or "custpnumberscomplete.csv".

The file contains the following fields:

Example:
CustomerNumber<TAB>OrigProductNumber
12345671<TAB>1112223331
12345672<TAB>*
*<TAB>1112223332
Remarks:

• If there is a "*" for CustomerNumber in the file, all entries stored in the shop with the specified OrigProductNumber will be deleted.

• If there is a "*" for OrigProductNumber in the file, all entries stored in the shop with the specified CustomerNumber will be deleted.

• If a customer or a product is deleted from the shop, the associated customer-dependent product numbers are not automatically deleted.

Miscellaneous shop parameters (parameter.ini)

For parameters that affect the import but do not fit into any of the other import files, there is the import file "parameter.ini". The file described in this section contains settings that affect all subshops (see also "Miscellaneous subshop parameters").

The structure of the file is the same as the other "INI" files of the shop, i.e. it is divided into sections containing name/value parameters:

The only valid section is currently "Inventory", the only valid parameter is "ValidDateTime". This parameter specifies the time to which the imported inventory data refers.

The format of the parameter is YYYYMMDDhhmmss so e.g. "20060523163310".

The reason for this parameter is that creating the stock import file, importing and transferring this data takes more or less time. During this process, orders may continue to arrive, so the stock finally set may differ from the actual one.

Example: At 14:05 the amount.dat is created, for the product xyz 5 pieces are still in stock at this time, but the stock for the product is actually set in the online shop at 14:15. At 14:13 a customer orders 4 pieces of the product, if the inventory is imported "normally", i.e. without specifying ValidDateTime, then 5 pieces would now be available in the shop, although (after delivery of the order of 14:13) only one piece is still in stock.

If in the above example "20090728140500" would be passed as "ValidDateTime", then when setting the stock at 14:15 all orders received between 14:05 and 14:15 would be subtracted from the stock, so the stock would be set to the correct value "1".

In order to use the function in the the parameter "SetOrderInventory-Allow" must be set to "yes" in the shop.config of the corresponding subshops in the section <Inventory>.

Miscellaneous subshop parameters (parameter.ini)

For parameters that affect the import but do not fit into any of the other import files, there is an import file called "parameter.ini". The file described in this section contains settings that affect a specific subshop (see also "Miscellaneous shop parameters").

The structure of the file is the same as the other "INI" files of the shop, i.e. it is divided into sections containing name/value parameters:

Section <Options>

In the "Options" section, currently the only valid parameter is "PreserveFields". This parameter can contain a comma-separated list of fields that should not be overwritten during import.

Note that this option only works for fields that are not used for searching, filtering, sorting or similar functions.

<ProductFields> section

The ProductFields section contains properties of product data fields that can be set via import. For each product data field for which properties are to be imported, the "ProductFields" section must contain a "Field" subsection.

Example:

The "Field" section can contain the following parameters:

Remark:

• If no parameter.ini is delivered during an import, the existing field settings remain unchanged.

• To use the sorting specified under "FilterSortSelect", the sorting "List" must be set under "Settings for filter list boxes" (in the WSPManager) for the field to be sorted.

Special topics

"Happy Hour" products

For products in the "Happy Hour" category a time control is active, which ensures that only a part of the products is visible in the shop at any time. Furthermore, a "Happy Hour" discount can be applied to the products that are currently visible in the category.

Products are imported into the "Happy Hour" category by assigning them to the "happyhour" category in the catupdate.csv/catcomplete.csv file, furthermore in the wpupdate.csv/wpcomplete.csv file the "Event" field must be set to the value "y".

With the optional fields "EventProductNumber" and "EventDiscount" a different product number and discount can be specified which will be used when the product is displayed in the "Happy Hour" category.

The settings of the "Happy Hour" category itself can be changed when importing the catcomplete.xml file ("eventrotationtime" and "eventproducts").

"Happy Hour" category

The "Happy Hour" category settings can be imported along with the rest of the category data in the catcomplete.xml.

"eventrotationtime" specifies the number of hours after which the products should be rotated, "eventproducts" specifies the number of products visible at the same time.

Note that the category is in the "nomenucategories" section and that the "index" and "type" attributes have the values "happyhour" and "event" respectively.

Shopping cart category

Items assigned to the "shopping cart" category are automatically added to the shopping cart during the checkout process.

Products are imported into the "shopping cart" category by assigning them to the "autobasket" category in the catupdate.csv/catcomplete.csv file.

The following restrictions apply to the products:

• The price must be 0.00.

• No input should be required when ordering, i.e. the product must not have any variants or text input fields.

• A maximum of 3 products can be assigned to the "Shopping Cart" category.

Since the shopping cart category does not support any settings such as templates or description and is not displayed in the shop menu, it does not need to be written in the catcomplete.xml.

The optional minimum order value, from which a product is added to the shopping cart, can be imported via the field "ABMinOrderVal" in the file wpupdate.csv/wpcomplete.csv.

Multiple images

It is possible to display so-called "multiple images" in the online shop in addition to the normal images. When displaying a product, these images are first displayed as a thumbnail, when you click on one of these thumbnails, it is displayed in normal size, replacing the original image.

In the WSPManager, a free field must be created for each multiple image and for each image size. If, for example, three multiple images are to be displayed (in addition to the normal image), then the fields

Image_mini_1
Image_mini_2
Image_mini_3
Image_small_1
Image_small_2
Image_small_3
Image_medium_1
Image_medium_2
Image_medium_3
Image_large_1
Image_large_2
Image_large_3

must be created.

The type of the free fields must be set to "Media image mini", "Media image small", "Media image normal" and "Media image large", respectively according to the size of the image.

The image files are stored like the normal product images in the directories ".../products/media/images/mini", ".../products/media/images/small", ".../products/media/images/normal" and ".../products/media/images/large".

In the free fields themselves there is then only the image name without path.

If less than (in this example) three multiple images are to be displayed for a product, the excess field names are simply left empty.

No longer existing products / no longer existing categories

"No longer existing products" and "No longer existing categories" are procedures for "link recovery" of deleted products and categories: They are used to prevent links to products or categories from "going nowhere" when products or categories are deleted.

Instead, calls to deleted products or categories can be redirected to other products or categories using these techniques.

To use the "Discontinued Products" feature you must import the "Discontinued" field in the import data with the value "y" during import. The product will then be deleted from the shop and calls to the product will be redirected to the category where the product was.

Alternatively, in the DiscontinuedSubstitute field, you have the option to specify the product index of a replacement product to which calls should be redirected.

A product needs and should be imported as "Discontinued" only once, note that all product data (including any existing variants and assignments to categories) must be supplied again in the process.

For the function "Discontinued categories" you do not need to change anything in the import data, it must only be activated by WEBSALE AG for your shop.

A call of a deleted category will be redirected to the next category, which is above the deleted category in the hierarchy and which still exists.

Both the function "No longer existing products" and the function "No longer existing categories " must be enabled by WEBSALE AG.

Service products

"Service products" are products that can no longer be ordered in the shop and are no longer assigned to a category, but can still be found via search and accessed via deep links.

The purpose of "Service Products" is to provide customers with information (e.g. technical data, download of manuals) about the products even when they are no longer sold in the shop.

"Service products" are imported by setting the "Service" field in the import data to the value "y". All data that should be displayed for the service product in the shop must be supplied again.

An assignment of a service product to a category is not necessary or not allowed.

It is sufficient to import a service product once, service products remain in the shop even with complete imports if no import data is supplied for them.

If a service product is to be deleted, this must be done explicitly via the import file wpdelete.csv.

The "Service products" function can be combined with the "No longer existing products" function. Note that in this case, however, the product index of the product is renamed by prefixing it with "sp_".

This renaming is necessary because otherwise a deep link to the service product would be redirected to the replacement category or product.

If a product should be "service product" and "discontinued" at the same time, the fields "service" and "discontinued" must also be set at the same time. I.e. it is not possible to import a product as "Service product" and set it to "discontinued" on a later import (or vice versa). Both flags must be set on the same import.

The function "Service products" must be enabled by WEBSALE AG.

Favourable time-dependent prices (BestPrices)

No time dependency can be specified in the "Best price" field (which contains the most favourable price for a product with variants). If time-dependent prices are used in a shop and this time dependency should also be taken into account when determining the best price, the "BestPrices" field can optionally be generated during import.

To do this, the parameter "CreateBestPrices" must be inserted in global.config:

The "BestPrices" field is then generated from the "AltPrices" and "Price" fields in the PRD files, from which the shop can determine the most favourable price for each point in time.
The actual import data does not need to be changed.

As this is a time-consuming process that extends the runtime of the import, the feature should only be activated if it is actually needed.

Protection against empty imports

In the file global.config in the directory "configuration" of the shop minimum values for the number of categories and (category assigned) products can be configured:

Before starting the import, a check is made for each subshop to see if the specified numbers are likely to be undercut after the import. If yes, then the import for the subshop will be aborted or not started at all.

During this pre-check only the files "catcomplete.xml", "catcomplete.csv" and "wpcomplete.csv" are checked. I.e. with delta imports the function does not take effect.

The purpose of the feature is to prevent the shop from being empty if incomplete data is imported by mistake.

Example files

The following sample files are part of this documentation, which you can download on the subordinate page: