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:

File name	Validity	Content and function

File name	Validity	Content and function
wpupdate.csv	Subshop	This file contains the data of products to be changed or added.
wpcomplete.csv	Subshop	The format of this file is identical to wpupdate.csv, but it must contain all products of the subshop. Products that are not included in this file will be deleted. The import of wpcomplete.csv requires the import of catcomplete.csv.
wpdelete.csv	Subshop	This file contains the product data to be deleted.
*.prd	Subshop	The data of dependent variants are stored in a separate file for each product. The name of these files is formed from the product index, the extension is "prd".
catupdate.csv	Subshop	This file contains category contents to be changed. For the products listed in this file, the associated product data must be supplied in the wpupdate.csv or already exist in the shop.
catcomplete.csv	Subshop	The format of this file is identical to catupdate.csv, but it must contain all product category assignments. From categories that are not present in this file all assigned products will be removed.
catdelete.csv	Subshop	This file contains the categories from which all products should be removed.
amountupdate.csv	Shop	This file contains the amount of stock of the products to be changed.
c-priceupdate.csv	Subshop	This file contains the (customer dependent) prices to be updated.
c-pricecomplete.csv	Subshop	The format of this file is identical to that of "c-priceupdate.csv", but the file must contain all customer-dependent prices of the subshop. Prices not included in the file will be deleted from the shop.
c-pricedelete.csv	Subshop	This file contains the (customer dependent) prices to be deleted.
catcomplete.xml	Subshop	This file contains the data of the categories themselves.
depsearchcomplete.csv	Subshop	Contains the possible combinations for the dependent search
deliveryupdate.csv	Shop	This file contains the entries of the product-dependent delivery costs to be updated/newly inserted
deliverydelete.csv	Shop	This file contains the entries of the product dependent shipping costs to be deleted
parameter.ini	Shop	Various parameters that do not fit into any other import file
parameter.ini	Subshop	Various parameters that do not fit into any other import file
discount.csv	Shop/subshop	Discount groups
custpnumberscomplete.csv	Shop	Contains all customer dependent product numbers
custpnumbersupdate.csv	Shop	Contains the customer dependent product numbers to be changed or added
custpnumbersdelete.csv	Shop	Contains the customer dependent product numbers to be deleted
onlinepricecomplete.csv	Subshop	Contains all online prices (of the subshop)
onlinepriceupdate.csv	Subshop	Contains the online prices to be changed or added
onlinepricedelete.csv	Subshop	Contains the online prices to be deleted

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:

<ProductImportPro>
  ConvertCharset    = yes # [yes|no], standard = no, convert character set when importing product data
  ImportCharset     = UTF-8 # standard = UTF-8, character set in which the import files are delivered
  UnknownCharacters = mapreplace # [ignore|stdreplace|mapreplace], standard = ignore
</ProductImportPro>

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.

<+ImportCharsetConvertMap>
	Charset = ISO-8859-1
	a = %c4%83
	I = %c3%8e
	%56 = %c3%8e
</+ImportCharsetConvertMap>

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:

Data Type	Description

Data Type	Description
S1	String (type 1) with all printable characters except TAB and CR/LF
S2	String (type 2) only with the allowed characters: 0..9 a..z A..Z Dot ".", colon ":" Slash "/", backslash "\", hyphen "-", underscore "_"
S3	String (type 3, alphanumeric) only with the allowed characters: 0..9 a..z A..Z
S4	String (type 4, ASCII) with all printable characters except TAB and CR/LF of the ASCII code or the first 128 characters of the ISO-8859-X codes.
I	Signed Integer, i.e. integer values with an optional sign. Only digits and signs are allowed. No other characters, especially no dots as thousand separators. Example: 25 -312 +13
U	Unsigned integer, i.e. integer values without sign. Only digits are allowed. No other characters, especially no dots as thousand separators. Example: 25
F	Float, i.e. "floating point numbers" with optional sign and optional decimal places. Decimal places are separated by a period (the comma is not allowed). Example: 1 1.0 -1.00 1002033 10033.80 Not allowed: 111.1 121,004.20

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:

Field name	Allowed characters/ max. length	Meaning/Format

