Summary

The Add/Update QuickBooks Online Customer TO iPaaS.com mapping collection brings QuickBooks Online customers into iPaaS.com as iPaaS.com customers, so QuickBooks can act as the customer master for businesses that bill accounts and services from QuickBooks. It creates an iPaaS.com customer for a QuickBooks customer that has not been transferred before, and updates the linked iPaaS.com customer when the QuickBooks customer changes.

The collection transfers the customer's name, company, email and notes, and gives each new iPaaS.com customer a customer number. A customer number, company or comment the iPaaS.com customer already has is kept when QuickBooks has no value for it. Before creating anything, the integration looks for an iPaaS.com customer with the same email and links to it, so a customer that already exists in iPaaS.com is updated rather than duplicated. The customer's QuickBooks billing and shipping addresses travel with it through the Add/Update QuickBooks Online Customer Address TO iPaaS.com child collection.

ID Format

Manual Sync ID: the QuickBooks customer id, a number QuickBooks assigns to each customer, such as 1052.
External ID saved after sync: the QuickBooks customer id, for example 1052. iPaaS.com keeps it in an external-ID record for this subscription that links the QuickBooks customer to its iPaaS.com customer, so later transfers of the same customer update that iPaaS.com customer instead of creating another.
Address external IDs: each address is linked separately as the QuickBooks customer id followed by |BILL or |SHIP, for example 1052|BILL and 1052|SHIP.
Customer number: a new iPaaS.com customer gets QBO- followed by the QuickBooks customer id, for example QBO-1052. It is there for visibility; it is not the link.

Deleted Record Support

Not supported. QuickBooks does not delete customers, only makes them inactive, and inactive customers are skipped by this collection's filter. iPaaS.com customers have no active field, so making a customer inactive in QuickBooks does not change or remove its iPaaS.com customer, and later changes to that inactive customer are not sent.

Mapping Collection Status

Status: Enabled.
Trigger events: the customer/poll scope (scheduled polling). Intuit webhooks are not offered in this release.

Duplicate or Conflicting Mappings

These collections also create or change the same customers:

Add/Update QuickBooks Online Customer FROM iPaaS.com: sends iPaaS.com customers to QuickBooks.
Add QuickBooks Online Sales Receipt FROM iPaaS.com and Add/Update QuickBooks Online Invoice FROM iPaaS.com: find the QuickBooks customer for each transaction by email (by name when there is no email), and create it in QuickBooks when none exists. Because the integration wrote that customer, expect its first transfer TO iPaaS.com to be skipped as the echo of that write, with no error; it then arrives the next time it changes in QuickBooks. To bring it over sooner, run Manual Sync with its QuickBooks customer id, and run it again if the customer does not appear in iPaaS.com. When it arrives, it is linked by email (see below).
Add/Update QuickBooks Online Customer Address FROM iPaaS.com: writes iPaaS.com customer addresses to QuickBooks as the billing and shipping address, the opposite direction of this collection's child.

Decide which system is the source of truth for customer data before you turn on both directions. The integration tells iPaaS.com about each customer it writes FROM iPaaS.com, so the next poll does not send that same change back as a new one. That skip applies to the next transfer of that customer TO iPaaS.com, whatever it carries, so a QuickBooks edit made between an iPaaS.com write and the next poll is not sent TO iPaaS.com until the customer changes again in QuickBooks. Outside that window, an edit made in either system, including an address edit, is copied to the other by whichever collection runs next. Review both collections' filters before going live.

Collision handling is not used on this collection, and the default template does not set a Collision Handling Method; matching is automatic. Before a QuickBooks customer that is not linked yet is transferred, the integration looks for iPaaS.com customers with the same email address, not case-sensitive:

