Customer Import

Short description

This interface describes which customer information is sent from the ERP system to Vendisto.

Customer information includes:

  • Shop Specific Debit Number

  • Billing address details

  • Name1

  • Name2 (e.g. Attn.)

  • Address

  • Postal code

  • City

  • Country

  • Standard shipping address information

  • Name1

  • Name2 (e.g. Attn.)

  • Address

  • Postal code

  • Town

  • Country

  • Additional information (e.g. port number, exit number, etc.)

  • Delivery instruction (e.g. "Leave behind in a box...")

  • Name contact person

  • E-mail address contact person

  • Payment method (on account, cash, etc.)

  • Payment condition

  • DeliverySchedule

  • DivisionCode

  • ApplyEqualizationTax

How to submit

Update Frequency: Batch at least 1x per day

Incremental or Full Set: Incremental

File Type: Zipped XML

Bestandsbenaming: [SHOPNAME]_customers_[INDEXNUMBER].xml Transport: over FTPS, FTPS Vendisto server is hosted by INTEGRACE, file is put on FTPS server by ERP party.

Location within FTP root: \Vendisto\Integration\

Customer XML Structure

This XML structure can be used for batch import of Customer data. All optional elements can be omitted from the import. Omitted elements that represent customer information will not update existing information. E.G. if <FirstName> is not present in the XML but is in the database, the field will not be updated. If <FirstName /> is present as an empty XML element, the FirstName in the database will be made empty. If <CustomerAddresses> is not present, the CustomerAddresses will not be updated. If <CustomerAddresses /> is present as empty XML element, all existing customer’s addresses will be removed from the database.

The ImportSettings element can be used to set the default behavior of import.

Changes from Customer XML 2.0 to 2.1

  • The ImportSettings node is now required as well as the 'Importer' setting.

  • The PartialUserImport setting is no longer available.

  • StreetAddressType is a new import setting with values: Combined and Separated

  • StreetAddres1 and StreetAddress2 are renamed to AddressLine1 and AddressLine2

  • AddressLine1 contains Street and housenumber when StreetAddressType is set to Combined

  • The new fields Street, HouseNumber and HouseNumberAddition are to be used when StreetAddressType is set to Separated

  • AddressLine2: May contain an additional address line

  • UserType and UserRights are new elements on the User level

  • ExternalId can be filled with the address id of the ERP system

Changes from Customer XML 2.1 to 2.2

  • The PriceGroup element was removed from the XML definition

  • A new PriceList element was added to the definition

  • An optional Currency element was added. This element can be used by the shop to predefine the users currency in the shop.

  • An optional Incoterm element was added. The incoterm is used to show to the user in the account section of the user portal.

  • An optional ShippingCostType element was added. The ShippingCostType is used for the shipment API. With this information the api can calculate the correct shipment costs.

  • An optional InvoiceTo element was added. If this field is filled, the shop will show the invoice addresses of the invoice debtor in the user portal and in the checkout process.

  • An optional DivisionCode element was added. We are able to configure the WebService to pass this field along with requests to a Shoxl rest implementation.

  • An optional attribute "ignoreElements" was added to the "Validation" element. It can be used to ignore certain XML elements in the validation process. Currently only supports "PostalCode" Usage:

    <?xml version="1.0" encoding="utf-8"?>
    <ImportSettings>
        <Validation ignoreElements="PostalCode,...">...</Validation>
        ...
    </ImportSettings>
  • An optional ApplyEqualizationTax element was added. If this field contains the value “true”, it means that this customer is eligible for an equalization tax. The shop can use this information to show a detailed breakdown of how a price is made up.

  • An optional CreateUnknownAuthorizationProfiles element was added to the import settings. If this field is true, non-existing authorization profiles are automatically created in Vendisto. This is useful when exporting pricelists as authorization profiles.

  • An optional PaymentCondition element was added. This element contains a debtor's payment condition code and -description.

