NetSuite Connector - Create Customer

This document describes the process of creating or updating customer records in NetSuite via the App4Sales platform using the NetSuite Connector. This functionality is primarily handled by the InsertOrUpdateCustomerCommand, which acts as the entry point for customer data from App4Sales into NetSuite. The connector leverages NetSuite's API to manage customer and contact records, including associated addresses, pricing, and other details.

Trigger & Permissions

The customer creation/update flow is enabled when the connector is configured with specific internal IDs. The InsertOrUpdateCustomerCommand is active when either Core.Constants.ConnectorInfoInternalIds.EditCustomer or Core.Constants.ConnectorInfoInternalIds.CreateCustomer flags are set within the connector's information. This controls whether the App4Sales system permits the modification or creation of customer records through this connector.

Data Source Configuration

The primary data source for customer creation/update is the App4Sales Customer object, which encapsulates all relevant customer and contact information. This data is then transformed and sent to the NetSuite ERP system using NetSuite's web services API. The connector pulls necessary configuration settings (e.g., default subsidiary, custom form IDs) from its internal settings to correctly format the data for NetSuite.

Payload Mapping - Customer Header Fields

The following table details the mapping from App4Sales customer fields to NetSuite customer record fields when creating or updating a customer:

App4Sales Field	Source Field (App4Sales Model)	Logic/Notes
Phone	`customer.Phone`	Direct mapping.
Mobile Phone	`customer.MainContactPerson.MobileNumber`	Mapped from the mobile number of the main contact person associated with the App4Sales customer.
Fax	`customer.Fax`	Direct mapping.
Company Name	`customer.CustomerName`	Direct mapping.
Email	`customer.MainContactPerson.Email`	Mapped from the email address of the main contact person associated with the App4Sales customer.
Is Inactive	`false`	Hardcoded to `false`; new customers are always created as active in NetSuite.
External ID	`customer.ExtraData ?? customer.CustomerGuid.GetHashCode().ToString()`	Uses the `ExtraData` field if available. If not, a hash code of the `CustomerGuid` is used to generate a unique external ID.
VAT Registration Number	`customer.VatCode`	Direct mapping to NetSuite's VAT registration number field.
Is Person	`false`	Hardcoded to `false`; customers are always treated as companies/organizations in NetSuite.
First Name	`customer.MainContactPerson.FirstName`	Mapped from the main contact person's first name, only if the setting "Only Send In Business Data On The Company When Creating A Customer" is `false`.
Last Name	`customer.MainContactPerson.LastName`	Mapped from the main contact person's last name, only if the setting "Only Send In Business Data On The Company When Creating A Customer" is `false`.
Phonetic Name	`customer.MainContactPerson.FullName`	Mapped from the main contact person's full name, only if the setting "Only Send In Business Data On The Company When Creating A Customer" is `false`.
Currency	`customerPriceList?.ExternalCurrency`	Set as a record reference using the external currency ID from the associated App4Sales price list.
Payment Terms	`customer.PaymentConditionCode`	Set as a record reference using the payment condition code from the App4Sales customer, if not empty.
Entity ID	`netSuiteCustomer.companyName`	Only applies when creating a new customer (not an update) and the setting "Setup Entity Id For New Customer" is `true`. The company name is used as the entity ID.
Taxable	`customer.VatLiable`	Only applies when creating a new customer (not an update) and the setting "Setup Vat Liable For New Customer" is `true`. The VAT liability status from the App4Sales customer is used.
Custom Form	`Settings.CustomerCustomFormName`	Set as a record reference using the internal ID derived from the `CustomerCustomFormName` setting. Only applies when creating a new customer.
Entity Status	`Settings.CustomerStatusName`	Set as a record reference using the internal ID derived from the `CustomerStatusName` setting. This defines the customer's stage (e.g., Lead, Prospect, Customer) in NetSuite. Only applies when creating a new customer.
Language	`customer.LanguageCode`	Mapped if the App4Sales `LanguageCode` is not empty and can be resolved to a valid NetSuite language enumeration.
Custom Fields	`customer.UnknownElements` or specific NetSuite properties	Custom fields are populated from `customer.UnknownElements` or directly from configured custom field mappings. The connector supports mapping to NetSuite custom fields prefixed with "cust" (e.g., `custentity_field`) or standard entity fields prefixed with "entity" (e.g., `entity_comments`). Additionally, `customer.ChamberOfCommerceCode` can be mapped to a custom field specified by the `CustomFieldForChamberOfCommerce` setting if `StoreCustomerCategoryFieldToFreeFields` is enabled.
Price Level	`customerPriceList.ExternalId` or Sales Rep's default price list	The price level is determined by the `SetPriceLevel` logic: If `UseSalesRepDefaultPriceListForCreateCustomer` is `true` and the sales representative has a default price list specified, that price list's external ID is used. Otherwise, the external ID from the App4Sales customer's selected price list (`customerPriceList.ExternalId`) is used.
Subsidiary	Determined based on Sales Rep or Default Subsidiary setting	Only applies when creating a new customer. If `UseTheSubsidiaryOfTheSalesRep` is `true`, the sales representative's subsidiary is used. Otherwise, the subsidiary specified by `DefaultCustomerSubsidiary` is applied.
Addresses	`customer.Addresses`	App4Sales addresses of type "Visit" and "Delivery" are mapped to NetSuite address book entries. The `defaultBilling` and `defaultShipping` flags are set based on whether the address is a shipping address.
Tax Item	`customer.VatLiable` and tax item settings	Based on the `customer.VatLiable` status, and the connector settings `TaxItemValueForVatLiableIsTrue` and `TaxItemValueForVatLiableIsFalse`, the appropriate NetSuite Sales Tax Item is assigned to the customer.