Exactly one match, not linked to another QuickBooks customer of this subscription: the integration links them, and the transfer updates that iPaaS.com customer. No error is logged.
No match: the transfer creates a new iPaaS.com customer.
Several matches, or a match already linked to another QuickBooks customer: nothing is linked. iPaaS.com allows one customer per email, so it refuses the new customer and the error appears in Dashboard / Integration Monitoring / Error Logs; the log also names the iPaaS.com customers that have the email. Resolve the duplicate iPaaS.com customers, or link the right one by setting the QuickBooks customer id (for example 1052) as the external ID of that iPaaS.com customer for this subscription, then transfer the QuickBooks customer again.

Supported Child Collections

Add/Update QuickBooks Online Customer Address TO iPaaS.com: transfers the customer's QuickBooks billing and shipping addresses as iPaaS.com customer addresses, with the customer's name, company and primary phone. It runs as part of each transfer of the parent; addresses cannot be sent on their own.

System Caveats

QuickBooks Online Caveats

Customers are never deleted: QuickBooks makes customers inactive instead, and inactive customers are skipped by this collection's filter.
One billing and one shipping address: QuickBooks keeps exactly one billing address and one shipping address on each customer. Each arrives in iPaaS.com as its own address; when a customer has only one of them, only that one is sent. Other addresses a customer has in iPaaS.com do not come from QuickBooks.
Names and phone live on the customer: QuickBooks addresses carry no name, company or phone, so the address mappings take them from the customer. Only the primary phone is transferred, and it is copied to both addresses; mobile and fax are not transferred.
Address lines 4 and 5: QuickBooks addresses can have up to five street lines; only lines 1 to 3 are transferred.
Values as entered: the state or province and the country are sent exactly as they were typed in QuickBooks; they are not converted to codes.
Sub-customers and jobs: a QuickBooks sub-customer or job arrives as an ordinary iPaaS.com customer; its parent customer is not transferred with it.
Rate limits: QuickBooks Online accepts at most 500 requests a minute and 10 requests a second for each connected company. When a limit is reached, the transfer is rescheduled automatically and runs again after about a minute. If rate-limit errors continue for hours, QuickBooks' monthly limit for the iPaaS.com app may have been reached: contact your MiSP or iPaaS.com Support (see QuickBooks Online Known Limitations).

iPaaS.com Caveats

Email address and customer number: every iPaaS.com customer needs an email address and a customer number. A QuickBooks customer without an email fails until one is added in QuickBooks; the template always supplies the customer number.
One customer per email: iPaaS.com allows one customer per email address, which is why the integration links by email before it creates (see Duplicate or Conflicting Mappings).
Whole-record updates: an update TO iPaaS.com replaces the whole customer and each whole address. Every standard iPaaS.com Customer field is mapped; the child collection leaves one address field unmapped, Type, which is overwritten with an empty value on every transfer, as is any field whose mapping you remove. Plain copies (FirstName, LastName, EmailAddress and the address fields) replace whatever another system wrote, even when the QuickBooks value is blank; a blank email is refused rather than written. The CustomerNumber, Company and Comment mappings keep the existing iPaaS.com value through DestinationValue when QuickBooks has none: keep them. To keep another value, map the field with a Dynamic Formula that reads DestinationValue with a null check, for example FirstName as return GivenName != null ? GivenName : (DestinationValue != null ? DestinationValue.FirstName : null); or the address Type as return DestinationValue != null ? DestinationValue.Type : null;. Subscribers or their MiSP should validate such a formula in a staging environment before relying on it in production. The customer's categories are a separate list and are not changed by this collection.
Retries: iPaaS.com retries every errored transfer automatically on a growing schedule. A transfer that fails because of the data (a missing email, for example) fails again on each retry until the QuickBooks customer is corrected.

Prerequisite Handling

None. A customer TO iPaaS.com depends on no other record; its addresses are saved with it by the child collection.

Setup Requirements

iPaaS.com Configuration

Automatic transfers do not start by themselves. In Dashboard / Integration Monitoring / Events, add a polling event for this subscription and the customer/poll scope, and set it to run every 15 minutes (see Events). No customers are transferred until that polling event exists. The child collection needs no setup of its own.

