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

General

This documentation describes the format and content of customer master data that can be sent to the shop.

Transfer of import files

The import files described below can be transferred in 3 ways.

Transfer via SFTP/REST

Step 1: Transferring the import files via SFTP
Step 2: Starting the import of the data via REST trigger

Since the trigger procedure is used in a similar way for different interfaces, it is described in the separate documentation "SFTP-REST-to-Shop (EN)".

Transfer via SFTP/SOAP

Step 1: Transferring the import files using SFTP
Step 2: Starting the import of the data using SOAP trigger

Since the trigger procedure is used in a similar way for different interfaces, it is described in the separate documentation "SFTP-SOAP-to-Shop (EN)".

Alternative transfer via WSPManager (previous version)

Data can also be transferred to and imported from the shop server using the Windows tool "WSPManager" provided by WEBSALE. This method should be used if, for example, no SFTP transfer or no REST/SOAP trigger can be implemented on the merchant's system.

The transfer via WSPManager is described in the separate documentation "WSPManager-to-Shop (EN)".

Format and character set of the files

The import files must be delivered in CSV format (character separated values).

The character used as field separator must be the tab character (ASCII 9). Other field separators are not allowed.

By using the tab separator, additional wrapping of text fields, e.g. by double quotes ("), is not necessary and also not allowed. All types of quotation marks are regular, permissible characters in the fields and may therefore be included directly in the data without any further marking.

The character set in which the data is encoded depends on the language of the country for which the shop is operated. The country ISO codes standardized on the Internet (e.g. ISO 8859-1) must be used. The use of UTF-8 is not allowed with WEBSALE V8, because otherwise many interfaces and services internally and to third party providers would deliver incorrect results.

Addressing of data records

In order to be able to access the master data of a customer specifically, key fields are required in the data. There are various key fields whose content is managed either by the shop, the ERP system or the customer.

To each customer data record belong only once occurring data such as the customer name or its address, but also multiple occurring data sets (multiple customer additional data) such as several deviating delivery addresses.

IDs with key function

Email

The primary identification of a customer in the shop is always via his email address.

From the shop's point of view, a new customer is therefore a customer who creates a new account in the shop with a new email address, i.e. one that has not yet been assigned to an account.

UserIndex of the customer master data (managed by the shop)

The UserIndex is a unique, numeric ID that is assigned exclusively by the shop when a new customer record is created in the shop database.

Possible cases of new creation in the shop

  1. A new customer registers in the shop

  2. An ERP system transfers to the shop a customer record previously unknown in the shop system.

To update existing records in the shop, an ERP system addresses a customer record using UserIndex.

CustomerID of the customer master data (managed by the ERP)

From the shop's point of view, the CustomerID is simply a string assigned by the shop operator. usually, the CustomerID is the unique customer number generated by the ERP system and used to reference the customer in the ERP system.

If an ERP system imports a new customer record from the shop system and then assigns a new customer number (CustomerID), the ERP system must inform the shop of this new customer number. In this case, the value that was transferred to the ERP together with the order or the customer data record (when collecting customer data changes) must be transferred as the user index. If the same customer number already exists in the shop, the import will be rejected as a duplicate.

TableIndex and ExternalID of the Multiple Customer Additional Data

These two IDs are used for addressing in tables of so-called "multiple additional customer data", i.e. for data records that can occur not only once but also several times. Such multiple, also several times per customer occurring data records can occur with 2 data types

  • Delivery addresses

  • Bank details

For each of these two data types there is a separate table in the shop.

TableIndex

The TableIndex is assigned exclusively by the shop when a new data record is created in one of the customer additional data tables.

The TableIndex is a unique numeric ID within the table.

Since there are three different customer additional data tables, the TableIndex values for the data records in each table can and do have the same values.

Example
A record in the table of delivery addresses can have the TableIndex "123", just as a record of a completely different customer in the table of bank details can also have the TableIndex "123".

ExternalID

From the shop's point of view, the ExternalID is simply a string that the shop operator has assigned. Usually, this is an index generated by the ERP system and used in the ERP system to reference one of several (multiple) delivery addresses of a customer, for example.

Rules of data transfer from ERP to the shop

New creation of a customer master data record

An ERP system transfers to the shop system a data record with a new CustomerID assigned by the ERP and a mail address not yet known in the shop.

The characteristic of a new creation is that the "UserIndex" field in the customer master data is empty.

In the course of importing the new customer master data into the shop database, the UserIndex is reassigned and then communicated from the shop to the ERP system via an export interface (see the documentation for the "SOAP-from-shop (EN)" interface).

The import of a customer record duplicate is rejected as an error and the record is discarded. A duplicate is recognized if the CustomerID or the mail address already exists in the shop database. Both CustomerID and mail address must therefore not exist in the shop. The remaining data, such as name or address, is irrelevant for the duplicate check of the shop during the customer data import!

Note:
In the case of a B2B shop, there may be an exception to the rule "New creation only if mail address does not exist". This is the case when using so-called "multiple accounts" (see the chapter "Multiple accounts" below). In this documentation, however, the standard case "a mail address may only exist once" is always treated in connection with the mail address.

Updating a customer master data record

An ERP system updates a data record that already exists in the shop by transferring all fields of the desired customer master data record.

The characteristic of an update is that the field "UserIndex" contains a UserIndex existing in the shop.

New creation of a multiple customer record

In a new creation, the same email addresses for different accounts can be passed to the shop. However, the CustomerID must be unique and must not already exist in the shop. If the CustomerID already exists, the record will be discarded.

Update of a multiple customer additional data record

An update of a multiple customer record is done via the UserIndex, as described in section above “Update of a customer master record.”

Examples of addressing

Assigning the IDs of new customers who register themselves in the shop

A new UserIndex, e.g. "123456", is generated in the shop database when a new customer master data record is created.

After the new creation, the shop transfers this UserIndex together with the other customer master data to the ERP system.

The transfer of the customer master data of the new customer takes place after his registration. Two cases are distinguished:

  1. transfer together with the order data
    if the customer has placed an order after the new creation of the account

  2. transfer by change of address data
    if the customer has not placed an order after the account was created

When transferring the customer master data, the CustomerID field (customer number) remains empty, since the shop does not yet know an ERP customer number (see the documentation for the "SOAP-from-Shop (EN)" interface).

The ERP system must now check the CustomerID field when reading in the order or change of address data and recognize that it is a new shop customer due to the non-existent customer number. It must then assign a new ERP customer number, e.g. "777888". This is immediately replicated back to the shop by the ERP system addressing the customer in the import file with the shop user index "123456" and passing the newly assigned ERP customer number "777888".

Assigning the IDs of new customers created in the ERP system

A new customer is created in the ERP system (e.g. by employees in the dealer's call center).
At least 2 fields are required to import a new customer into the shop:

  1. a new customer number

  2. a new email address

Both fields are required. The UserIndex, however, must be empty or 0 in this case.

Due to the missing UserIndex, the shop recognizes that this is a new creation and checks whether CustomerID or email already exist. If not, a new record with a new UserIndex is created in the shop database. The user indices of the created new customers can be queried via the SOAP function "GetAddedCustomers" (see the documentation "SFTP-SOAP-to-Shop (EN)").

Exceptions and options

eMarketingManager attachments

In addition to the shop, the WEBSALE-eMarketingManager (eMM), a newsletter system with extended functionality, also creates data records. These are

  • Mail address

  • optional address data

Since a newsletter usually only requires the specification of a mail address, the customer records created by the eMarketingManager (eMM) are usually without a password.

As a consequence, an ERP system usually discards a customer record from the shop that consists of a mail address alone, so the record also has no customer number in the customer database.

Here it is to be considered, if later a data record is to be imported from the ERP system with one of the same mail address:

  • Many ERP systems do not know the UserIndex of these records because they either do not read address data changes from the shop or have discarded the incomplete address data that eMarketingManager creates.

  • If these systems then try to create a new record with the same mail address, it will be rejected with an error message during import, because a mail address must not occur twice in the database.

For this reason, the mail address is also used for addressing under the following condition:

  • No UserIndex is specified in the import data from the ERP (i.e. from the ERP's point of view, it is the creation of a new customer)

  • A customer exists in the shop customer database with the mail address in the import data and without a password created and without a customer number in the shop database.

If these conditions are met, then the customer data from the import data will be written to the shop record that has the specified mail address.

Note:
This is also tolerable from the shop's point of view from a data security point of view, because the owner of the mail address had to undergo a double opt-in procedure when registering for the newsletter, thus clearly proving authorization to use the mail address.

Multiple accounts (eMail)

Multiple accounts are a feature that may be desired by the mail order company for a B2B shop.

By default, only one account can be created per mail address in a WEBSALE shop. However, if multiple accounts are allowed in a shop, it is possible to create multiple customer accounts with the same mail address, in deviation from the standard. Each of these multiple accounts then has its own password for login.

Multiple accounts should only be used in a shop in absolutely exceptional cases, as mail duplicates restrict some functions in the shop or even make them impossible.

Example of an application
A purchasing department with several buyers does not handle all purchase-related communication with individual mail addresses for each buyer, but with a single central purchasing mail address (e.g. einkaufsteam@firma.de). Nevertheless, each order in the shop should be traceably assigned to the individual purchaser. In this case, the login to the shop takes place with the same mail address, but each buyer has his own password. The combination mail / password ensures the assignment to the correct master data record of the respective buyer.

In the case of multiple accounts, there are thus several customer master data records with the same mail address in the shop.

Prerequisite for use
To use this feature, the shop must be specially configured. Please contact WEBSALE AG if multiple accounts are required.

Multiple accounts (CustomerID)

Normally it is not possible to create multiple customer records with the same customer number (CustomerID) via import, because they will be rejected as duplicates.

When using the "Multiple Accounts (CustomerID)" feature, this restriction is removed.

Compared to the feature "Multiple accounts (eMail)" there is the additional complication that the records in the individual import files (e.g. custupdate.csv and billcomplete.csv) are linked via UserIndex or CustomerID. In case of a new creation, however, the UserIndex must now have the value "0", so that in case of ambiguous CustomerIDs, an unambiguous assignment of the rows in the individual import files is no longer possible.

For this reason, when using "Multiple Accounts (CustomerID)", the "Email" field must be specified in each import file.

A combination of "Multiple accounts (CustomerID)" with "Multiple accounts (eMail)" is not possible for the same reason.

Prerequisite for use
To use this feature, the shop must be specially configured. Please contact WEBSALE AG if multiple accounts are required.

Mail addressing

Normally an import record with an empty user index (or user index = 0) is rejected as a duplicate if the mail address specified there is already used for a customer record in the shop.

If "Mail Addressing" is activated, the record with the specified mail address will be overwritten instead in this case.
The same is done if the user index specified in the import data does not exist in the shop database, i.e. a record with matching mail is searched for and overwritten.

Advantages

A certain "error tolerance" is achieved. If a customer is created in the ERP system who has already registered himself in the shop, then the import normally fails, because the import data record is marked as "new creation" and the mail is already assigned.

This case may occur if the ERP has not (yet) read the customer created in the shop. This can happen if the customer was created in the shop and in the ERP at the same time or if the ERP has explicitly refused to read in the customer data record (e.g. because of an incomplete address).

Furthermore, a customer record can still be imported if there is an incorrect user index in the ERP database, e.g. because the customer has deleted himself in the shop and registered again and this process has not arrived in the ERP.

Disadvantages

The "error tolerance" is also a disadvantage at the same time, because it disguises discrepancies between the ERP database and the shop database.

For example, by creating a new customer in the ERP, a clerk can overwrite an existing customer record in the shop without being notified in any way.

Something similar can happen if the user index in the ERP is no longer correct; this can also unknowingly overwrite data for a shop customer for whom the changes were not intended.

Furthermore, "Multiple accounts (eMail)" can of course not be used in combination with "Email addressing".

Prerequisite for use
To use this feature, the shop must be specially configured. Please contact WEBSALE AG if email addressing is required.

Import files

Limitation of field lengths

The default and at the same time maximum allowed length of all customer data fields is 256 characters.

In the section "AddressMaxInputLen" of the shop configuration "shop.config" the maximum length of the individual fields for which the customer can enter content in the shop can be reduced if required. You should make use of this option if the respective field length in your system is smaller than 256 characters.

Limitation of file size

  • Import via SFTP: 4 GB per file

  • Import via WSPManager: 1 GB per file

Overview of import files

File name

Comment

File name

Comment

custupdate.csv

Records to be updated and inserted/ access data and customer options

custdelete.csv

Records to be deleted

billupdate.csv

Billing addresses to be updated and inserted.

billcomplete.csv

Billing addresses to be updated and inserted. In contrast to the file "billupdate.csv", this file must contain all billing addresses of a customer. Billing addresses that are not included will be deleted.
This file is intended as an alternative to billupdate.csv, a simultaneous import will generally not be useful.

billdelete.csv

Billing addresses to be deleted. This file is intended for deleting individual addresses of specific customers. When deleting the complete customer using the file "custdelete.csv", all billing addresses will be automatically deleted as well.

delivupdate.csv

Delivery addresses to be updated and inserted

delivcomplete.csv

Shipping addresses to be updated and inserted. (analogous to billcomplete.csv).

delivdelete.csv

Delivery addresses to be deleted (analogous to billdelete.csv).

bankupdate.csv

Bank details to be updated and inserted

bankcomplete.csv

Bank details to update and insert (analogous to billcomplete.csv).

bankdelete.csv

Bank details to be deleted (analogous to billdelete.csv).

Import order

The files are imported in the following order:

  1. *delete files

  2. custupdate.csv

  3. All other *update files

  4. *complete files

So, within an import, records of a customer could be deleted first and inserted again afterwards, if this makes sense from the point of view of the exporting system.

Because of the processing as last, a complete import of all records always has "the upper hand". If with an update file and in the associated complete file thus data records for the same customer are transferred, then the data of the complete file overwrite the previously imported data of the update file.

Structure and contents of the file “custupdate.csv”

This file can be used to create new records in the shop and set various options for customers. So that for a customer invoice addresses, delivery addresses etc. can be imported always also first a data record must be created with the help of the custupdate.csv.

If required fields are not supplied in the file (i.e. the column is missing completely), the values originally shop for these fields in the customer record are retained.

The file contains the following fields:

Field name

Field content

Required field yes/no

Field name

Field content

Required field yes/no

UserIndex

The table key in the shop database (see section Addressing the records)

yes when changing a record, forbidden when creating a new record (see Addressing records section)

CustomerID

The customer number

yes when a new record is created, otherwise: see Addressing of records

Password

The password with which the customer can log in to the shop.
Note that you can only set the password when creating new customers. Since the customer can change his password in the shop at any time, there would otherwise be a risk that you overwrite the password chosen by the customer.

no

EMail

The customer's mail address

yes

MainSubshop

If a subshop ID is entered here, the customer can only log in to this subshop (and any subshops specified in the Subshop field). If a customer tries to log in to a subshop for which he has no access authorization, he will be redirected to the subshop specified under "MainSubshop".

If this field is empty, the customer can log in to all subshops.

yes, if the "Subshop" field is used

Subshop

If a subshop is entered in the "MainSubshop" field, the "Subshop" field can be used to specify a comma-separated list of additional subshops that the customer can log into.

As an alternative to a list of subshops, the value "*" can also be entered here, in which case the customer can log in to all subshops.

no

CharsetImport

If the customer data cannot be delivered in the character set used in the shop, the character set can be converted with these two fields

no

CharsetShop

no

AddressSharingLastChangeDate

Consent to share addresses for advertising purposes: Date of the last change of state in the format DD.MM.YYYY

no

AddressSharingLastChangeIP

Consent to share addresses for advertising purposes: IP address at last change

no

AddressSharingLastChangeTime

Consent to share addresses for advertising purposes: Time of last change of state in SS:MM:SS format (hours/minutes/seconds)

no

AddressSharingState

Consent to share addresses for advertising purposes: state, possible values are:
0: Not set
1: Consent rejected by phone
2: Consent given by phone
3: Consent refused in the shop
4: Consent given in the shop

no

AgeResMail

A mail address where the "AgeResPasswd" can be sent to

no

AgeRestricted

The age of the customer. If this field is filled with a value greater than 0, the logged in customer will only be shown products whose "AgeRestricted" is less than or equal to the customer's age

no

AgeResPasswd

The password (for the guardian) that can be used to change the "AgeRestricted" field

no

BillieDuration

Time in days within which the customer has to pay the invoice (only for payment type Billie)

Valid values: 7 - 120 (overwrites the default value of 30 days from the shop configuration)

no

CreditCheckDate

Date on which an (automatic, renewed) credit check should be performed.
The field can be used if a positive credit check by the shop should not be valid indefinitely, but e.g. after one year should be checked again whether a customer may continue to pay by invoice.

Format: YYYY-MM-DD

Example: 2022-03-17

no

CreditPassState

0/empty: not checked

1: checked positive

2: negative checked

no

Currency

The currency in which the prices are displayed to the customer by default after login.

no

CustomerDiscountOnly

"X": The customer will only be given the customer discount specified in "Discount", no other discounts.
If no customer discount is assigned to the customer and this flag is set, the customer will not receive any discounts at all.

no

DelCostDiscRate

Discount in % that the customer will receive on the shipping cost.

no

DeliveryCostReduction

"X": Reduced delivery costs apply to the customer

no

DeliveryDays

Comma separated list of weekdays on which the customer can be delivered.

1=Monday
...
7=Sunday

no

DeliveryGroup

DeliveryGroup, allows to make article dependent delivery costs additionally customer dependent.

no

Discount

Discount in %, which the customer receives when purchasing discountable items

no

DiscountGroupID

Suffix for Discount.dat, allows customer dependent discount groups.

Example:

If DiscountGroupID="abc", then the file "discount_abc.dat" will be loaded from the shop.

If DiscountGroupID="", then the file "discount.dat" will be loaded from the shop.

The format of the "discount_*.dat" files is described in the "Products PRO (EN)" documentation.

no

DiscountList

Definition of the possible grouping of discountable products for the customer. If this field is used, the shop will ignore the general discount rate. This field can be used to supply discounts for products or categories that match the specified search mask.

Structure of the field:

<g>(Type):(discount rate)[:(search mask)][:(fromQuantity-toQuantity)]</g>...

Type can have the following values:
1: Product number with optional wildcard characters
2: Product index with optional wildcard characters
3: UserDiscountCategory (reserved for internal use)

"Wildcard characters" are:
?: Any character
*: Any number of arbitrary characters

Example:
<g>1:12.00:123?R*</g>
<g>2:12.00:10-123?R*</g>
<g>3:3.00:UserDiscountCategory</g>

Data with and without quantities can also be combined. In this case, the first rule that applies from the left is used.

Example:
In the "flyer" category, a 3% discount is granted up to 1000 units, 2% up to 10000 and 1% from 10000:
<g>3:3.00:flyer:-999</g><g>3:2.00:flyer:1000-9999</g><g>3:1.00:flyer:10000-</g>

no

FreeDelivery

"X": The customer does not pay shipping costs

no

FreePayCost

"X": The customer does not pay any payment method costs

no

FreightCostsValue

Amount of a freight cost surcharge/deduction, e.g. 23.50

no

FreightCostsType

Type of freight cost surcharge/deduction, possible values:

A+=Absolute markup
A-=Absolute markdown
P+=Percentage markup
P-=Percentage markdown

no

GroupLogin

"X": The login data is used by multiple users ("group login"). In this case, neither the login data nor the address data can be changed by the logged-in user in the shop.

no

InfoScoreState

0/empty: not checked
1: positively checked
2: negative checked

no

LastOrderDate

Date of the last order in the format YYYY-MM-DD

This field is intended for orders that were not placed in the online shop, e.g. by telephone. It can then be used to recognise new customers and to control the logic when retrieving address data changes.

no

MaxOrderForUserAccount

If this field contains a value > 0, this value will be used instead of the "MaxOrder-Value" entered for the payment types in shop.config.

no

OrderGenerator

"X": If a link to the "OrderGenerator" should be offered to the logged in customer.

no

PayCostDiscRate

Discount in % that the customer receives on the payment method costs

 

PaymentMethods

A comma-separated list of payment type codes of the payment methods available to the customer.

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

no

ProductDiscount

"X": The customer discount is displayed at the product
Any other value: The customer discount is displayed in the shopping cart

no

PriceGroup

A price group, if different prices have been specified for this price group during the article import, these will be displayed to the customer instead of the default prices.

Even if customer-dependent prices are assigned via the customer number, this field must contain a non-empty entry. This "dummy entry" does not have to correspond to any existing price group and only serves as a flag so that the online shop activates the "customer-dependent prices" function.

no

RegistrationCode

"Unlock code", the shop can be set up so that only customers who know an unlock code can register.

This activation code is stored by the shop with the customer data, a change of the value over the import is not meaningful therefore however a deletion of the code.

no

Releaser

"X": The customer can release the orders of other customers

no

ReleaseID

An ID for the release procedure

no

ReleaseRequired

"X": The customer's orders must be released before they are executed.

no

Reseller

"X": The customer can enter a "reseller markup" (commission), which will then be added to the total amount of the order

no

StartPage

A "start page" that is displayed after the customer logs in

no

SuperUserID

ID of a "Super-User" with special rights.

This user can e.g. log in as another user and order for this user.

Every customer with a filled SuperUserID is considered a "SuperUser", the ID entered here is returned in the order data. It is therefore recommended to use a different ID for each SuperUser, so that it is clear in the order data who has carried out the order.

no

SuperUserRestricted

"X": The "SuperUser" is only allowed to access the customer records where his SuperUserID is entered in the SuperUserIDList field.

no

SuperUserIDList

A comma-separated list of the SuperUserIDs of the SuperUsers that are allowed to access this customer record.

no

Surcharge

In addition to the global surcharge, it is possible to define an amount (SurchargeLimit) per customer, up to which a surcharge will be charged per order (SurchargeBase), if the surcharge falls below this amount. Furthermore, the amount of the surcharge can be defined individually for each customer.

no

SurchargeLimit

no

TeleMarketingLastChangeDate

Consent for telephone advertising: Date of last change of state in the format DD.MM.YYYY

no

TeleMarketingLastChangeIP

Consent for telephone advertising: IP address at the last change of state

no

TeleMarketingLastChangeTime

Consent for telephone advertising: time of last change of state in format SS:MM:SS

no

TeleMarketingState

Consent for phone advertising: state, possible values are:
0: Not set
1: Consent rejected by phone
2: Consent given by phone
3: Consent declined in shop
4: Consent given in the shop

no

UnitFactorGroupID

If customer-dependent denominations are to be used, the group ID must be entered here, which is then also used in the "UnitFactorGroups" field in the product data.

no

Warranty

Comma-separated list of the customer's authorization codes. An authorization code is an alphanumeric string whose content determines whether or not certain areas in the shop are displayed to the customer.

Example list: 1,2,abc

The customer belongs to the authorization groups "1", "2" and "abc".

Example brackets in a template:

{ST-Warranty(1,abc)} This area is only displayed to the customer if he belongs to group "1" or "abc". {/ST-Warranty(1,abc)} {!ST-Warranty(1,abc)} This area is displayed to the customer, if he belongs neither to group "1" nor "abc". {/!ST-Warranty(1,abc)}

no

WebsaleIni

Deprecated: The name of an alternative shop.config to use for the customer.

no

Structure and content of the file “custdelete.csv”

This file can be used to delete records from the shop. If a record is deleted using custdelete.csv, all of the customer's data is deleted, i.e. their billing addresses, shipping addresses, etc.

The file contains the following fields:

Field name

Field content

Required field yes/no

Field name

Field content

Required field yes/no

UserIndex

The table key in the shop database (see section "Addressing the records")

Yes, if the CustomerID field is missing or empty (see Addressing the records section)

CustomerID

The customer number

Yes, if the UserIndex field is missing, empty or 0 (see Addressing the records)

If the UserIndex field is missing, empty or 0 and a customer number is specified, then all records matching this customer number are deleted.

Structure and content of the file “billupdate.csv/billcomplete.csv”

These files contain the invoice addresses to be inserted or updated. The structure of the two files is identical. However, the contained data are handled differently during import:
records of a customer that are not contained in the billupdate.csv remain in the shop's customer database, while they are deleted during import of the identical data in a billcomplete.csv.

Example

The customer database of the shop contains two customers with the customer numbers "123" and "ABC". For customer "123" there are 5 billing addresses stored in the customer database. In the billupdate.csv/billcomplete.csv there are 3 billing addresses for the same customer. The customer "ABC" does not appear in the import files.

When importing the data as "billcomplete.csv", the 5 invoice addresses of customer "123" from the database would be replaced by the 3 invoice addresses from the import file.

When importing the data as "billupdate.csv", the 3 addresses from the import data would be added to the addresses already in the customer database or the existing addresses would be updated.

The data of the customer "ABC" remain unchanged in the customer database in both cases.

Please note that the shop supports only one billing address per customer so far.

The files contain the following fields:

Field name

Field content

Required field yes/no

Field name

Field content

Required field yes/no

UserIndex

The table key in the shop database (see section Addressing records)

yes when changing a record, prohibited when creating a new record

(see section Addressing of data records)

CustomerID

The customer number

yes when creating a new data record, otherwise: see Addressing of data records

TableIndex

The table key in the shop database

This field is currently optional, because the shop supports only one billing address per customer

ExternalID

The ID of the record for the customer.

ExternalID: yes when creating a new record. Optional when updating a billing address.

(see Addressing records

BCCEMail

Comma-separated list of mail addresses to which the order confirmations should be sent as a "blind carbon copy".

no

BusinessFax

Fax (business)

no

BusinessPhone

Phone (business)

no

CCEMail

Comma-separated list of mail addresses to which the order confirmations should be sent as "carbon copy".

no

City

City of residence

no

Company

Company

no

CompleteSalutation

Complete salutation, e.g. "Dear Mr. Miller". This field can be used if a welcome email is to be sent to new customers when importing the data. It has no meaning for the shop.

no

CostCenter

CostCenter

no

CountryISO

Three-digit ISO code of the country

no

DateOfBirth

Date of birth in the format DD.MM.YYYY

no

Department

Department

no

EMail2

Mail address for invoice

no

Fax

Fax

no

FirstName

FirstName

no

LastName

LastName

no

MobilePhone

Mobile Phone

no

Phone

Phone

no

PostOfficeBox

P.O. Box

no

PostOfficeBoxZip

Post office box zip code

no

Salutation

Salutation, e.g. "Mr.". This field is used by the shop only if the "SalutationCode" is not filled. It is recommended to import the "SalutationCode" field instead of "Salutation" and to enter the text of the salutation (e.g. "Mr.") in the "salutation.dat" configuration.

no

SalutationCode

Code of the salutation, e.g. "11". The codes and the associated settings are configured in the configuration "salutation.dat". Access is via the "Configuration" service in the online service area.

no

State

Country, e.g. "Bavaria

no

Street1

Street / House number

no

Street2

  1. Street / house number

no

Suffix1-50

Freely usable address data fields

no

TaxId

Sales ID

no

TaxIds

Sales IDs for chain transactions.
Format:
<g>{3ISO country}:{Check status}:{Sales-ID}</g>

Example:

<g>DEU:ok:DE123456789</g><g>BEL:unchecked:BE0999999999</g><g>AUT:failed:AT0999999999</g>

no

Title

Title, e.g. "Dr.".

no

TitleCode

Code of the title, e.g. "11" (the codes and the corresponding settings are configured in the "title.dat" file in the "configuration" directory of the SubShops)

no

UserDescr

A comment that is displayed in the shop during address selection

no

UserType

"Type" of the customer, must correspond to a value configured in shop.config

no

Zip

Zip code

no

Structure and content of the file “billdelete.csv”

this file can be used to delete individual invoice addresses from the shop. If all data of a customer should be deleted, it is sufficient to delete the data record with custdelete.csv, a deletion of the individual invoice addresses with billdelete.csv is not necessary in this case.

The file contains the following fields:

Field name

Field content

Required field yes/no

UserIndex

The table key in the shop database (see section "Addressing records")

Yes, if the CustomerID field is missing or empty

CustomerID

The customer number

Yes, if the UserIndex field is missing, empty or 0

TableIndex

The table key in the shop database

Yes, if the ExternalID field is missing or empty

ExternalID

The ID of the record for the customer.

Yes, if the TableIndex field is missing, empty or 0

Structure and content of the file “delivupdate.csv/delivcomplete.csv”

These files contain the delivery addresses to be inserted or updated. They are handled analogously to the files billupdate.csv or billcomplete.csv. Delivery addresses only need to be imported for a customer if they differ from the billing addresses.

The files contain the following fields:

Field name

Field content

Required field yes/no

Field name

Field content

Required field yes/no

UserIndex

The table key in the shop database (see section "Addressing records")

yes when changing a record, forbidden when creating a new record

(see section "Addressing the data records")

CustomerID

The customer number

yes when creating a new dataset, otherwise: see Addressing of datasets

TableIndex

The table key in the shop database

TableIndex: yes when changing a dataset, forbidden when creating a new dataset

(see addressing of the data records)

ExternalID

The ID of the record for the customer.

ExternalID: yes when creating a new record, otherwise optional

(see Addressing of data sets

City

City of residence

no

Company

Company

no

CostCenter

CostCenter

no

CountryISO

Three-digit ISO code of the country

no

Department

Department

no

EMail

Mail for delivery address

no

FirstName

FirstName

no

LastName

LastName

no

Phone

Phone

no

PostOfficeBox

P.O. Box

no

PostOfficeBoxZip

Post office box zip code

no

Salutation

Salutation, e.g. "Mr.". This field is used by the shop only if the "SalutationCode" is not filled. It is recommended to import the "SalutationCode" field instead of "Salutation" and to enter the text of the salutation (e.g. "Mr.") in the "salutation.dat" configuration.

no

SalutationCode

Code of the salutation, e.g. "11". The codes and the associated settings are configured in the configuration "salutation.dat". Access is via the "Configuration" service in the online service area.

no

State

Country, e.g. "Bavaria

no

Street1

Street / House number

no

Street2

  1. Street / house number

no

Suffix1-50

Freely usable address data fields

no

Title

Title, e.g. "Dr.".

no

TitleCode

Code of the title, e.g. "11" (the codes and the corresponding settings are configured in the "title.dat" file in the "configuration" directory of the SubShops)

no

UserDescr

A comment that is displayed in the shop during address selection

no

Zip

Postal code

no

Structure and content of the file “delivdelete.csv”

This file can be used to delete individual delivery addresses from the shop. It is handled in the same way as the billdelete.csv file.

The file contains the following fields:

Field name

Field content

Required field yes/no

Field name

Field content

Required field yes/no

UserIndex

The table key in the shop database (see section "Addressing records")

Yes, if the CustomerID field is missing or empty

CustomerID

The customer number

Yes, if the UserIndex field is missing, empty or 0

TableIndex

The table key in the shop database

Yes, if the ExternalID field is missing or empty

ExternalID

The ID of the record for the customer.

Yes, if the TableIndex field is missing, empty or 0

Structure and content of the file “bankupdate.csv/bankcomplete.csv”

These files contain the bank details data to be inserted or updated, they are treated analogously to the billupdate.csv or billcomplete.csv files.

The files contain the following fields:

Field name

Field content

Required field yes/no

Field name

Field content

Required field yes/no

UserIndex

The table key in the shop database (see section "Addressing records")

yes when changing a record, forbidden when creating a new record

(see section "Addressing the data records")

CustomerID

The customer number

yes when creating a new dataset, otherwise: see Addressing of datasets

TableIndex

The table key in the shop database

TableIndex: yes when changing a dataset, forbidden when creating a new dataset

(see addressing of the data records)

ExternalID

The ID of the record for the customer.

ExternalID: yes when creating a new record, otherwise optional

(see Addressing of records

AccountNumber

Account number

no

Bank

Name of the bank

no

BankCode

Bank code

no

BIC

Bank Identifier Code

no

CountryISO

Three-digit ISO code of the country

no

IBAN

International Bank Account Number

no

Owner

Owner of the account

no

SEPALastMandate

Last SEPA mandate number

no

SEPAMandateType

Sepa mandate type

0: not set
1: one-time mandate
2: recurring mandate

no

SEPADebitType

SEPA direct debit type

0: not set
1: basic direct debit
2: company direct debit

no

SEPAMandateDate

Date of mandate consent
Format: YYYYMMDD

no

UserDescr

A comment that is displayed in the shop when selecting the bank details

no

Structure and content of the file “bankdelete.csv”

This file can be used to delete individual bank details from the shop, it is handled in the same way as the “billdelete.csv” file.

The file contains the following fields:

Field name

Field content

Required field yes/no

Field name

Field content

Required field yes/no

UserIndex

The table key in the shop database (see section "Addressing records")

Yes, if the CustomerID field is missing or empty

CustomerID

The customer number

Yes, if the UserIndex field is missing, empty or 0

TableIndex

The table key in the shop database

Yes, if the ExternalID field is missing or empty

ExternalID

The ID of the record for the customer.

Yes, if the TableIndex field is missing, empty or 0

Character set conversion

If the address data cannot be supplied in the character set used by the shop, the character set can be converted during import. There are two ways to do this:

1. Using the fields "CharsetImport" and "CharsetShop".

These two fields must be specified in the custupdate.csv file for each imported data set and contain the character set of the data set in the import data and the character set to be used in the shop.

2. Configuration of the conversion in the file global.config

Here in the file "global.config" in the directory "configuration" is set in which character set the customer data are supplied. The file "global.config" is optional in the shop and must be created therefore possibly first.

The character set of the shop is read from the "shop.config". In order for the subshop (and thus the shop.config to be used) to be determined, the "MainSubhop" field must be filled for each record in this method.

Example for the configuration in global.config

<CustomerImportPro> ConvertCharset = yes # [yes|no], standard = no ImportCharset = UTF-8 # standard = UTF-8 UnknownCharacters = mapreplace # standard = ignore </CustomerImportPro> <+ImportCharsetConvertMap> Charset = ISO-8859-1 a = %c4%83 $delete = %c3%8d %56 = %c3%8e s = %c5%9f </+ImportCharsetConvertMap>

The only required parameter is "ConvertCharset", because only if this parameter has the value "yes" the charset will be converted at all. "ImportCharset" specifies the character set of the import file. If the parameter is missing or empty, the character set "UTF-8" will be used.
"UnknownCharacters" controls the behavior if the import file contains characters that are not available in the shop's character set. The default value is "ignore". Characters that cannot be converted are completely omitted. With "stdreplace" it is tried to replace unknown characters with one or more similar looking characters. The value "mapreplace" causes configurable replacements to be made before the actual conversion. If characters cannot be converted even after these replacements, they are omitted (as with "ignore").

Which characters are replaced by what is defined in the "<+ImportCharsetConvertMap>" sections.

In the global.config file there can be several of these sections. One for each required character set. The parameter "Charset" specifies the charset for which the section should be used, all other parameters represent replacement rules. To the left of the "=" is a character or character string from the import file, to the right of it is the desired replacement. Since the character set of the import file generally differs from the character set of global.config, the characters can be specified URL-encoded. With this encoding, a character is essentially replaced by its hexadecimal code and the code is preceded by a "%".

The fields "CustomerID", "Mail", "Subshop" and "MainSubshop" are excluded from the character set conversion.

Welcome emails for new customers

It is possible to send a "welcome mail" to each new customer whose data has been imported via the "custupdate.csv" file. A customer in the "custupdate.csv" is considered a new customer if one of the following two conditions is met:

  • The customer was not in the database before the import

  • The customer did not have a customer number before and a new one is assigned to him via the "custupdate.csv"

The text of the mail that is sent to the customer is formed from a template that is configured in shop.config:

<NewCustomerMail> ... Template = mail_newcustomer.htm </NewCustomerMail>

The template file is located in the directory ".../used/templates/<subshop>/"

So the template used for sending the welcome mail depends on the content of the "MainSubshop" field in the import file. If this field is missing or empty, no welcome mail can be sent.

The sender name, sender address and subject of the welcome mail are also set in shop.config:

If sending a welcome mail is not desired, this can be prevented by setting the "Allow" parameter to "no":

Alternatively or additionally, the template can be deleted or renamed.

The following placeholders are available in the mail template:

Placeholder

Replacement

Placeholder

Replacement

~A-CompleteSalutation~

The complete salutation as it was imported in the CompleteSalutation field

~A-Salutation~

The salutation as it was imported in the "Salutation" field

~A-FirstName~

The first name of the customer

~A-LastName~

The last name of the customer

~A-UID~

The login ID of the customer

~A-Number~

The customer number

~A-E-mail~

The email address

All address data (A-CompleteSalutation, A-Salutation, A-FirstName, A-LastName) will be read from the customer's first billing address.

Forced change password

This feature can be used to force a customer created via import to change his password after the first login. To do this, set the "NewUserPWChangeRequired" parameter in the "UserData" section of shop.config to "yes"

Handling of deleted accesses

Customers have the option to delete or deactivate their accesses to the shop. These "deleted" records will initially remain in the database and will only be flagged as deleted there.

If you try to import data for deleted records, the changes will be ignored. However, deleting the data via custdelete.csv is possible or even necessary to actually remove the data from the database.

The reason for this behavior is that ERP systems normally cannot delete customer data. If the customer data were to be completely deleted from the shop database, there would be a risk that the ERP system would import the data deleted in the shop back into the shop. The customer who deleted his account in the shop would then rightly wonder why his deleted account is suddenly active again.

Sample files

Part of this documentation are the following example files, which you can download on the subordinate page:

Directory

Comment

Directory

Comment

Complete

With these import files the customers "Müller" and "Maier" are newly created in the customer database.

Update

In this example, the customer "Schulze" is assigned a customer number. This customer has registered via the shop and received the UserIndex "123" from the shop. Furthermore, "ExternalIDs" are assigned for the addresses and the bank details, with which these can be addressed in the import files in the future.

Note that this is the only example where the TableIndex field is used.

Since the only purpose of these files is to assign a customer number and "ExternalIDs" to the record created by the shop, the remaining fields are empty.

Delta

In this example, for the customer "Miller", a shipping address is added, one of the bank details is deleted and the billing address is changed.

It is assumed that the customer was given UserIndex 123 when it was created.

Delete

This file deletes the customer Müller with all addresses and bank details from the database.

Orderquantity

Example of creating and deleting customer-dependent, minimum and maximum order quantities

Error codes

Code

Comment

Code

Comment

EC001

Neither the header field "UserIndex" nor the header field "CustomerID" exists in the import file, the import of the customer data was aborted.

EC002

In the import file neither the header field "TableIndex" nor the header field "ExternalID" is present, the import of the customer data was aborted.

EC003

For the record both CustomerID and UserIndex are empty, therefore it was ignored.

EC004

For the record both ExternalID and TableIndex are empty, it was therefore ignored.

EC005

Neither the CustomerID nor the UserIndex of the record exists in the database.

EC006

A TableIndex was specified in the import file that does not exist for the associated customer record, but is already used for another customer.

Since the TableIndex must be unique table-wide, the record could not be created. It is recommended to leave the TableIndex empty when creating new records and leave the generation to the database.

EC007

The record does not contain a mail address. Because V8-Shops need the mail address for registration, the record is ignored.

EC008

The record to import does not yet exist in the database, but the specified mail address is already used in another record.

Multiple records with the same mail address are only allowed if multiple accounts are set up in at least one subshop.

EC009

Using the UserIndex, an attempt was made to assign a customer number to a customer that already exists in the database and is already being used for another customer.

EC010

CharsetImport without CharsetShop is ignored.

If the character set is to be converted during import, then both the source character set (CharsetImport) and the target character set (CharsetShop) must be specified.

EC011

CharsetShop without CharsetImport is ignored.
If the character set is to be converted during import, then both the source character set (CharsetImport) and the target character set (CharsetShop) must be specified.

EC012

… strings could not be converted to the target character set without errors.

EC013

Invalid character set (... or ...).

One of the specified character sets is not supported by the import.

EC014

There are both encrypted data and data transferred with SFTP.

This message is only relevant if the customer data is imported via the Article Import Pro interface. The import data can be played either encrypted into the shop directory or unencrypted via SFTP into a specially designated directory.

EC015

The 'UserIndex' field is not present in the import data, although it is a required field in the configured import options.

EC016

UserIndex ... does not exist.
A UserIndex specified in the import file must already exist in the shop database.

EC017

TableIndex ... replaced by ... replaced. An invoice address with one TableIndex was imported, although an invoice address with a different TableIndex already existed for the customer. Instead of the TableIndex from the import file, the existing TableIndex was used.

EC018

More than one billing address exists.
Currently a maximum of one billing address per customer is supported, in the import file there are more.

EC019

In the file ... is missing the required field ...

EC020

The required field ... is empty (file: ... line: ...)

EC021

Invalid data type ... in field ... (file: ..., line: ...)

EC022

UserIndex is empty (file: ..., line: ...)

EC023

Invalid value for 'TableIndex': ... (file: ..., line: ...)

TableIndex is not a number or exceeds the maximum value (2147483647)

EC024

Invalid indices (<1 or >...) for product customer group in groupproductupdate.csv

When importing the product customer groups, only the sum of the lines with invalid indices is logged, not each individual invalid line. Index" means the field "GroupIdx" in the import file. The value is invalid either because it exceeds the number of enabled groups, because it is not a number or because the value is <1.

EC025

No customer database available.

This is an internal error that occurs if no customer database was created when WEBSALE created the shop.

EC026

'CustomerID' not available in the database (file: ..., line: ...)

No UserIndex is specified in the specified import file and no suitable customer data record exists in the database for the customer number either (only occurs with import files for prime packages).

EC027

Maximum number of prime packages (10) for the customer ... exceeded

EC028

Invalid format for ValidFrom or ValidUntil (file: ..., line: ...)

EC029

Multiple accounts and mail addressing cannot be used at the same time.

Multiple accounts are characterised by the fact that several customer records have the same email address. Therefore, the email cannot be used to address data records, because several data records might match.)

EC030

'UserIndex' not available in the database (file: ..., line: ~linenum~)

In an import file, a UserIndex > 0 is specified, but there is no matching customer record in the database. The record is therefore ignored. (Only occurs with import files for prime packages.)

Error mails during import via WSPManager

When transferring customer import files with the WSPManager, the list of occurred errors and warnings is shortened if it exceeds a certain length.

The complete list of occurred errors and warnings can be sent to you by mail, configure the following sections in the shop.config of the first subshop:

Other import files

Overview of "other import files”

Import data

File name

Import data

File name

Product customer groups (customer/group assignment)

groupproductupdate.csv
groupproductdelete.csv

Customer accounts, bonus points, allowances

accountupdate.csv

Offer data

offerheadupd.dat/offerheadupd.csv
offerprodupd.dat/ offerprodupd.csv
offerdel.dat/ offerdel.csv

Customer dependent orderquantities

orderquantityupdate.csv
orderquantitydelete.csv

Prime packages

primeupdate.csv
primedelete.csv

Import of product customer groups

Product customer groups can be used to show or hide categories in the shop, depending on which customer has logged into the shop.

The assignment of customers to product customer groups is done via two additional files in the "customerimport" directory: "groupproductupdate.csv" and "groupproductdelete.csv".

With the file "groupproductupdate.csv" customers can be assigned to product customer groups, with the file "groupproductdelete.csv" these assignments can be deleted again.

Structure of the file "groupproductupdate.csv"

Field name

Field content

Field name

Field content

CustomerID

Customer number as assigned to the customer in the file "custupdate.csv

GroupIdx

The index of the group, e.g. "1".

The lowest possible value for the field is "1", the maximum value depends on how many product customer groups are enabled for the shop. if the value exceeds the number of unlocked product customer groups, an error is logged and the assignment is ignored.

For example, to assign the product customer groups 1 and 2 to the customer with the customer number "1234" you could use the following file:

CustomerID<TAB>GroupIdx

1234<TAB>1

1234<TAB>2

("<TAB>" in this example stands for the tab character/ASCII code 9. If other product customer groups were already assigned to the customer before the import, these will be retained)

Structure of the file "groupproductdelete.csv"

Field name

Field content

Field name

Field content

CustomerID

Customer number as assigned to the customer in the file "custupdate.csv" or "*" if a product customer group is to be deleted for all customers.

GroupIdx

The index of the group (e.g. "1") or "*" if all groups for a customer are to be deleted.

(See also the field description in "groupproductupdate.csv")

The following file would remove the customer with customer number "1234" from the product customer group "Pianos", as well as delete the complete product customer group "Monitors":

CustomerID<TAB>GroupID

1234<TAB>1

*<TAB>2

Import of data for customer accounts, bonus points, grants

Customer accounts, bonus points and allowances are intended for the realization of bonus systems and credits that can be redeemed in the shop.

Bonus points:
For example, a customer is credited with a number of bonus points for purchasing a product. If he has collected enough bonus points, he can redeem them in the shop.

If you do not offer bonus points, then you can omit the "BonusPoints" column in the import file.

Customer account:
Here you can credit customers with any amount of credits. When purchasing, the customer then selects the payment method "customer account" and pays with his credit. WEBSALE automatically reduces the credit after a purchase.

If you do not offer a customer account, then you can omit the "Credit" column in the import file.

Allowance:
Here you can credit customers with any allowance. The granted allowance will be deducted from the total amount in the shopping cart. When the order is placed, the granted allowance will be automatically deducted from the allowance account of the shop. Any remaining amount will be taken into account for subsequent orders until the allowance has been used up.

The import of the customer account data is done via an additional file named "accountupdate.csv" in the "customerimport" directory.

Structure of the file "accountupdate.csv"

Field name

Field content

Field name

Field content

UserIndex

UserIndex

BonusPoints

Number of bonus points of the customer (integer)

Credit

Credit of the customer account

Subsidy

Subsidy

Remarks:

  • The UserIndex is used to address the records, so this indirectly means that customer account data can only be imported for customers who already exist in the database, because otherwise the UserIndex is not known.

  • For bonus points, credits and allowances, differences can be specified in addition to absolute values. For this purpose, the value is preceded by a "+" or a "-".
    For example, if a customer has 100 bonus points on his account and you import the value "10" in the "BonusPoints" column, the value in the database will be set to 10. If you specify the value "+10" instead, the value will be increased to 110; if you specify "-10", the value will be decreased to 90.
    If possible, differences should be specified during the import, because in this way it can never happen that the import undoes changes that were made by the online shop. Ex: You want to reduce the number of bonus points of a customer from 150 to 100 because he redeemed 50 points via a telephone order. The same customer was in the shop shortly before you started the import and sent an order that credited him with an additional 77 points. If you now import "100", you will delete the credit of 77 points. If you import "-50", the number of bonus points will be set to the correct value (177).

  • An explicit deletion of entries from the customer account table is not possible, entries are deleted when (by transferring the file "custdelete.csv") the general customer data are deleted. Of course, you can set the values to "0".

  • During an import, several files with customer accounts, bonus points and allowances can be imported. In this case the names must be provided with a "suffix", the name of an import file could then be e.g. "accountupdate_1.csv".
    The suffix starts with an underscore followed by one or more digits.
    Import files are sorted alphanumerically before import, i.e. "accountupdate_10.csv" is imported before "accountupdate_2.csv".

Quotation data

This function allows you to transfer a quotation that you have made to a specific customer to the online shop, the customer can then order the corresponding products online.

For the import of offer data you have to create two files, the file "offerheadupd.dat" and the file "offerprodupd.dat". The first file contains data related to the whole offer, e.g. shipping costs. The second file contains the individual products of the offer.

You can delete offers with the file "offerdel.dat".

All three files must be stored in the "data-exchange" directory. Alternatively, the files can be named "offerheadupd.csv", "offerprodupd.csv" and "offerdel.csv", in which case they must be stored in the customer-import files ("customerimport") directory.

When importing via the SFTP-SOAP interface the *.csv files must be used, when transferring with the WSPManager the *.dat or the *.csv files can be used.

Structure of the file “offerheadupd.dat/offerheadupd.csv”

Field name

Field content

Restriction

Field name

Field content

Restriction

Subshop

The ID of the subshop in which the offer should be displayed
(required field)

max. 128 characters

CustomerID

The customer number
(required field)

max. 255 characters

OfferID

A unique ID for the offer
(required field)

max. 255 characters

ExpireDate

Date until which the offer is valid in the format DD.MM.YYYY
(required field)

 

OfferDate

Date when the offer was submitted in the format DD.MM.YYYY
(required field)

 

PaymentCode

Code of the payment method
(optional)

 

PaymentCost

Cost of the payment method (e.g. cash on delivery fee)
(optional)

 

DeliveryName

Name of the delivery company (e.g. "Post within Germany,")
(optional)

 

Deliverycost

Delivery cost
(optional)

 

Description

Description
(optional)

max. 4000 characters

Structure of the file “offerprodupd.dat/offerprodupd.csv”

Field name

Field content

Restriction

Field name

Field content

Restriction

CustomerID

The customer number
(required field)

max. 255 characters

OfferID

The ID of the offer
(required field)

max. 255 characters

Name

Name of the product
(required field)

max. 128 characters

Insert

Advertising code
(optional)

max. 16 characters

Number

Product number
(optional)

max. 64 characters

Quantity

Quantity
(required field)

 

Price

Price
(required field)

max. 9 characters

VAT

Value added tax index
(optional)

 

DiscountRate

Discount in percent
(optional)

 

Discount

Discount (absolute amount)
(optional)

 

Variations

Variation of the product in the format <n-1>name1</n-1><v-1>value1</v-1><n-2>name2</n-2><v-2>value2</v-2>...

Ex: <n-1>color</n-1><v-1>red</v-1>
(optional)

 

TextinputFields

Text input fields of the product in the format <n-1>Name1</n-1><v-1>Value1</v-1><n-2>Name2</n-2><v-2>Value2</v-2>...

Ex: <n-1>imprint</n-1><v-1>testimprint</v-1>
(optional)

 

Upload

"X": The item offered is an "upload item"
(optional)

 

Image

The filename of a full-size image that can be displayed with the listing.

The associated file must be stored in the shop in the "...\products\media\images\normal" directory.
(optional)

max. 128 characters

Thumbnail

The filename of a small image that can be displayed along with the listing.

The corresponding file must be stored in the shop in the directory "...\products\media\images\small".
(optional)

max. 128 characters

ProdOrder

An integer, positive value that determines the order in which the products in the offer are displayed. A product with a smaller "ProdOrder" value will be displayed before a product with a larger "ProdOrder" value.

If this field is missing, the products are displayed in the order they are in the import file.
(optional)

8 characters

Structure of the file “offerdel.dat/offerdel.csv”

Field name

Field content

Restriction

Field name

Field content

Restriction

CustomerID

The customer number (required field)

max. 255 characters

OfferID

The ID of the offer (required field)

max. 255 characters

Import of customer dependent order quantities

For each product and customer a maximum and/or a minimum order quantity can be imported.

Order quantities are created and modified using the "orderquantityupdate.csv" import file, and deleted using the "orderquantitydelete.csv" file. Both files must not exceed a maximum size of 1 GB and both must be created (like the other customer import files) in the "customerimport" directory.

The file "orderquantitydelete.csv" is read in before the file "orderquantityupdate.csv", so that it is possible to delete entries and create new ones during an import.

Structure and content of the file “orderquantityupdate.csv”

The file is used to create and modify entries and contains the following fields:

Field name

Field content

Restrictions/
allowed values

Required field yes/no

Field name

Field content

Restrictions/
allowed values

Required field yes/no

CustomerID

The customer number

max. 255 characters

yes

ProdIndex

The product index

max. 64 characters

yes

Subshop

The subshop of the product

max. 128 characters

yes

MaxOrderQuantity

The maximum order quantity

Floating point number
from 0.00 to 1000000000.00, "$NoLimit$"
or "-"

no

MinOrderQuantity

The minimum order quantity

no

Remarks:

  • The "-" value in the "MaxOrderQuantity" and "MinOrderQuantity" fields has the effect of not changing the value set in the shop. Leaving the field completely empty has the same effect.

  • The "$NoLimit$" value in the "MaxOrderQuantity" or "MinOrderQuantity" fields causes a limit set for the product/customer to be removed. I.e. the customer can then order as much or as little of the product as he wants.

  • If a value for MinOrderQuantity or MaxOrderQuantity has never been explicitly set for a product/customer, then the value corresponds to "$NoLimit$".
    "$NoLimit$" is therefore the value with which the "MaxOrderQuantity" and "MinOrderQuantity" fields are initialized.

  • If no maximum/minimum order quantity is to be set for any product/customer, the MaxOrderQuantity/MinOrderQuantity column can be omitted completely. The effect is the same as if the column was filled with the value "-".

  • When deleting products or customers, the associated order quantities are not automatically deleted. An automatism is problematic, if products or customers are deleted and afterwards created again, because afterwards also the order quantities would have to be imported again.

  • There is no check whether a customer or a product in the import file actually exists in the shop. This has the advantage that order quantities can be imported before products or customers.

  • For products with dependent variations, it is not sufficient to specify an order quantity for the master item. Instead, the order quantity must be specified for each individual dependent variation.

  • When a customer orders in the shop, the value of MaxOrderQuantity is decreased by the ordered quantity.

Structure and content of the file “orderquantitydelete.csv”

The file is used to delete entries and contains the following fields:

Field name

Field content

Restrictions/
allowed values

Required field
yes/no

Field name

Field content

Restrictions/
allowed values

Required field
yes/no

CustomerID

The customer number

max. 255 characters

yes

ProdIndex

The product index

max. 64 characters

yes

Subshop

The subshop of the product

max. 128 characters

yes

Remarks:

The special value "*" can be specified for each column. This causes that the value in this column is not considered when deleting. For example, if the "ProdIndex" column contains the value "123", the "Subshop" column contains the value "German" and the CustomerID column contains the value "*", the order quantities of product "123" would be deleted for all customers

Import of prime packages

The prime packages assigned to a customer are imported via the primeupdate.csv and primedelete.csv files.

Structure of the file “primeupdate.csv”

The primeupdate.csv file is used to create and update the prime packages assigned to a customer. A maximum of 10 different prime packages can be assigned to each customer.

If a prime package is imported for a customer that is already assigned to him, the data of the existing prime package will be updated. If the prime package is not yet assigned to him, it will be added.

Prime packages that are assigned to the customer but are not imported will remain unchanged.

Each line of the import file corresponds to one prime package, i.e. if 10 prime packages are to be assigned to a customer, then the file must contain 10 lines for this customer.

The primeupdate.csv file contains the following fields:

Field name

Field content

Restrictions/
allowed values

Required field yes/no

Field name

Field content

Restrictions/
allowed values

Required field yes/no

CustomerID

The customer number

max. 255 characters

yes

UserIndex

If a UserIndex >0 is specified in the file, this is used instead of the customer number for addressing.

If no customer exists with this UserIndex, the data record is ignored.

Integer value <2147483647

no

ProdIndex

The product index of the set upper article containing the data of the prime package

max. 64 characters

yes

ValidFrom

The start of the validity in the format YYYYMMDD

max. 8 characters

yes

ValidUntil

The end of the validity in the format YYYYMMDD

max. 8 characters

yes

Cancel

"yes": cancellation desired
"no"/empty: cancellation not desired
"-": Do not overwrite value in customer data

max. 3 characters

no

OrderInfo

Any data to be returned in the order for the package.
If a customer buys a Prime package in the shop, then the content of the OrderInfo field of the product is written in here, which contains the data of the package.

"-": Do not overwrite value in customer data

max. 256 characters

no

Structure of the file “primedelete.csv”

The primedelete.csv file is used to delete prime packages assigned to a customer. It contains the following fields:

Field name

Field content

Restrictions/
allowed values

Required field yes/no

Field name

Field content

Restrictions/
allowed values

Required field yes/no

CustomerID

The customer number

max. 255 characters

yes

UserIndex

See primeupdate.csv above

Integer value <2147483647

no

ProdIndex

The product index of the set top article containing the prime package data, or the value "*" if all prime packages of a shop are to be deleted.

max. 64 characters

yes

Sample files

Part of this documentation are the following sample files, which you can find on the subordinate page for download:

Directory

Comment

Directory

Comment

Offer

Example of importing quotation data

Customer account

Example of importing customer account/bonus points/allowances

Pcustomergrp

Example of importing product customer groups