<?xml version="1.0" encoding="utf-8"?>
<Import>
    <ImportSettings>
        <Importer>CustomerData</Importer>
        <Version>2.2</Version>
        <PartialImport></PartialImport>
        <Validation></Validation>
        <CreateUnknownAuthorizationProfiles></CreateUnknownAuthorizationProfiles>
        <StreetAddressType></StreetAddressType>
    </ImportSettings>
    <Customers>
        <Customer>
            <DebtorNumber></DebtorNumber>
            <Company></Company>
            <CompanyVatNumber></CompanyVatNumber>
            <Gln></Gln>
            <Gender></Gender>
            <FirstName></FirstName>
            <MiddleName></MiddleName>
            <LastName></LastName>
            <Email></Email>
            <PhoneNumber></PhoneNumber>
            <MobilePhoneNumber></MobilePhoneNumber>
            <DefaultReference></DefaultReference>
            <DateOfBirth></DateOfBirth>
            <Iban></Iban>
            <BuyOnCredit></BuyOnCredit>
            <PriceList></PriceList>
            <State></State>
            <PreferredBranche></PreferredBranche>
            <Currency></Currency>
            <Incoterm></Incoterm>
            <ShippingCostType></ShippingCostType>
            <InvoiceTo></InvoiceTo>
            <DeliverySchedule></DeliverySchedule>
            <DivisionCode></DivisionCode>
            <EqualizationTax></EqualizationTax>
            <PaymentCondition>
                <Code></Code>
                <Description></Description>
            </PaymentCondition>
            <Authorization>
                <Profile></Profile>
                <Profile></Profile>
            </Authorization>
            <CustomerAddresses>
                <CustomerAddress>
                    <AddressType></AddressType>
                    <Company></Company>
                    <Gender></Gender>
                    <FirstName></FirstName>
                    <MiddleName></MiddleName>
                    <LastName></LastName>
                    <AddressLine1></AddressLine1>
                    <Street></Street>
                    <HouseNumber></HouseNumber>
                    <HouseNumberAddition></HouseNumberAddition>
                    <AddressLine2></AddressLine2>
                    <PostalCode></PostalCode>
                    <City></City>
                    <Country></Country>
                    <ExternalId></ExternalId>
                    <IsDefaultAddress></IsDefaultAddress>
                </CustomerAddress>
            </CustomerAddresses>
            <Users>
                <User>
                    <Username></Username>
                    <FirstName></FirstName>
                    <MiddleName></MiddleName>
                    <LastName></LastName>
                    <Email></Email>
                    <PreferredLanguage></PreferredLanguage>
                    <BuyOnCredit></BuyOnCredit>
                    <State></State>
                    <Authorization>
                        <Profile></Profile>
                        <Profile></Profile>
                    </Authorization>
                    <UserType></UserType>
                    <UserRights>
                        <Right></Right>
                        <Right></Right>
                    </UserRights>
                </User>
            </Users>
        </Customer>
    </Customers>
</Import >

Velden customer XML

Import element:

Name

Description

Type

Required/Optional

ImportSettings

Container element for importsettings

Element

Required

Customers

Container element for Customer data

Element

Required

ImportSettings element:

Name

Description

Type

Required/Optional

Importer

Name of the importer. Should be CustomerData.

Text,

default CustomerData

Required

Version

Version of the import xml. Value must be set to 2.2

Text

Required

PartialImport

Defines if import is full or partial import.

Boolean, default Y

Optional

Validation

Defines the validation type. Strict validation requires FirstName and LastName fields of Customer Address. Loose validation doesn’t.

Also contains attribute "ignoreElements" which holds comma seperated element names which are ignored during the validation process.

Validation, default Loose

Optional

CreateUnknownAuthorizationProfiles

If this field is true, non-existing authorization profiles are automatically created in Vendisto

default N

Optional

StreetAddressType

Setting to make the distinction between 'Combined' and 'Separated' address lines. ERP systems that store the housenumber in a separate field should set the type to 'Separated'. Those that don't to 'Combined'.

StreetAddressType,

default Separated

Optional

Customer element:

Name

Description

Type

Required/Optional

DebtorNumber

Debtor number

Text

Required if Vendisto setting ‘Customer identification type’ is set to ‘Debtor number’, else Optional.

Company

Name of the company

Text

Optional

CompanyVatNumber

Vat number

Text

Optional

Gln

Global location number

GLN

Optional

Gender

Gender of the customer contact person

Gender

Optional

FirstName

of the contact person

Text

Optional

MiddleName

of the contact person

Text

Optional

LastName

of the contact person

Text

Optional

Email

of the contact person

Text, must be a valid email address

Required

PhoneNumber

of the contact person

Text

Optional

MobilePhoneNumber

of the contact person

Text

Optional

DateOfBirth

of the contact person

Date

Optional

DefaultReference

Depricated

Text

Optional

Iban

For future use

Text

Optional

BuyOnCredit

Enables the BuyOnCredit payment method, if this is available in the shop

Boolean, default N

Optional

PriceList

Vendisto pricelist name

PriceList

Optional

State

State of the customer: Active or Blocked

CustomerState, default Active

Optional

PreferredBranche