Field name	Allowed characters/ max. length	Meaning/Format
ProdIndex	S1/64	A unique ID for the product within the subshop. This field is the only required field in the file. Example: "78459abc"
Name	S1/128	The product name. Example: "Coffee maker, stainless steel".
Name2	S1/128	An additional name of the product.
Number	S1/64	The number of the product/product number. Example: "78459-abc".
AltNumber1 AltNumber2 AltNumber3 AltNumber4 AltNumber5	S1/64	Fields with "alternative product numbers". The numbers imported in these fields can be used for direct orders as an alternative to the value entered in the "Number" field.
InsertList	S1/4000	A comma-separated list of promotional codes allowed for the product. Example: "01,XY,58".
Descr	S1/16000	The product description. Example: "Highest product quality through..."
Shortdescr	S1/1024	The product short description. This description can be used e.g. in product lists, alternatively a version of "Descr" automatically shortened by the shop can be displayed there.
Image	S2/128	The name of the normal sized product image. Example: "78459abc.jpg".
Thumbnail	S2/128	A small product image for use in product lists. Example: "78459abc.jpg"
MiniThumbnail	S2/128	An extra-small product image, e.g. for display in the shopping cart. Example: "78459abc.jpg"
LargeImage	S2/128	An extra large product image, e.g. to be displayed in the shop by clicking on an "enlarge" link. Example: "78459abc.jpg"
Unit	S1/64	The (packaging) unit in which the product can be ordered. Example: "Piece". If a packaging unit contains several pieces, this number can either be entered in the unit field or imported separately in a free field. In the first case, the number of pieces will also be displayed in the shopping cart and included in the order data, in the second case it will not.
UnitCode	S1/64	A code for the unit in which the product can be ordered. In contrast to "Unit", this value is not intended to be displayed in the shop, but to be evaluated when the orders are read in by a MMS. Example: "Stck".
UnitFactor	F/8	When using this field, only multiples of the unit specified under "Unit" can be ordered. Example: "3", in this case only 3,6,9 etc. Pieces could be ordered.
UnitFactorGroups	S1/4048	The value of the UnitFactor field (see above), can be imported depending on the customer. In the customer data, a group ID ("UnitFactorGroupID") must be specified for this purpose. In the product data, the corresponding unit factor must be imported for each group ID. Format: <g><1>GroupID</1><2>UnitFactor</2></g>. Example: <g><1>wholesale</1><2>10</2></g>
QuantityScaling	S1/1024	Specifies the allowed order quantities. Unlike "UnitFactor", all allowable quantities must be listed in a comma separated list. Example: 1,5,8
AdditionCostFactor	F/8	Allows to adjust the cost of shipping for individual products. The value specified here is multiplied by the number of items ordered and a factor to be configured in the "shop.config" and then added to the shipping cost. Example: "2.5"
FreeDelivery	S1/1	"y" if no shipping cost should be charged for the product.
DeliveryCostGroup	S1/64	The delivery cost group for the product dependent delivery costs.
VATIndex	Permissible values: 1...15	Defines the VAT rate of the product. The percentage belonging to the VATIndex is configured in shop.config. Example: "1".
Price	F/8	The "normal" price of the product. Example: "1.99
AltPrices	-	Time-dependent, alternative prices. See "Meta fields" for format description and example.
OrgPrice	F/8	An "old price" a "recommended price" or something similar. The shop can automatically display the difference between "OrgPrice" and "Price" as savings. Example: "2.85
OrgPrices	-	Corresponds to the "OrgPrice" field in terms of content, but time-dependent prices can be specified in "OrgPrices". See "Meta fields" for format description and example .
BestPrice	F/8	If a product has dependent variants, then the cheapest price of all variants should be entered here. Before all variants are selected in the shop, this price can then be displayed as "From price" (e.g. "from 2.25 EUR"). Example: "2.25
BestPriceData	S1/128	If ‘BestPrice’ is filled, the variation index (‘VarIndex’) and the product number of the variant with the most favourable price can be entered here. Format: <4>variation index</4> <5>product number</5> The content of the field can be used to load and display data of the ‘cheapest variant’ in the shop template.
BestPiecePrice	F/8	If the number of pieces is imported as a variant, then the best price per piece can be passed in this field,
BestPiecePriceQuantity	F/8	The quantity belonging to "BestPiecePrice
MaxPrice	F/8	If a product has dependent variants, then the highest price of all variants can be entered here. Together with "BestPrice", "MaxPrice" can be used to display a price range (from ... to ...) before a variation is selected.
MaxPriceData	S1/128	As with BestPrice/BestPriceData, the product number and the variation index of the variant with the highest price can be transferred here. See BestPriceData
BulkDiscount	Max. 100 prices	The scale prices. See "Meta fields" for format description and example.
BulkDiscountId	S1/64	The scale price ID. Products with the same scale price ID are considered the same for the scale price calculation. Example: All T-shirts in a shop have got the scale price ID "TShirt", starting from the purchase of 3 pieces a reduced scale price applies. If a customer orders one piece of t-shirt "A", one piece of t-shirt "B" and one piece of t-shirt "C", he pays only the reduced price. Without using the scale price ID he would pay the full price.
BulkDiscountPrices		"Promotional" prices, i.e. prices that depend on time and quantity. See "Meta fields" for format description and example.
AreaProductPriceScale		Scale prices for area products. For format description and example see "Meta fields".
ValidFrom	U/10	Time/date from which the product should be displayed in the shop as Unix time. Example: "1210892400".
ValidUntil	U/10	Time/date up to which the product should be displayed in the shop as Unix time. Example: "1210986000"
TextInputFields	Max. 10 fields	The text input fields. For format description and example see "Meta fields".
SearchItems	S1/256	Terms that should be considered in the search, but not displayed in the online shop. This field is used for a full text search, i.e. no special formatting needs to be observed. Example: "Term1,Term2 Term3".
MerchantName	S1/64	The name of the manufacturer or supplier of the product. Example: "Meier AG".
MerchantID	S1/64	An ID of the manufacturer or supplier of the product. In contrast to MerchantName, this field is not intended for display in the shop but for evaluation when reading in orders.
Weight	F/8	The weight of the item in any unit, but it must be the same for all products. Example: "5.0
Volume	F/8	The volume of the item in any unit, but it must be the same for all products. Example: "8.0"
Length	F/8	The length of the item in any unit, but it must be the same for all products and should be aligned with that of "Volume". Example: "1.0"
Height	F/8	The height of the item (see Length). Example: "2.52
Width	F/8	The width of the item (see Length). Example: "0.42"
MinQuantity	U/7	The minimum order quantity for the product. Example: "3"
MaxQuantity	U/7	The maximum order quantity for the product. Example: "25".
QuantityDecimal	Permissible values: 0...6	The allowed decimal places for the order quantity. Normally a customer can only enter integer order quantities in the shop, by using this field you can also allow floating point values. Example: "2
Event	S1/1	Enter "y" here if the product is displayed in the "Happy Hour" category. Note that the product must also be assigned to the "Happy-Hour" category via the catupdate.csv/ catcomplete.csv files.
EventProductNumber	S1/64	A different product number that will be used during the "Happy-Hour".
EventDiscount	F/8	Discount in percent that will be applied to the product during the "Happy Hour". Example: "7.0
Variations	Max. 200 variations; and 2000 entries	The "normal" variations. See "Meta fields" for format description and example.
DepVariations/ DepVarFile	Max. 200 variants; and 100000 entries. Recommendation: The number of entries should not exceed 10000, because with increasing number the display in the shop becomes slower.	The "dependent" variants. See "Meta fields" for format description and example.
CrossLinks	Max. 200 entries	Cross-links, cross-selling links, etc. For format description and example see "Meta fields".
Inventory	-	Inventory data For format description and example see "Meta fields".
StoreId	S4/64	The "stock item number" of the product. Normally the stock of an article is assigned via the product index. If a different ID is to be used, it can be entered here. Example: "087-XYZ
StockEmail	S1/128	An e-mail address for notifications when the reorder level is fallen short of. If this field is empty, the address configured in shop.config is used. Example: "info@shop.de"
OrderInfo	S1/16000	This field can be used to write data that should not be displayed in the shop but is required in the order data, e.g. an internal article number.
Test	S1/1	"y" if the product should not be displayed in the shop. By appending "&test=on" to the URL of the shop call, the products marked in this way can be displayed in the shop for test purposes.
HideForBasket	S1/1	"y" if the product should not be displayed in the shopping basket.
BookDelivery	S1/1	"y" if a special book delivery shipping cost should be calculated for the product.
SoldOut	S1/1	"y" if the product should not be orderable in the shop.
Export	S1/1	"n" if the product should not be exported by the "PricePush" and "External search system" services.
License	S1/1	"y" if the product is a "license article". When purchasing a license article, the customer receives a license number. Typically, this is software that can be freely downloaded, but can only be used without restrictions after a license number has been entered.
DiscountFactor	F/8	The "(customer) discount factor". The discounts granted are multiplied by this factor. By default, every product is discountable (DiscountFactor = 1), even if the field is left empty. If no discount should be granted for a product, this can be achieved by entering "0" here. Example: "0.5
DiscountId	S1/64	The discount group. Example: "abc"
DiscountIDs	S1/4096	Specification of time-dependent assignments to a discount group (for ‘valid indefinitely’, 0 can be specified in <2>). Example: <g><1>from UnixTimestamp</1><2>to UnixTimestamp</2><3>DiscountID</3></g>
Discount	F/8	A discount in percent for the product that applies to all customers. Example: "7.89"
UserDiscountRate	F/8	Each customer who buys this item will be given the discount (in percent) specified here for the entire order and for all orders in the future. Example: "5.00"
BonusPoints	U/7	The number of bonus points that will be credited when this product is purchased. Example: "1500"
BonusDeny	S1/1	"y" if no bonus points can be redeemed when buying this product.
BonusProduct	S1/1	Bonus product ("y": product is a bonus product, any other value: product is not a bonus product) In contrast to the "normal" redemption of bonus points, premium products can only be purchased with the redemption of bonus points and you can explicitly specify for each product how many bonus points are required for the purchase.
BonusProductPrice	U/7	Bonus points needed to buy the product (only if BonusProduct=y)
Upload	S1/1	"y" if the purchaser can upload files during the purchase (typically for printed products).
Download	-	The data for download items. See "Meta fields" for format description and example.
Set	Max. 500 sub-articles	The set sub-articles of the product. See "Meta fields" for format description and example.
OnlyAsSetChild		“y” product can only be ordered as part of a set
ParentProdIndex	S1/64	The product index of the grouping parent article.
ChildProducts	-	The grouping child articles of the product. See "Meta fields" for format description and example.
AgeRestricted	U/7	Specifies a minimum age for the customer (typical application: DVDs, computer games, etc., 0: No age restriction)'
GiftPackage	S1/1	"n" if gift packaging is not possible for the product.
GiftPackagePrice	F/8	The extra price per piece if the product comes with gift packaging.
NoCampaignVoucher	S1/1	"y" if no promotional vouchers can be applied to the purchase price of the product (e.g. because this would violate book price fixing). Purchase vouchers can be redeemed for the product in any case.
NumSearchOnly	S1/1	"y": When searching in the online shop, only the field with the product number is searched, the content of all other fields is ignored. Any other value: The normal logic of the product search is applied.
AreaProduct	S1/1	"y": The customer can specify in the shop the desired dimensions in the shop. See also "AreaProductRange" under "Meta fields".
DenyPayments	S1/128	Excluded payment types This field contains a comma-separated list of payment type codes with which the customer cannot pay for the product. Examples for payment type codes: 1=Credit card 3=Cash on delivery 4=Direct debit 5=Prepayment 6=Invoice … You find all payment type codes in the documentation for designers: Zahlungsarten Codes

Dokumentation

Format and content - WS-SFTP-Produkte PRO (EN)

General

Transfer of import files

Overview import files

Character set of the import files

Character set conversion

Conversion of the "catcomplete.xml" character set

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

Conversion tables

Formats of the import files

General

Data types

Maximum length of fields

Product data (wpupdate.csv/wpcomplete.csv)

List of fields (unstructured)