Initialization is not supported. The first poll looks back only the number of days in the Initial Poll Days subscription setting (7 when blank); later polls continue from where the previous one stopped. To bring in more history, raise Initial Poll Days before the first poll that finds a customer (once a poll has found one, changing it has no effect), transfer customers one at a time with Manual Sync, or use bulk sync using Postman.

QuickBooks Online Configuration

Nothing beyond the connection. Give every QuickBooks customer you want in iPaaS.com an email address, and avoid giving two QuickBooks customers the same email: iPaaS.com refuses a customer without one and allows one customer per email.

Integration Flow

The customer/poll scope finds QuickBooks customers created or changed since the previous poll, active and inactive. Manual Sync starts at the next step with the id you enter.
The integration reads the customer from QuickBooks with its billing and shipping addresses.
If the QuickBooks customer is not linked yet, the integration links it to the one iPaaS.com customer with the same email, when there is exactly one and it is not linked to another QuickBooks customer of this subscription (see Duplicate or Conflicting Mappings).
The filter keeps only active customers.
iPaaS.com creates the customer, or updates the linked one, with the mapped values.
The child collection saves the billing and shipping addresses on that iPaaS.com customer, each linked by the customer id followed by |BILL or |SHIP. If the parent transfer fails, its addresses are not transferred either.

Mappings

Add/Update QuickBooks Online Customer TO iPaaS.com

iPaaS.com data type: Customer

Mapping Filter

// Active QuickBooks customers.
return Active == true;

Filter Description. Only QuickBooks customers whose Active value is true pass. The poll also finds inactive customers, and this filter skips them without an error.

Mapping Type	Source Field (QuickBooks Online)	Destination Field (iPaaS.com)	Description
Dynamic Formula	`return DestinationValue != null && DestinationValue.CustomerNumber != null ? DestinationValue.CustomerNumber : "QBO-" + Id;`	CustomerNumber	Required. An iPaaS.com customer that already has a customer number keeps it, so linking or updating never renumbers a customer another system created. A new customer gets QBO- followed by the QuickBooks customer id, for example QBO-1052. The customer number is not the link.
Field	GivenName	FirstName	Recommended. The QuickBooks first name replaces the iPaaS.com first name on every update, including when QuickBooks has none.
Field	FamilyName	LastName	Recommended. The QuickBooks last name replaces the iPaaS.com last name on every update, including when QuickBooks has none.
Field	Email	EmailAddress	Required. The QuickBooks primary email. iPaaS.com refuses a customer without one; add an email in QuickBooks and transfer it again. It is also how a QuickBooks customer not linked yet is matched to an existing iPaaS.com customer.
Dynamic Formula	`return CompanyName != null ? CompanyName : (DestinationValue != null && DestinationValue.Company != null ? DestinationValue.Company : (GivenName == null && FamilyName == null ? DisplayName : null));`	Company	Recommended. The QuickBooks company name; otherwise the existing iPaaS.com company; otherwise, only for a customer with no first and no last name, the QuickBooks display name (for example Acme Supply), so a customer known only by its display name still arrives with a name. Keep this mapping.
Dynamic Formula	`return Notes != null ? Notes : (DestinationValue != null ? DestinationValue.Comment : null);`	Comment	Optional. The QuickBooks customer notes (up to 2,000 characters). When QuickBooks has no notes, the existing iPaaS.com comment is kept, so an update does not clear a comment entered in iPaaS.com.

Add/Update QuickBooks Online Customer Address TO iPaaS.com (child)

iPaaS.com data type: Customer Address