A preferred location or branche where the order will be handled

Text

Optional

Currency

Must contain the ISO 4217 three-letter currency code

Char[3]

Optional

Incoterm

Trade term

Text

Optional

ShippingCostType

The shipment cost type

ENUM: ShippingCostApplied, ShippingCostFree, ShippingCostPostCalculation

Optional

InvoiceTo

Account Number of the Invoice debtor. If this field is filled, the shop will show the invoice addresses of the invoice debtor in the user portal and in the checkout process

Text

Optional

DeliverySchedule

The name of the DeliverySchedule that the customer needs to be set to

Text

Optional

DivisionCode

Indicates the division a customer belongs to

Text

Optional

EqualizationTax

Indicates a customer is eligible for equalization tax

Boolean, default N

Optional

Authorization

Container for list of Profiles

Authorization element

Optional

CustomerAddresses

List of addresses of the customer (Invoice or Delivery)

CustomerAddress elements

Optional

Users

List of users for the customer

User elements

Optional

PaymentCondition

A debtor's payment condition

CustomerPaymentConditionElement

Optional

Authorization element:

Name

Description

Type

Required/Optional

Profile

Code of authorization profile

Char[3]

Optional

CustomerAddress element:

Name

Description

Type

Required/Optional

AddressType

Defines the type of the address: Invoicing or Delivery

AddressType

Required

CompanyName

Name of the company

Text

Optional

Gender

Gender of the customer address contact person

Gender, default Undefined

Optional

FirstName

of the address contact person

Text

Required if Validation is Strict

MiddleName

of the address contact person

Text

Optional

LastName

of the address contact person

Text

Required if Validation is Strict

AddressLine1

of the address contact person

Text

Only imported if StreetAddressType is Combined and in that case Required

Street

of the address contact person

Text

Only imported if StreetAddressType is Separated and in that case Required

HouseNumber

of the address contact person

Text

Only imported if StreetAddressType is Separated and in that case Required

HouseNumberAddition

of the address contact person

Text

Only imported if StreetAddressType is Separated and in that case Optional

AddressLine2

of the address contact person

Text

Optional

PostalCode

of the address contact person

Text

Required

City

of the address contact person

Text

Required

Country

of the address contact person

Text

Required

ExternalId

Address ID of the external (ERP) system

Text

Optional

IsDefaultAddress

In case of multiple addresses of the given Type this property indicates the default

Boolean, default N

Optional

User element:

Name

Description

Type

Required/Optional

Username

User’s username

Text

Required

FirstName

User's firstname

Text

Optional

MiddleName

User's middlename

Text

Optional

LastName

User's lastname

Text

Optional

Email

User’s email address

Text, must be a valid email address

Optional

PreferredLanguage

Indicates preferred language on website

LCID

Optional

BuyOnCredit

Enables the BuyOnCredit payment method, if this is available in the shop

Boolean, overrides customer’s BuyOnCredit setting

Optional

State

State of the user: Inactive, Active or Blocked

UserState, default Active

Optional

Authorization

Container for list of Profiles, overrides customer authorization profiles

Authorization element

Optional

UserType

The type of the user. Can be used to indicate the superuser who is able to manage the Rights per user.

UserType, default User

Optional

UserRights

Container for a list of Rights

UserRights element

Optional

UserRights element:

Name

Description

Type

Required/Optional

Right

Specifies a right that the user has

Right

Required

CustomerPaymentConditionElement:

NameDescriptionTypeRequired

Code

Identifier of a Payment Condition

string

Description

Description of a Payment Condition

string

Types:

Type

Values

AddressType

Invoicing, Delivery

Boolean

Y, N

Date

yyyy-MM-dd

CustomerIdentification

DebtorNumber, Email

CustomerState

Active, Blocked

Gender

Undefined, Male, Female

GLN

Must be a valid GLN number

LCID

Windows decimal LCID

PriceList

Name of in Vendisto existing PriceList

Right

OrderHistory, InvoiceHistory, BackOrderOverview, RestrictedOrderList, FavoritesList, UserManagement

StreetAddressType

Combined, Separated

UserState

Inactive, Active, Blocked

UserType

User, SuperUser

Validation

Strict, Loose

Structuur Customer XML (Legacy)

De informatie in deze sectie beschrijft het legacy formaat voor de Customer XML import. Dit formaat wordt nog ondersteund maar zal worden uitgefaseerd. Nieuwe implementaties dienen hier geen gebruik meer van te maken.