Payload Mapping - Contact Person Fields

The following table details the mapping from the App4Sales main contact person fields to NetSuite contact record fields:

App4Sales Field	Source Field (App4Sales Model)	Logic/Notes
Company	`customer.InternalCode`	Set as a record reference linking the contact to the newly created or updated customer in NetSuite.
First Name	`customer.MainContactPerson.FirstName`	Direct mapping.
Middle Name	`customer.MainContactPerson.MiddleName`	Direct mapping.
Last Name	`customer.MainContactPerson.LastName`	Direct mapping.
Entity ID	`customer.MainContactPerson.FullName`	The full name of the main contact person.
Mobile Phone	`customer.MainContactPerson.MobileNumber`	Direct mapping.
Email	`customer.MainContactPerson.Email`	Direct mapping.
Phone	`customer.MainContactPerson.Phonenumber`	Direct mapping.
Phonetic Name	`customer.MainContactPerson.FullName`	The full name of the main contact person.
Subsidiary	Determined based on Sales Rep or Default Subsidiary setting	Only applies when creating a new contact (not an update). The subsidiary is set according to the same logic as for the customer.

Validation & Defaults

Required Fields: While not explicitly shown as blocking validation in the connector code for App4Sales fields, NetSuite API calls will typically fail if mandatory fields are missing.
Default Values:
- New customers are always created as active (isInactive = false).
- Customers are always treated as companies/organizations (isPerson = false).
- If customer.CustomerCode is empty after the NetSuite operation, an exception is thrown, indicating that a customer code could not be retrieved from the ERP.
- Country parsing: If a country string cannot be directly matched to a NetSuite country enumeration, it attempts to find a partial match. If no match is found, an exception is thrown.
VAT Liability: The VAT liability (customer.VatLiable) is mapped based on settings such as UseTaxRegNrForVatliability and the customer's delivery address country, or directly from NetSuite's taxable field or linked tax item.

Response & Error Handling

After submitting customer and contact data to NetSuite:

Customer Upsert: The CustomersRepository.SendCustomer method performs an upsert operation (insert or update). It handles the NetSuite API response and extracts the internal ID of the created or updated customer. The customer object passed by reference is then updated with the NetSuite internalId and CustomerCode.
Contact Upsert: The CustomersRepository.SendContact method performs an add or update operation for the contact person. It also handles the NetSuite API response and returns the internal ID of the contact.
Contact Attachment: The CustomersRepository.AttachContactPersonToCustomer method links the contact person to the customer in NetSuite, optionally assigning a specific contact role (e.g., "Primary Contact").
Error Handling:
- If NetSuite does not return a customer code after a creation attempt, an Exception is thrown with the message "No customercode retrieved from the ERP".
- Warnings are logged if contact persons are not created/updated successfully (e.g., "Contact was not updated/created.").
- General exceptions during API calls are caught and logged, but then re-thrown to propagate the error.

