Summary
The Add/Update QuickBooks Online Item FROM iPaaS.com mapping collection creates and updates QuickBooks Online items from iPaaS.com products, so that products exist in QuickBooks before they are sold and keep their name, SKU, sales description, sales price and active state in step with iPaaS.com. Each product becomes one QuickBooks item; QuickBooks has no variants.
A product that is not linked to a QuickBooks item yet is first matched against the items already in QuickBooks, by SKU and then by name, so an existing item is not duplicated. A new item takes its type from the item type translation, or the Default Item Type setting when the type is blank, and its accounts from the Income Account, Expense Account and Inventory Asset Account settings. An update writes only the mapped values that have a value and never changes the item type. Quantities are never written to QuickBooks by this collection after an item is created.
ID Format
Manual Sync ID: the iPaaS.com product id, a number such as 100512.
External ID saved after sync: the QuickBooks item id, for example 41. After a successful create or link, iPaaS.com keeps it in an external-ID record for this subscription that links the product to its QuickBooks item, so later transfers of the same product update that item instead of creating another. Until that record exists, the integration matches an existing QuickBooks item by SKU and then by name, which is why the default template maps the product's Sku and Name; changing those mappings changes what an unlinked product can match.
Deleted Record Support
Not supported. QuickBooks Online never deletes items, and deleting a product in iPaaS.com does not delete or deactivate its QuickBooks item. To retire an item, give the product a status other than Active (for example Disabled or Discontinued): the Active mapping makes the QuickBooks item inactive, and an inactive item cannot be added to new transactions.
Mapping Collection Status
Status: Enabled.
Trigger events: the iPaaS.com product triggers product/created and product/updated. Whether a transfer creates or updates the QuickBooks item depends on whether the product is already linked by an external ID, not on which trigger fired.
Duplicate or Conflicting Mappings
These mapping collections also work with QuickBooks items or iPaaS.com products:
Add/Update QuickBooks Online Item TO iPaaS.com: creates and updates iPaaS.com products from QuickBooks items.
Add QuickBooks Online Sales Receipt FROM iPaaS.com and Add/Update QuickBooks Online Invoice FROM iPaaS.com: when a transaction line's SKU or name matches no QuickBooks item and the Create Missing Items setting is on, they create the item with the line's price and description, the Default Item Type and the Income Account. Such an item is not linked to its iPaaS.com product until Add/Update QuickBooks Online Item TO iPaaS.com links it by SKU, so if this collection sends that product first, the create matches the existing item and follows the Collision Handling Method.
Before enabling this collection alongside Add/Update QuickBooks Online Item TO iPaaS.com, decide which system is the source of truth for item names, SKUs, prices and descriptions, and review both collections' filters. With both directions active on the default mappings, a change in either system is sent to the other on its next transfer, and a change made in QuickBooks is overwritten the next time the product is sent FROM iPaaS.com.
Collision handling. The default template sets no Collision Handling Method on this collection. Set it on the mapping collection's settings page before the first transfer. It applies when a product that is not linked yet matches an existing QuickBooks item, active or inactive, by SKU or name:
Error (and no method set): the transfer fails with QBOL-BIZL-1004 naming the existing item's id, name and SKU, and nothing is created.
Remap and Link: the product is linked to the existing item, and iPaaS.com then updates that item with the mapped values. Linking rewrites the existing QuickBooks item's name, SKU, description, price and active state; its type is not changed.
Update and Link: the same result as Remap and Link: the product is linked and the existing item is updated with the mapped values.
Update and No Link: the existing item is updated with the mapped values, but no link is saved, so every later transfer of the product matches the item again.
A product whose SKU or name belongs to a QuickBooks Category or bundle (Group) item is never linked to it, under any method: the transfer fails with QBOL-BIZL-1005 naming the item and its type, and nothing is written. Rename the product or the QuickBooks category or bundle, then send the product again.
Supported Child Collections
None.
System Caveats
QuickBooks Online Caveats
Items are never deleted: QuickBooks Online only makes items inactive. Map Active and change the product status to retire an item.
Item type is set once: QuickBooks sets an item's type when it is created, and this collection never changes it on update. To change a NonInventory item into an Inventory item, do it in QuickBooks.
Unique names: QuickBooks item names must be unique among items, are limited to 100 characters (longer names are cut), and may not contain a colon, tab or line break. Inactive items still own their names and are still found by matching.
Rate limits: QuickBooks Online allows 500 requests a minute and 10 requests a second for each company and app. When the limit is reached, iPaaS.com holds the transfer and retries it 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
Retries: iPaaS.com retries every errored transfer automatically on a growing schedule. A product that cannot transfer, for example because an account setting names an account that does not exist, fails again on each retry until the setting, the product or the mapping is fixed.
Status drives active state: the product status, not a separate flag, decides whether the QuickBooks item is active. A product with the status Preorder makes its QuickBooks item inactive, like Disabled and Discontinued.
Prerequisite Handling
None. An item depends on no other record that this integration transfers first. Its accounts must already exist in the QuickBooks chart of accounts (see Setup Requirements).
Setup Requirements
iPaaS.com Configuration
Automatic transfers: these do not start by themselves. In the subscription configuration, open Outbound Data Flows and subscribe to the iPaaS.com product triggers product/created and product/updated. Until those subscriptions are enabled, no automatic transfers occur.
Collision Handling Method: set it on this mapping collection before the first transfer (see Duplicate or Conflicting Mappings).
Default Item Type: the type a new item takes when its mapped type is blank: NonInventory (the default) or Service.
Income Account: the income account for a new item whose account is not mapped (default Sales of Product Income). Every new item uses it.
Expense Account and Inventory Asset Account: the cost of goods sold and inventory asset accounts for a new Inventory item (defaults Cost of Goods Sold and Inventory Asset). Other item types do not use them.
Each account setting must name an account (or sub-account, written as Parent:Child, for example Income:Sales) or hold an account id that exists in the QuickBooks chart of accounts, or the create fails with an error naming the setting.
Item type translation: review QuickBooks Online Item Type FROM iPaaS.com and add a row for every iPaaS.com product type in use (see Mappings).
QuickBooks Online Configuration
Make sure the accounts named in the three account settings exist in the chart of accounts.
Inventory items need QuickBooks inventory tracking: included in Plus and Advanced, an add-on for Simple Start and Essentials.
Keep product names and SKUs different from the names of QuickBooks categories and bundles.
Integration Flow
A product/created or product/updated trigger, or Manual Sync with the iPaaS.com product id, starts the transfer.
The filter keeps only products that have a SKU.
Linked product: the integration reads the current QuickBooks item and updates it with only the mapped values that have a value. The item type is never changed. A value that is missing altogether leaves the QuickBooks value as it is, including the name; an empty text value in any other field is sent and clears that QuickBooks field.
Product not linked yet: the integration looks for an existing QuickBooks item, active or inactive, with the same SKU, and then with the same name. A match on a category or bundle fails with QBOL-BIZL-1005; any other match follows the Collision Handling Method.
No match: the integration resolves the item's accounts by name or id and creates the item with its type. An Inventory item is created with quantity tracking on, a start quantity and a start date. A create retried after a lost response returns the item QuickBooks created the first time instead of creating a second one.
iPaaS.com saves the QuickBooks item id as the product's external ID.
Mappings
Add/Update QuickBooks Online Item FROM iPaaS.com
iPaaS.com data type: Product
Mapping Filter
// Products with a SKU. return Sku != null;
Filter Description. Only iPaaS.com products that have a SKU are processed; products without a SKU are skipped without an error. The filter does not check the product status, so a product whose status is not Active is still sent and makes its QuickBooks item inactive.
Mapping Type | Source Field (iPaaS.com) | Destination Field (QuickBooks Online) | Description |
Field | Name | Name | Required. The product name becomes the QuickBooks item name: unique among items, up to 100 characters (longer names are cut). It is the second key a new item is matched on. When the name is blank, a new item is named after its SKU and an update keeps the existing QuickBooks name. |
Field | Sku | Sku | Required. The product SKU becomes the QuickBooks item SKU (up to 100 characters). The filter only sends products with a SKU, and the SKU is the first key a new item is matched on. |
Translation | Type (translation QuickBooks Online Item Type FROM iPaaS.com) | Type | Translates the iPaaS.com product type to a QuickBooks item type, set only when the item is created. Recommended: when it is blank, a new item uses the Default Item Type setting. Allowed QuickBooks values: Inventory, NonInventory, Service; any other value fails the transfer. |
Field | Description | Description | The product description becomes the item's sales description, shown on sales forms (up to 4,000 characters). Recommended. A missing description leaves the QuickBooks description as it is; an empty text value clears it. |
Field | DefaultPrice | UnitPrice | The product's default price becomes the item's sales price, which QuickBooks offers when the item is added to a sale. Recommended. An empty price leaves the QuickBooks price as it is. |
Dynamic Formula |
| Active | A product with the status Active makes an active item; any other status (Disabled, Discontinued or Preorder) makes the item inactive. Recommended: it is how a product retired in iPaaS.com is retired in QuickBooks. |
Item Type Translation Values
The Type mapping uses the translation QuickBooks Online Item Type FROM iPaaS.com, which ships with these rows:
iPaaS.com product type | QuickBooks item type |
Service Items | Service |
Non-Inventory Items | NonInventory |
Virtual | Service |
Physical | NonInventory |
Physical becomes NonInventory, and the Default Item Type setting offers only NonInventory and Service, so this collection creates Inventory items only when subscribers or their MiSP map a type of Inventory on purpose, for example by changing the translation's Physical row to Inventory. Add a row for every iPaaS.com product type in use, and validate any type without a row in a staging environment before relying on it in production.
Inventory Items
An Inventory item needs:
Accounts: an income account, a cost of goods sold (expense) account and an inventory asset account. When the item's account fields are not mapped, the Income Account, Expense Account and Inventory Asset Account settings are used.
A start quantity: the quantity on hand on the start date, from a mapped QtyOnHand, otherwise 0. After the item is created, its quantity changes only in QuickBooks, through sales and inventory adjustments; this collection never updates it.
A start date: from a mapped InventoryStartDate (format yyyy-MM-dd), otherwise today's date in Coordinated Universal Time (UTC). For a US company, the UTC date is already tomorrow during the local evening, so an item created then starts tomorrow, and a sale dated today on that item can be refused by QuickBooks because it is dated before the item's start date. To avoid it, map InventoryStartDate to a date on or before the earliest sale the item can have: for example a Static value of a past date such as 2026-01-01. Validate the mapping 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. Full messages are in QuickBooks Online Error Messages.
QBOL-BIZL-1004: QuickBooks already has an item with this SKU or name, and the collection's Collision Handling Method is Error or not set. Link the existing item, or set the method to Remap and Link or Update and Link.
QBOL-BIZL-1005: the product's SKU or name belongs to a QuickBooks category or bundle, which cannot be linked. Rename the product or the category or bundle, then resend.
QBOL-VALD-1005: the item's type is not Inventory, NonInventory or Service. Add a row to the item type translation.
QBOL-VALD-1006: the product has neither a name nor a SKU to name a new item by.
QBOL-VALD-1007: the product's external ID is not a QuickBooks item id (for example it was edited by hand). Check the product's external ID in iPaaS.com.
QBOL-NFND-1005: an account setting, or the item's mapped account, names an account QuickBooks does not have. Set it to an account name or id from your chart of accounts.
QBOL-EXTN-1010 (code 6240): QuickBooks refused a duplicate item name. Make the name unique, or link the existing item, then resend.
QBOL-EXTN-1013: QuickBooks limited the request rate; iPaaS.com retries after a minute.
Connection errors (QBOL-AUTH codes) are also covered in QuickBooks Online Error Messages.
Testing & Validation
Set the Collision Handling Method to Error. Create a product in iPaaS.com with a SKU, a name, the type Service Items, a description and a default price, and transfer it with Manual Sync. Confirm QuickBooks has a Service item with the same name, SKU, description and sales price, and that the product now carries the QuickBooks item id as its external ID.
Change the product's price and description and transfer it again. Confirm the same QuickBooks item is updated and no new item is created.
Create a second product whose SKU matches an existing QuickBooks item and transfer it. Confirm it fails with QBOL-BIZL-1004. Set the method to Update and Link, resend, and confirm the existing item is linked and updated.
Set a product's status to Discontinued and transfer it. Confirm the QuickBooks item is inactive.
Transfer a product whose name matches a QuickBooks category. Confirm it fails with QBOL-BIZL-1005 and nothing is written.
Additional Notes
Out of scope: deleting items (deleting a product does not delete or deactivate the QuickBooks item); writing quantities to QuickBooks, apart from an Inventory item's start quantity at creation; variants, categories and bundles (this collection creates Inventory, NonInventory and Service items only).
Known limitations: a product whose SKU or name belongs to a QuickBooks category or bundle fails with QBOL-BIZL-1005 until one of them is renamed; changes made to the item in QuickBooks (name, SKU, description, price, active state) are overwritten the next time the product is sent FROM iPaaS.com. See QuickBooks Online Known Limitations.
Related Documents
Related Mapping Documentation