QuickBooks Online Connector - Create/Update Customer

This document details the process by which the App4Sales platform creates or updates customer records within QuickBooks Online. The process is initiated by the InsertOrUpdateCustomerCommand, which acts as the primary entry point for App4Sales customer data into the QuickBooks Online connector. The connector determines whether to create a new customer or update an existing one based on the presence of an App4Sales CustomerCode. If no CustomerCode is provided, a new customer is created. If a CustomerCode is present, the existing customer record in QuickBooks Online is updated using a sparse update mechanism.

Trigger & Permissions

The customer creation/update flow is triggered by the InsertOrUpdateCustomerCommand within the App4Sales platform. This command, in turn, invokes the CreateCustomer method of the QuickBooks Online connector. For this functionality to be active, the following connector information flags must be enabled:

ConnectorInfoInternalIds.CreateCustomer: Enables the creation of new customer records.
ConnectorInfoInternalIds.EditCustomer: Enables the modification of existing customer records.

Payload Mapping (Customer Header)

The following table illustrates how fields from the App4Sales XmlCustomer object are mapped to the corresponding fields in the QuickBooks Online Customer entity during creation or update:

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`CustomerCode`	`Id`	Used as the primary identifier in QuickBooks Online. If this field is empty, a new customer is created. Otherwise, an existing customer is updated.
`ContactFullName` (First Name)	`MainContactPersonGivenName`	Extracted as the first name from the App4Sales `ContactFullName`.
`ContactFullName` (Last Name)	`MainContactPersonFamilyName`	Extracted as the last name from the App4Sales `ContactFullName`.
`CustomerName`	`FullyQualifiedName`, `DisplayName`, `CompanyName`, `PrintOnCheckName`	The App4Sales customer name is mapped to multiple display and company name fields in QuickBooks Online.
`VatLiable`	`Taxable`	Boolean value indicating if the customer is VAT liable.
`Phone`	`PrimaryPhone.FreeFormNumber`	The customer's primary phone number.
`Email`	`PrimaryEmailAddr.Address`	The customer's primary email address.
N/A	`Active`	Hardcoded to `true`, meaning all customers created/updated via this connector are marked as active in QuickBooks Online.
N/A	`Job`	Hardcoded to `false`. This connector does not create customers as sub-customers or jobs in QuickBooks Online.
N/A	`Sparse`	Set to `true` for update operations (when `CustomerCode` is provided), indicating a sparse update (only provided fields are modified). `null` for create operations.
N/A	`SyncToken`	Used for update operations. Retrieved from QuickBooks Online before an update to prevent stale object modifications. Incremented by 1 before sending to QuickBooks Online.

Payload Mapping (Shipping Address)

The customer's delivery address in App4Sales is mapped to the shipping address (ShipAddr) in QuickBooks Online:

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`DeliveryAddress1`	`ShipAddr.Line1`	First line of the delivery address.
`DeliveryAddress2`	`ShipAddr.Line2`	Second line of the delivery address.
`DeliveryCity`	`ShipAddr.City`	City of the delivery address.
`DeliveryPostCode`	`ShipAddr.PostalCode`	Postal code of the delivery address.
`CountryCode`	`ShipAddr.Country`	The App4Sales country code is converted to the full country name using `CultureHelper.GetCountryFromIso2`.
`UnknownElements` (key: `Constants.StateForDeliveryAddressFieldName`)	`ShipAddr.CountrySubDivisionCode`	If the App4Sales `XmlCustomer` contains a state for the delivery address (e.g., for US states) in its `UnknownElements`, it is parsed and used as the country subdivision code. Validated against `Constants.StateUSA` enumeration.

Payload Mapping (Billing / Visit / Invoice Address)

The customer's visit address in App4Sales is mapped to the billing address (BillAddr) in QuickBooks Online:

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`VisitAddress1`	`BillAddr.Line1`	First line of the visit address.
`VisitAddress2`	`BillAddr.Line2`	Second line of the visit address.
`VisitCity`	`BillAddr.City`	City of the visit address.
`VisitPostCode`	`BillAddr.PostalCode`	Postal code of the visit address.
`CountryCode`	`BillAddr.Country`	The App4Sales country code is converted to the full country name using `CultureHelper.GetCountryFromIso2`.
`UnknownElements` (key: `Constants.StateForVisitAddressFieldName`)	`BillAddr.CountrySubDivisionCode`	If the App4Sales `XmlCustomer` contains a state for the visit address (e.g., for US states) in its `UnknownElements`, it is parsed and used as the country subdivision code. Validated against `Constants.StateUSA` enumeration.

Validation & Defaults

**Active Status**: All customers created or updated through this connector are explicitly marked as Active = true in QuickBooks Online.
**Job/Sub-Customer**: The Job field is always set to false, meaning customers are created as top-level entities, not as sub-customers or jobs.
**US States Handling**: If Settings.EnableCustomerUsaStatesFields is enabled, the connector attempts to parse and map state information from App4Sales' dynamic free fields (identified by Constants.StateForDeliveryAddressFieldName and Constants.StateForVisitAddressFieldName) to the CountrySubDivisionCode for shipping and billing addresses respectively. Values are validated against the Constants.StateUSA enumeration.
**Sparse Update**: For updates, the Sparse flag is set to true, ensuring that only the fields explicitly provided in the request are modified in QuickBooks Online.
**Concurrency Control**: The SyncToken mechanism is employed for updates. The connector retrieves the current SyncToken from QuickBooks Online for the customer and increments it before sending the update request. This prevents data loss due to concurrent modifications.

Response & Error Handling

Upon successful creation or update, the QuickBooks Online API returns a CreateOrUpdateCustomerResponse containing the newly created or updated QuickBooksOnlineCustomer object. The Id of this customer is then used to populate the App4Sales CustomerCode.

In case of an error during the API call, exceptions are caught and logged using the LogMe utility. Errors during creation or update will result in an exception being thrown, providing details such as "Invalid response while customer create" or "Error occurred while updating customer". These errors are surfaced back to the App4Sales platform to indicate the failure of the operation.

Related Settings & Prerequisites

The following settings and prerequisites are relevant to the customer creation/update functionality:

**Connector Info Flags**: CreateCustomer and EditCustomer must be enabled in the App4Sales administration for the QuickBooks Online connector.
**Enable Customer USA States Fields**: If enabled, this setting allows the connector to process and store US state information for customer addresses.
**Custom Extra Fields**: The connector utilizes custom extra fields (Constants.StateForVisitAddressFieldName and Constants.StateForDeliveryAddressFieldName) in App4Sales to manage US state data for visit and delivery addresses. These fields are initialized as dropdowns if EnableCustomerUsaStatesFields is true and they don't already exist.

QuickBooksOnline - Create customer