<?xml version="1.0" encoding="utf-8"?>
<customers>
        <customer>
                <accountNumber></accountNumber>
                <defaultBillingAddress>
                        <name1></name1>
                        <name2></name2>
                        <address1></address1>
                        <address2></address2>
                        <postalCode></postalCode>
                        <city></city>
                        <country></country>
                </defaultBillingAddress>
                <defaultShipmentAddress>
                        <name1></name1>
                        <name2></name2>
                        <address1></address1>
                        <address2></address2>
                        <postalCode></postalCode>
                        <city></city>
                        <country></country>
                        <transportInstructionText></transportInstructionText>
                </defaultShipmentAddress>
                <projects>
                        <project>
                                <projectAccountNumber></projectAccountNumber>
                                <name></name>
                                <description></description>
                                <defaultShipmentAddress>
                                        <name1></name1>
                                        <name2></name2>
                                        <address1></address1>
                                        <address2></address2>
                                        <postalCode></postalCode>
                                        <city></city>
                                        <country></country>
                                        <transportInstructionText></transportInstructionText>
                                </defaultShipmentAddress>
                        </project>
                </projects>
                <ContactName></ContactName>
                <ContactEmailAddress></ContactEmailAddress>
                <CompanyVatNumber></CompanyVatNumber>
                <FirstName></FirstName>
                <MiddleName></MiddleName >
                <LastName></LastName >
                <GLN></GLN>
                <priceListNumber></priceListNumber>
                <paymentOnAccountAllowed></paymentOnAccountAllowed>
                <showPrices></showPrices>
                <showStock></showStock>
        </customer>
</customers>

Velden customer XML (Legacy)

Name

Description

Type

Required / Optional

accountNumber

The identifier of a customer.

Text

Required

defaultBillingAddress / name1

Name of the billing address (department).

Text

Required

defaultBillingAddress / name2

A second name row of the billing address (attn)

Text

Optional

defaultBillingAddress / address1

Street and house number of the billing address

Text

Required

defaultBillingAddress / address2

An extra address row for the billing address

Text

Optional

defaultBillingAddress / postalcode

The postal code of the billing address

Text

Required

defaultBillingAddress /city

The city of the billing address

Text

Required

defaultBillingAddress /country

The country of the billing address

Text

Required

defaultShippingAddress / name1

Name of the shipping address (department).

Text

Required

defaultShippingAddress / name2

A second name row of the shipping address (attn)

Text

Optional

defaultShippingAddress / address1

Street and house number of the shipping address

Text

Required

defaultShippingAddress / address2

An extra address row for the shipping address

Text

Optional

defaultShippingAddress / postalcode

The postal code of the shipping address

Text

Required

defaultShippingAddress /city

The city of the Shipping address

Text

Required

defaultShippingAddress /country

The country of the Shipping address

Text

Required

defaultShippingAddress

/transportInstructionText

Transport and delivery instruction for the shipping address

Text

Optional

project / projectAccountNumber

The identifier of a project

Text

Required

project / name

The name of the project

Text

Required

project / description

A description of the project

Text

Optional

project / defaultShippingAddress / name1

Name of the shipping address (department).

Text

Required

project / defaultShippingAddress / name2

A second name row of the shipping address (attn)

Text

Optional

project / defaultShippingAddress / address1

Street and house number of the shipping address

Text

Required

project / defaultShippingAddress / address2

An extra address row for the shipping address

Text

Optional

project / defaultShippingAddress / postalcode

The postal code of the shipping address

Text

Required

project / defaultShippingAddress /city

The city of the Shipping address

Text

Required

project / defaultShippingAddress

/country

The country of the Shipping address

Text

Required

project /defaultShippingAddress /transportInstructionText

Transport and delivery instruction for the shipping address

Text

Optional

ContactName

The name of the contact. Can be replaced by FirstName, MiddleName and LastName

Text

Optional

ContactEmailAddress

The contacts emailaddress

Text

Required

FirstName

First name of the contact person

Text

Optional

MiddleName

Middle name of the contact person

Text

Optional

LastName

Last name of the contact person

Text

Optional

CompanyVatNumber

Vat number

Text

Optional

GLN

Global location number

GLN

Optional

priceListNumber

The pricelist reference

Text

Required

paymentOnAccountAllowed

Is the customer allowed to pay on account? (yes

= true, no = false)

Boolean

Required

showPrices

Can the customer see price information? (yes = true, no = false)

Boolean

Required

showStock

Can the customer see stock information? (yes

= true, no = false)

Boolean

Required

Types:

Name

Values

Boolean

yes, no

GLN

Must be a valid GLN number