Summary
The Add/Update QuickBooks Online Customer FROM iPaaS.com mapping collection sends iPaaS.com customers to QuickBooks Online as QuickBooks customers, so customers captured in other systems (for example an online store) are ready in QuickBooks before they are invoiced. It creates a QuickBooks customer for an iPaaS.com customer that is not linked yet, and updates the linked QuickBooks customer when the iPaaS.com customer changes.
The collection sends the customer's company, first and last name, email and comment, and builds the QuickBooks display name from them. Before creating a customer, the integration looks for one QuickBooks already has: by email, or by display name only when the customer has no email. What happens on a match follows the collection's Collision Handling Method. The customer's billing and shipping addresses are written inside the same QuickBooks customer through the Add/Update QuickBooks Online Customer Address FROM iPaaS.com child collection.
ID Format
Manual Sync ID: the iPaaS.com Customer ID, for example 100245.
External ID saved after sync: the QuickBooks customer id, for example 1052. After a successful create, or a link made by collision handling, iPaaS.com keeps it in an external-ID record for this subscription that links the iPaaS.com customer to its QuickBooks customer, so later transfers of the same customer update that QuickBooks customer instead of creating another. Addresses have no link of their own: they are written inside the QuickBooks customer.
Deleted Record Support
Not supported. QuickBooks never deletes customers, and deleting a customer in iPaaS.com does not change QuickBooks, so do not subscribe to customer/deleted. To make a QuickBooks customer inactive, subscribers or their MiSP can add a mapping to the QuickBooks Active field that returns false for the customers to deactivate; the default template does not map it. Validate such a mapping in a staging environment before relying on it in production.
Mapping Collection Status
Status: Enabled.
Trigger events: the iPaaS.com customer/created and customer/updated events, once subscribed under Outbound Data Flows. Whether a transfer creates or updates a QuickBooks customer depends on whether the iPaaS.com customer is already linked to one, not on which event fired.
Duplicate or Conflicting Mappings
These collections also create or change the same QuickBooks customers:
Add/Update QuickBooks Online Customer TO iPaaS.com: brings QuickBooks customers TO iPaaS.com, in the opposite direction. A customer this collection has just written is not sent straight back on the next poll.
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. A customer created that way is not linked to the iPaaS.com customer, so when that customer later goes through this collection, the create finds it by email and follows the Collision Handling Method.
Important: Decide which system is the source of truth for customer data before you turn on both directions. Every update from this collection replaces the mapped QuickBooks values, including edits a bookkeeper made in QuickBooks, and rebuilds the display name. Fields this collection does not map are left as they are in QuickBooks.
Collision handling. The Collision Handling Method setting is on this mapping collection's settings in iPaaS.com. It decides what happens when a create finds a QuickBooks customer, active or inactive, with the same email (or, when the customer has no email, the same display name). The default template ships with no collision setting, which behaves as Error. Choose a method before going live:
Error: the transfer fails with QBOL-BIZL-1001 naming the existing customer's id and display name. Nothing is written and nothing is linked.
Remap and Link: the iPaaS.com customer is linked to the existing QuickBooks customer, and iPaaS.com then updates it with the mapped data. The existing customer's values are overwritten, including its display name.
Update and Link: the same result as Remap and Link. The existing QuickBooks customer is linked and updated, and its display name is replaced.
Update and No Link: the existing QuickBooks customer is updated with the mapped data, but no link is saved, so iPaaS.com does not record which QuickBooks customer it updated.
When two or more QuickBooks customers have the customer's email, no method picks one: the transfer fails with QBOL-BIZL-1002 naming them, and nothing is written or linked. Give each QuickBooks customer its own email, or link the iPaaS.com customer to the right QuickBooks customer, then send the customer again.
Linking keeps one QuickBooks customer per person, including a customer a transaction created earlier. Subscribers or their MiSP should expect any linked customer to take the iPaaS.com values from then on.
Supported Child Collections
Add/Update QuickBooks Online Customer Address FROM iPaaS.com: writes the iPaaS.com customer's addresses as the QuickBooks billing and shipping address, inside the customer record in the same transfer. There is no separate QuickBooks address record and no separate link.
System Caveats
QuickBooks Online Caveats
Display names are unique: a display name must be unique across all QuickBooks customers, vendors and employees, including inactive ones, and QuickBooks allows up to 500 characters. On a create, when the name belongs to a vendor, an employee or another customer with a different email, the integration adds the email in parentheses, for example Jane Smith (jane@example.com), and creates the customer. Without an email, a name used by another QuickBooks customer is treated as a match, and a name used by a vendor or an employee fails the create with QBOL-EXTN-1010.
Display names follow the source: the display name is rebuilt on every update, so changing the company or the name in iPaaS.com renames the customer in QuickBooks. A customer created as Jane Smith (jane@example.com) keeps that name while the mapped name is still Jane Smith. When an update renames a customer to a name already in use, the update is tried once more with the email added; without an email, it fails with QBOL-EXTN-1010.
Inactive customers still count: an inactive QuickBooks customer still owns its display name and is still found by the email or name match.
Field lengths: first name, last name, company name and email allow 100 characters each, notes 2,000, and each address street line 500. A longer value fails the transfer with QBOL-EXTN-1007.
Characters in display names: QuickBooks does not accept a colon, tab or line break in a display name; such a value fails the transfer.
One billing and one shipping address: QuickBooks keeps exactly one of each per customer. When the transfer carries an address, QuickBooks keeps only what is sent for it, except address lines 4 and 5, which are kept.
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, iPaaS.com holds the transfer and retries it after about a minute (see QuickBooks Online Known Limitations).
iPaaS.com Caveats
Sparse updates: an update sends only the fields that carry a value. A field with no value in iPaaS.com is not sent, and the QuickBooks value stays as it is; a field that holds an empty text value is sent and clears the QuickBooks field.
Stale link: when the linked QuickBooks customer no longer exists, the update fails with QBOL-NFND-1003. Remove the stale link in iPaaS.com and send the customer again.
Retries: iPaaS.com retries every errored transfer automatically on a growing schedule. An error caused by the data (a duplicate display name, for example) repeats on each retry until the customer or the mapping is corrected.
Prerequisite Handling
None. A customer depends on no other record, and its addresses are written in the same transfer.
Setup Requirements
iPaaS.com Configuration
Automatic transfers do not activate by default. In the subscription configuration, open Outbound Data Flows and subscribe to the iPaaS.com customer/created and customer/updated events. Until they are subscribed, no customers transfer automatically. Do not subscribe to customer/deleted, and do not subscribe to the iPaaS.com customer address events: addresses cannot be transferred on their own, and an address change reaches QuickBooks the next time its customer is sent.
Before going live, choose the collection's Collision Handling Method (see Duplicate or Conflicting Mappings).
QuickBooks Online Configuration
Nothing beyond the connection. Where existing QuickBooks customers share an email, give each its own email before going live, so that customers with that email can be matched.
Integration Flow
The customer/created or customer/updated event, or Manual Sync with the iPaaS.com Customer ID, starts the transfer.
The filter keeps only customers that have an email or a company.
The integration builds the display name: the company name; else the first and last name; else the email. A customer with none of these fails with QBOL-VALD-1001.
Create (customer not linked yet): the integration looks for a QuickBooks customer, active or inactive, with the same email, or with the same display name only when the customer has no email. On a match, the transfer follows the Collision Handling Method; when two or more customers have the email, it fails with QBOL-BIZL-1002. With no match, the customer is created with its billing and shipping addresses. If QuickBooks reports that the display name is already in use and the customer has an email, the create is tried once more with the email added to the display name. A create retried after a lost response returns the customer QuickBooks created the first time instead of creating a second one.
Update (customer linked): the integration reads the customer's current version from QuickBooks, then sends only the fields that carry a value, with the addresses. A customer saved in QuickBooks as the name with the email added keeps that name, and address lines 4 and 5 are kept. If someone saved the customer in QuickBooks between the read and the write, the integration reads it again and retries once.
iPaaS.com saves the QuickBooks customer id as the customer's external ID.
Mappings
Add/Update QuickBooks Online Customer FROM iPaaS.com
iPaaS.com data type: Customer
Mapping Filter
// Customers with an email or a company name. return EmailAddress != null || Company != null;
Filter Description. Only iPaaS.com customers that have an EmailAddress or a Company are sent. A customer with neither (for example, a customer with only a first and last name) is skipped without an error and never reaches QuickBooks. Because of this filter, the display-name match on create applies only to customers that have a company and no email.
Mapping Type | Source Field (iPaaS.com) | Destination Field (QuickBooks Online) | Description |
Field | FirstName | GivenName | Recommended. When the customer has no company, the first and last name together become the QuickBooks display name (for example Jane Smith). Up to 100 characters. |
Field | LastName | FamilyName | Recommended. Joins the first name to form the display name when the customer has no company. Up to 100 characters. |
Field | Company | CompanyName | Recommended for business customers. When it has a value, it also becomes the QuickBooks display name (for example Acme Supply), so changing the company in iPaaS.com renames the customer in QuickBooks on the next update. Up to 100 characters. |
Field | EmailAddress | Recommended; keep it mapped. The key a create uses to find a customer QuickBooks already has, and the value added to a display name that is already in use. Two or more QuickBooks customers with the same email fail the transfer with QBOL-BIZL-1002. Up to 100 characters. | |
Field | Comment | Notes | Optional. Sends the iPaaS.com customer Comment to the QuickBooks customer Notes. Up to 2,000 characters. |
At least one of CompanyName, GivenName, FamilyName or Email must have a value, or the transfer fails with QBOL-VALD-1001. When a mapped field has no value, an update leaves the QuickBooks value as it is; an empty text value clears it.
Add/Update QuickBooks Online Customer Address FROM iPaaS.com (child)
iPaaS.com data type: Customer Address
Mapping Type | Source Field (iPaaS.com) | Destination Field (QuickBooks Online) | Description |
Dynamic Formula |
| AddressType | Recommended. An address marked primary shipping and not primary billing becomes the QuickBooks shipping address (SHIP); every other address, including one marked both, becomes the billing address (BILL). Without this mapping, every address is written as the billing address. |
Field | Address1 | Line1 | Recommended. QuickBooks allows up to 500 characters per line. |
Field | Address2 | Line2 | Optional. When the address is sent and line 2 is empty, the QuickBooks line 2 is cleared. |
Field | Address3 | Line3 | Optional. QuickBooks address lines 4 and 5 cannot be mapped; an update keeps them. |
Field | City | City | Recommended. When the address is sent and the city is empty, the QuickBooks city is cleared. |
Field | Region | State | Recommended. Stored as sent (for example CA); it is not converted. |
Field | PostalCode | PostalCode | Recommended. When the address is sent and the postal code is empty, the QuickBooks postal code is cleared. |
Field | Country | Country | Optional. Stored as sent (for example US); QuickBooks keeps the country as free text. |
Address selection. Only the first address of each type that the transfer carries is written, and an address whose mapped fields are all empty is skipped. An address marked both primary billing and primary shipping is written as the billing address only, and the QuickBooks shipping address is left as it is. When a customer has several addresses that become billing addresses (for example a primary billing address and an address with neither flag), only the first one the transfer carries is written. Subscribers or their MiSP who need the primary billing address to win can add a filter to this collection that keeps only addresses marked primary billing or primary shipping, and should validate it in a staging environment before relying on it in production.
Error Handling
Errors appear in Dashboard / Integration Monitoring / Error Logs, and iPaaS.com retries an errored transfer automatically on a growing schedule. Customers skipped by the filter are not errors.
QBOL-VALD-1001 - A QuickBooks customer needs a display name, company name, first or last name, or email. Map at least one. The customer has no company, name or email value to name it by. Add one in iPaaS.com, or map one.
QBOL-BIZL-1001 - QuickBooks already has customer {id} ('{display name}') with this email or display name. Link it, or set the collection's collision handling to Remap and Link or Update and Link. The create found an existing QuickBooks customer and the Collision Handling Method is Error (or not set). Choose a linking method, or link the customer by hand, and send it again.
QBOL-BIZL-1002 - QuickBooks has {2 or 3 or more} customers with the email {email}: ... Several QuickBooks customers share the email, so nothing was written. Give each its own email, or link the iPaaS.com customer to the right one.
QBOL-EXTN-1010 (QuickBooks code 6240, duplicate name): the display name belongs to another customer, a vendor or an employee, and the customer has no email to make it unique. Change the company or name, or add an email.
QBOL-EXTN-1007 (QuickBooks code 2050, value too long): a value is longer than QuickBooks allows (see Field lengths). Shorten it in iPaaS.com.
QBOL-NFND-1003 - QuickBooks has no customer {id} to update (it may have been deleted). Remove the stale link in iPaaS.com and send the record again.
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.
If rate-limit errors continue for hours, or an error persists after the data is corrected, contact your MiSP or iPaaS.com Support.
Testing & Validation
Create an iPaaS.com customer with a first and last name, an email that QuickBooks does not have, and a primary billing address, and send it with Manual Sync. Confirm QuickBooks has a customer with the display name First Last, the email, and the billing address, and that the iPaaS.com customer now has the QuickBooks customer id as its external ID.
Change the customer's last name and city in iPaaS.com and send it again. Confirm the same QuickBooks customer is renamed and its billing city changes, and no second customer is created.
Create a second iPaaS.com customer whose email belongs to an existing QuickBooks customer, with the Collision Handling Method at its default. Confirm the transfer fails with QBOL-BIZL-1001 and nothing changes in QuickBooks. Set the method to Update and Link, send it again, and confirm the existing QuickBooks customer is linked and updated.
Create an iPaaS.com customer with the same first and last name as a QuickBooks vendor but its own email. Confirm QuickBooks creates the customer as First Last (email), and that a later update keeps that name.
Add an address marked primary shipping (and not primary billing) to the first customer and send it. Confirm it becomes the QuickBooks shipping address and the billing address is unchanged.
Additional Notes
Out of scope: deleting customers (map Active to false to deactivate one); QuickBooks customer custom fields; sub-customers and jobs (every customer is created as a top-level QuickBooks customer).
Known limitations: customers that share an email in QuickBooks cannot be matched by email; QuickBooks address lines 4 and 5 are kept on update but cannot be written, so when the street changes at the source, the old lines 4 and 5 stay until they are edited in QuickBooks. See QuickBooks Online Known Limitations.
Related Documents
Related Mapping Documentation