Special Logic & Filters

Subsidiary Assignment: For new customers, the subsidiary is determined by the connector setting UseTheSubsidiaryOfTheSalesRep (using the sales rep's subsidiary if enabled) or falls back to the DefaultCustomerSubsidiary setting.
Price Level Assignment: The price level for a new customer is set based on either the sales representative's default price list (if enabled via UseSalesRepDefaultPriceListForCreateCustomer) or the external ID of the price list selected within App4Sales.
Custom Forms and Statuses: The connector attempts to retrieve and apply NetSuite custom form IDs and customer status IDs based on the CustomerCustomFormName and CustomerStatusName settings respectively.
Address Processing: App4Sales addresses are mapped to NetSuite's address book, specifically handling "Visit" and "Delivery" address types and setting default billing/shipping flags.
VAT Tax Items: Appropriate sales tax items are assigned based on the customer's VAT liability and connector settings (TaxItemValueForVatLiableIsTrue, TaxItemValueForVatLiableIsFalse).

Related Settings & Prerequisites

The following connector settings influence the customer creation process:

Use the subsidiary of the sales rep: (UseTheSubsidiaryOfTheSalesRep) If true, the sales representative's assigned subsidiary in NetSuite is used for new customers.
Default customer subsidiary: (DefaultCustomerSubsidiary) Specifies the default NetSuite subsidiary name to use if a sales rep's subsidiary is not applicable or found.
Primary contact role name: (PrimaryContactRoleName) The name of the contact role in NetSuite to assign to the main contact person.
Customer custom form name: (CustomerCustomFormName) The name of a custom customer form in NetSuite to be used for new customer records.
Customer status name: (CustomerStatusName) The name of a customer status in NetSuite to assign to new customer records (e.g., "Lead", "Qualified").
Only send in business data on the company when creating a customer: (OnlySendInBusinessDataOnTheCompanyWhenCreatingACustomer) If true, individual contact details (first name, last name) from the main contact person are not sent to the NetSuite customer record.
Setup entity id for new customer: (SetupEntityIdForNewCustomer) If true, the customer's company name is used as the NetSuite entity ID for new customers.
Setup vat liable for new customer: (SetupVatLiableForNewCustomer) If true, the customer's VAT liability status from App4Sales is explicitly set in NetSuite upon creation.
Tax item value for vat liable is true: (TaxItemValueForVatLiableIsTrue) The name of the NetSuite Sales Tax Item to use when a customer is VAT liable.
Tax item value for vat liable is false: (TaxItemValueForVatLiableIsFalse) The name of the NetSuite Sales Tax Item to use when a customer is not VAT liable.
Use sales rep default price list for create customer: (UseSalesRepDefaultPriceListForCreateCustomer) If true, the default price list assigned to the sales representative is used for new customers.
Use tax reg nr for vat liability: (UseTaxRegNrForVatliability) If true, the customer's VAT registration number and country are used to determine VAT liability.
Use country for tax reg nr vat liability: (UseCountryForTaxRegNrVatLiability) The country code used in conjunction with UseTaxRegNrForVatliability to determine VAT liability based on geographical rules.
Customer discount custom field name: (CustomerDiscountCustomFieldName) The script ID of a custom field in NetSuite where customer discount information is stored.
Custom Field For Company Name: (CustomFieldForCompanyName) Script ID of a custom field to store/retrieve the company name.
Custom Field For Customer Manager: (CustomFieldForCustomerManager) Script ID of a custom field to store/retrieve the customer manager.
Custom Field For Chamber Of Commerce: (CustomFieldForChamberOfCommerce) Script ID of a custom field to store/retrieve the Chamber of Commerce code.
Customer Free Fields Configuration: (CustomerFreeFieldsConfiguration) JSON configuration for mapping arbitrary App4Sales free fields to NetSuite custom fields.
Store Customer Category Field To Free Fields: (StoreCustomerCategoryFieldToFreeFields) If true, the NetSuite customer category field is stored as a free field in App4Sales.

Known Limitations

The connector assumes that if a customer code is not returned by NetSuite after creation, the operation has failed.
Country mapping relies on string matching and might require exact or very close matches to NetSuite's country enumerations.

NetSuite - Create customer