Customers Template

The Customers template for the import/export tools describes your customer accounts and contact information. This data is used to manage orders, subscribed messages, promotional emails, newsletters, and so on. If you are preparing your initial data import for a new Kibo eCommerce tenant, import customers first.

Merchants can also import/export customers with associated customer segments. An option at the top of the attribute selection dropdown will allow you to specify filtering on customer segment information. The export action exports all segments to a file when "customer segment" is selected. The import action updates existing segments and adds any new segments to the Customer Segment page within admin.

Access the Tools

With the Kibo eCommerce Import-Export Application installed and enabled, go to Main > Customers > Import/Export in Kibo eCommerce Admin.

Supported File Formats

• CSV (.csv): Each sheet is a separate CSV file. For both imports and exports, sheets are compressed into a ZIP file. When importing, the ZIP file can have any file name but each individual CSV file name must match the export file name and the sheet. You can remove CSV files for data you do not want to import.

These CSV files should not be opened in Excel, as that may cause errors with their formatting. Instead, use a different CSV editing program to make changes to the data.

You should only use the default Windows zipper to zip the files, as using different software may cause errors. You can upload multiple files at once as long as they all are zipped.

Template Key

For each sheet, we define each column and describe valid values for the column. Some values are not required for an import, but are required Kibo eCommerce data. For example, you do not have to specify a customer's FirstName every time you modify the customer account, but all customer accounts require a FirstName when they are created. If you have questions or concerns specific to your data, please contact your integration partner or Kibo Support.

Sheets

Accounts

Corresponding REST API Resource: commerce/customer/accounts

Required With: CustomerContacts

This sheet defines customer accounts within Kibo eCommerce. Customer accounts can be registered shopper accounts or guest accounts. Registered accounts are created through a registration event, typically completed by the customer. Guest accounts are created when a customer chooses not to register. Guest accounts still have account IDs and associated data necessary to fulfill orders.

Contacts

Corresponding REST API Resource: commerce/customer/accounts/contacts

Required With: CustomerAccounts

This sheet defines the contacts for customer accounts. Contacts include such information as telephone numbers, shipping and billing addresses, and so on. A single customer account can have multiple contacts associated with it.

PurchaseOrderAccounts

Corresponding REST API Resource: commerce/customer/accounts/purchaseOrder

This sheet defines purchase order accounts within Kibo eCommerce.

PurchaseOrderPaymentTerms

Corresponding REST API Resource: commerce/customer/accounts/purchaseOrder

This sheet allows you to assign payment terms within a site to specific customer accounts.

PurchaseOrderTransactions

Corresponding REST API Operation: GetCustomerPurchaseOrderTransactions

This sheet defines purchase order transactions for customer accounts.

StoreCredits

Corresponding REST API Resource: commerce/customer/credits

This sheet allows you to assign store credit to specific customer accounts.

StoreCreditTransactions

Corresponding REST API Resource: commerce/customer/credits/transactions

This sheet allows you to assign store credit transactions based on a store credit code.

Customer Segments

Corresponding REST API Resource: commerce/customer/segments

This sheet defines customer segments within Kibo eCommerce.

Best Practices

Use the Kibo eCommerce API to Export > 50,000 Records

For optimal performance, Kibo eCommerce recommends only using the import/export tool if you are working with fewer than 50,000 customer records. If you need to export or import more than 50,000 records, refer to the samples below for more information about using the Kibo eCommerce API to import your customer records.

Customer Import Code Samples

The following sample code demonstrates how to import customers using the Kibo eCommerce API. These samples were implemented using the Kibo eCommerce .NET SDK, but the general implementation is the same across all the Kibo eCommerce SDKs.

Required Behaviors

Any application that implements code to import or update customers must have the following behaviors enabled:

• Customer Create
• Customer Read
• Customer Update

Import Customers

The following code sample organizes various calls to import customers to Kibo eCommerce:

private System.Collections.Concurrent.ConcurrentDictionary ImportCustomers(IEnumerable accountAuthCollection)
{
    var accountResource = new Mozu.Api.Resources.Commerce.Customer.CustomerAccountResource(_apiContext);
    var contactResource = new Mozu.Api.Resources.Commerce.Customer.Accounts.CustomerContactResource(_apiContext);

    var accountExternalIds = new System.Collections.Concurrent.ConcurrentDictionary();

    Parallel.ForEach(accountAuthCollection, new System.Threading.Tasks.ParallelOptions() { MaxDegreeOfParallelism = 1 }, accountAuthInfo =>
    {
        var filter = string.Format("ExternalId eq '{0}'", accountAuthInfo.Account.ExternalId);

        var importedResultStatus = string.Empty;

        Mozu.Api.Contracts.Customer.CustomerAccount existingAcct = null;

        var existingAcctCollection = accountResource.GetAccountsAsync(filter: filter).Result;

        if (existingAcctCollection.Items.Count == 0)
        {
            try
            {
                existingAcct = accountResource.AddAccountAsync(accountAuthInfo.Account, "Id,ExternalId").Result;
                importedResultStatus = string.Format("Added-New-Account-Id:{0}", existingAcct.Id);

                var existingAcctAuthTicket = accountResource.AddLoginToExistingCustomerAsync(new Mozu.Api.Contracts.Customer.CustomerLoginInfo()
                {
                    EmailAddress = accountAuthInfo.Account.EmailAddress,
                    IsImport = accountAuthInfo.IsImport,
                    Password = accountAuthInfo.Password,
                    Username = accountAuthInfo.Account.UserName,
                }, existingAcct.Id).Result;

                foreach (var contact in accountAuthInfo.Account.Contacts)
                {
                    var existingContact = contactResource.AddAccountContactAsync(contact, existingAcct.Id, "Id").Result;
                }
            }
            catch (Exception ex)
            {
                importedResultStatus = "Error-Encountered";
            }

            accountExternalIds.TryAdd(existingAcct.ExternalId, importedResultStatus);
        }
    });

    return accountExternalIds;
}