Mapping Type	Source Field (QuickBooks Online)	Destination Field (iPaaS.com)	Description
Dynamic Formula	`return Parent.GivenName;`	FirstName	Optional. The parent customer's first name, put on each of its addresses; empty when the customer has none.
Dynamic Formula	`return Parent.FamilyName;`	LastName	Optional. The parent customer's last name, put on each of its addresses; empty when the customer has none.
Dynamic Formula	`return Parent.CompanyName;`	Company	Optional. The parent customer's company name, put on each of its addresses; empty when the customer has none.
Field	Line1	Address1	Recommended. Street line 1 of the QuickBooks billing or shipping address. Only lines 1 to 3 are transferred; lines 4 and 5 do not reach iPaaS.com.
Field	Line2	Address2	Optional. Street line 2. When QuickBooks has no line 2, the iPaaS.com value is cleared on update.
Field	Line3	Address3	Optional. Street line 3.
Field	City	City	Recommended. The address city.
Field	State	Region	Recommended. The state or province code exactly as entered in QuickBooks, for example CA.
Field	Country	Country	Optional. The country exactly as entered in QuickBooks (for example USA or United States); it is not converted to a country code.
Field	PostalCode	PostalCode	Recommended. The address postal code.
Dynamic Formula	`return AddressType == "BILL";`	IsPrimaryBilling	Recommended. True for the QuickBooks billing address (labelled BILL), false for the shipping address, so iPaaS.com knows which address is the billing address.
Dynamic Formula	`return AddressType == "SHIP";`	IsPrimaryShipping	Recommended. True for the shipping address (labelled SHIP), false for the billing address. When the two are the same in QuickBooks, iPaaS.com still receives two addresses.
Dynamic Formula	`return Parent.Phone;`	PhoneNumber	Optional. The parent customer's primary phone, put on each of its addresses. Mobile and fax are not transferred.

Error Handling

Errors appear in Dashboard / Integration Monitoring / Error Logs, and iPaaS.com retries an errored transfer automatically on a growing schedule. Inactive customers are skipped without an error, and linking by email never fails a transfer.

Customer without an email (from iPaaS.com): iPaaS.com refuses a customer with no email address. Add an email to the customer in QuickBooks, then transfer it again.
BIZL-1006 (from iPaaS.com): the QuickBooks customer could not be linked (several iPaaS.com customers have its email, or the one that has it is linked to another QuickBooks customer), and iPaaS.com refused a new customer with the same email. Resolve the duplicates or link the right customer by hand (see Duplicate or Conflicting Mappings).
QBOL-EXTN-1013: QuickBooks limited the request rate; iPaaS.com retries after a minute.
Connection errors (QBOL-AUTH codes) are covered in QuickBooks Online Error Messages.

Testing & Validation

Create a customer in QuickBooks with a first and last name, a company, an email, notes, a phone, and different billing and shipping addresses. Transfer it with Manual Sync, or wait for the next poll. Confirm iPaaS.com has the customer with customer number QBO- followed by its QuickBooks id, and two addresses, one marked primary billing and one primary shipping, each carrying the customer's name, company and phone.
Create an iPaaS.com customer, then a QuickBooks customer with the same email in different letter case, and transfer the QuickBooks customer. Confirm no new iPaaS.com customer is created and the existing one is updated, keeping its customer number.
Clear the notes on the QuickBooks customer and transfer it again. Confirm the iPaaS.com comment is kept.
Transfer a QuickBooks customer with no email. Confirm the error in Dashboard / Integration Monitoring / Error Logs; add an email in QuickBooks and transfer it again.
Make a QuickBooks customer inactive and transfer it. Confirm the iPaaS.com customer is unchanged.

Additional Notes

Out of scope: deletes (QuickBooks never deletes customers); QuickBooks customer custom fields; the sub-customer and job relationship.
Known limitations: changes reach iPaaS.com only when the scheduled poll runs; QuickBooks address lines 4 and 5 are not transferred; updates TO iPaaS.com replace the whole record. See QuickBooks Online Known Limitations.

QuickBooks Online to iPaaS.com Customer Mapping Documentation