Add a Customer Account

The following code sample is a unit test that demonstrates the uses of various customer import methods:

[TestMethod]
public void Add_Customer_Accounts_Test()
{
    var tblAccounts = GetAccountTestData();
    var tblContacts = GetContactTestData();
    var accountAndAuths = new List();

    foreach(System.Data.DataRow drAcct in tblAccounts.Rows)
    {
        var customerLoginInfo = MapCustomerLoginInfo(drAcct);
        var account = MapCustomerAccount(drAcct);

        System.Data.DataRow[] drContacts = tblContacts.Select(string.Format("Id = '{0}'", drAcct["Id"].ToString()));

        account.Contacts = new List();
        foreach(System.Data.DataRow drContact in drContacts)
        {
            var  contact = MapCustomerContact(drContact);
            account.Contacts.Add(contact);
        }

        accountAndAuths.Add(new Mozu.Api.Contracts.Customer.CustomerAccountAndAuthInfo()
        {
            Account = account,
            IsImport = Convert.ToBoolean(customerLoginInfo.IsImport),
            Password = customerLoginInfo.Password
        });
    }

    var importedAcctIds = ImportCustomers(accountAndAuths);
}

Add Account Login

The following code sample maps customer account login information to a customer object in Kibo eCommerce:

private Mozu.Api.Contracts.Customer.CustomerLoginInfo MapCustomerLoginInfo(System.Data.DataRow drAccount)
{
    var mappedAccountAndAuthInfo = new Mozu.Api.Contracts.Customer.CustomerLoginInfo()
    {
        IsImport = true,
        EmailAddress = drAccount["Email"].ToString(),
        Password = drAccount["Password"].ToString(),
        Username = drAccount["Username"].ToString(),
    };

    return mappedAccountAndAuthInfo;
}

Get Account Test Data

The following code sample retrieves test data for customer accounts that you can then map to a customer object in Kibo eCommerce:

private System.Data.DataTable GetAccountTestData()
{
    var tblAccount = new System.Data.DataTable();
    tblAccount.Columns.Add("Id");
    tblAccount.Columns.Add("AccountID");
    tblAccount.Columns.Add("UserName");
    tblAccount.Columns.Add("Email");
    tblAccount.Columns.Add("Password");
    tblAccount.Columns.Add("FirstName");
    tblAccount.Columns.Add("LastNameOrSurname");
    tblAccount.Columns.Add("CompanyOrOrganization");
    tblAccount.Columns.Add("TaxExempt");
    tblAccount.Columns.Add("TaxId");
    tblAccount.Columns.Add("AcceptsMarketing");
    tblAccount.Columns.Add("LocaleCode");
    tblAccount.Columns.Add("UserRole");
    tblAccount.Columns.Add("IsActive");
    tblAccount.Columns.Add("IsAnonymous");
    tblAccount.Columns.Add("Total Order Amount");
    tblAccount.Columns.Add("Total Orders");
    tblAccount.Columns.Add("Last Order Date");
    tblAccount.Columns.Add("Total Contacts");
    tblAccount.Columns.Add("LastModifiedDate");
    
    System.Data.DataRow newRow = tblAccount.NewRow();
    newRow["Id"] = "101"; //externalId
    newRow["UserName"] = "vip_shopper";
    newRow["Email"]  = "vip_shopper@mozu.com";
    newRow["Password"] = "IBuyOnline2015";
    newRow["FirstName"] = "Jon";
    newRow["LastNameOrSurname"] = "Smithe";
    newRow["CompanyOrOrganization"] = "Main Corp";
    newRow["TaxExempt"] = false;
    newRow["AcceptsMarketing"] = true;
    newRow["LocaleCode"] = "en-US";
    newRow["IsActive"] = true;
    newRow["IsAnonymous"] = false;
    tblAccount.Rows.Add(newRow);
    
    return tblAccount;
}

Map Account Data

The following code sample maps customer account data to a customer object:

private Mozu.Api.Contracts.Customer.CustomerAccount MapCustomerAccount(System.Data.DataRow drAccount)
{
    var mappedAccount = new Mozu.Api.Contracts.Customer.CustomerAccount()
    {
        ExternalId = drAccount["Id"].ToString(),
        EmailAddress = drAccount["Email"].ToString(),
        FirstName = drAccount["FirstName"].ToString(),
        LastName = drAccount["LastNameOrSurname"].ToString(),
        CompanyOrOrganization = drAccount["CompanyOrOrganization"].ToString(),
        TaxExempt = Convert.ToBoolean(drAccount["TaxExempt"]),
        TaxId = drAccount["TaxId"].ToString(),
        AcceptsMarketing = Convert.ToBoolean(drAccount["AcceptsMarketing"]),
        LocaleCode = drAccount["LocaleCode"].ToString(),
        IsActive = Convert.ToBoolean(drAccount["IsActive"]),
        IsAnonymous = Convert.ToBoolean(drAccount["IsAnonymous"]),
        UserName = drAccount["UserName"].ToString(),
    };

    return mappedAccount;
}

Get Contact Test Data

The following code sample retrieves test data for customer contacts that you can then map to a customer object in Kibo eCommerce:

private System.Data.DataTable GetContactTestData()
{
  var tblContact = new System.Data.DataTable();
  tblContact.Columns.Add("Id");
  tblContact.Columns.Add("Type");
  tblContact.Columns.Add("IsPrimary");
  tblContact.Columns.Add("CompanyOrOrganization");
  tblContact.Columns.Add("FirstName");
  tblContact.Columns.Add("MiddleNameorInitial");
  tblContact.Columns.Add("LastNameOrSurname");
  tblContact.Columns.Add("Email");
  tblContact.Columns.Add("FaxNumber");
  tblContact.Columns.Add("HomePhone");
  tblContact.Columns.Add("MobilePhone");
  tblContact.Columns.Add("WorkPhone");
  tblContact.Columns.Add("AddressType");
  tblContact.Columns.Add("Address1");
  tblContact.Columns.Add("Address2");
  tblContact.Columns.Add("CityOrTown");
  tblContact.Columns.Add("StateOrProvince");
  tblContact.Columns.Add("PostalOrZipCode");
  tblContact.Columns.Add("CountryCode");

  System.Data.DataRow newRow = tblContact.NewRow();
  newRow["Id"] = "101"; //externalId
  newRow["Type"] = "Billing";
  newRow["IsPrimary"] = true;
  newRow["CompanyOrOrganization"] = "Main Corp";
  newRow["FirstName"] = "Jon";
  newRow["LastNameOrSurname"] = "Smithe";
  newRow["Email"] = "vip_shopper@mozu.com";
  newRow["WorkPhone"] = "555-555-5555";
  newRow["AddressType"] = "Commercial";
  newRow["Address1"] = "100 Main Corp Way";
  newRow["Address2"] = "Building 9";
  newRow["CityOrTown"] = "New York";
  newRow["StateOrProvince"] = "NY";
  newRow["PostalOrZipCode"] = "10026";
  newRow["CountryCode"] = "US";
  tblContact.Rows.Add(newRow);
  return tblContact;
}

Map Contact Data

The following code sample maps customer contact data to a customer object:

private Mozu.Api.Contracts.Customer.CustomerContact MapCustomerContact(System.Data.DataRow drContact)
{
    var mappedContact = new Mozu.Api.Contracts.Customer.CustomerContact()
    {
        CompanyOrOrganization = drContact["CompanyOrOrganization"].ToString(),
        Email = drContact["Email"].ToString(),
        FaxNumber = drContact["FaxNumber"].ToString(),
        FirstName = drContact["FirstName"].ToString(),
        LastNameOrSurname = drContact["LastNameOrSurname"].ToString(),
        MiddleNameOrInitial = drContact["MiddleNameOrInitial"].ToString(),
        Types = new List() 
        { 
            new Mozu.Api.Contracts.Customer.ContactType()
            {
                Name = drContact["Type"].ToString(),
                IsPrimary = Convert.ToBoolean(drContact["IsPrimary"]),
            }
        },
        Address = new Mozu.Api.Contracts.Core.Address() 
        {
            Address1 = drContact["Address1"].ToString(),
            Address2 = drContact["Address2"].ToString(),
            AddressType = drContact["AddressType"].ToString(),
            CityOrTown = drContact["CityOrTown"].ToString(),
            StateOrProvince = drContact["StateOrProvince"].ToString(),
            PostalOrZipCode = drContact["PostalOrZipCode"].ToString(),
            CountryCode = drContact["CountryCode"].ToString()
        },
        PhoneNumbers = new Mozu.Api.Contracts.Core.Phone()
        {
            Home = drContact["HomePhone"].ToString(),
            Mobile = drContact["MobilePhone"].ToString(),
            Work = drContact["WorkPhone"].ToString(),
        }
    };

    return mappedContact;
}