QuickBooks Integration Setup

this document details the steps required to set up quickbooks and nue to prepare for the following quickbooks integration collect payments via quickbooks docid\ e6resganksuoeja6stqmf nue's billing accelerator simplifies the invoicing and collection workflow for businesses by seamlessly integrating with quickbooks by effortlessly generating invoices from orders and smoothly transferring them to quickbooks for payment processing, nue ensures a streamlined experience when customers settle their invoices via quickbooks, either by using payment or applying credit memo, nue automatically updates the corresponding invoice, marking the balance as paid this powerful integration between nue and quickbooks presents businesses with an efficient and hassle free billing solution, empowering them to effectively manage their finances permissions required please enable the following permissions in the user role integrations manage quickbooks integration collections view payment application manage payment application system settings manage events and webhooks docid 2ec0ab583e2a6b23f44f93add56747ed3b4b2d91 setup connection please follow the steps below to setup connections to quickbooks navigate to nue > settings (via the gear at the top right corner of the dashboard) in the search box, search for quickbooks integration navigate to the quickbooks integration setup page click on 'new integration' button, and then input your "environment" input an "integration name" click "save and next" setting up your integration use case upon clicking "save and next", you will be brought to the integration use case page if you check "payments and collections" it will enable the payments integration as explained on this page collect payments via quickbooks if you leave it unchecked, it would mean that you are using the default quickbooks integration solely for accounting (and collecting elsewhere) as detailed in this page manage accounting via quickbooks inputting your quickbooks configuration next, you will enter the main quickbooks configuration page this page is where you setup the main configuration variables to connect to your quickbooks instance to begin, copy the auto generated "quickbooks triggered events public url" by clicking on the "copy to clipboard" button located on the right hand side of the input field next, paste the url into your quickbooks webhooks settings page you can access this page by navigating from your dashboard https //developer intuit com/app/developer/dashboard to my hub in the upper right corner from there, proceed to workspaces, select the workspace associated with your app (for example, sample workspace), and then locate the app within the workspace once you are in this section, you will find the option to navigate to "webhooks" in the left side panel 3\ next, create nue authentication by inputing a nue api key 4\ create an authenticaticated quickbooks instance by inputing quickbooks username and password in "connect to your quickbooks" section 5\ input your company id this is found by navigating to your quickbooks instance from my hub > sandboxes clicking on the sandbox company will open up your quickbooks online instance 6\ at this point, you can click " finish " as all other fields are optional for all other configuration inputs, please navigate to additional configuration in order to ensure you are mapping correctly to your quickbooks gl, please navigate to gl account configuration upon succesful activation, you will see your list of active and draft integrations in the quickbooks setup page enabling your quickbooks webhook note to enable the quickbooks webhook, the quickbooks app which contains the webhook settings, is required to authorize the quickbooks account otherwise, nue will not receieve any payment messages from quickbooks you can copy and paste the following url to your web browser and process the app authentication (don't forget replace your client id, your redirect uri, your unique state) https //appcenter intuit com/connect/oauth2?client id=your client id\&redirect uri=your redirect uri\&scope=com intuit quickbooks accounting\&response type=code\&state=your unique state your client id you can find it in the same page when you configured webhook, dashboard > select / create an app > production settings > keys & credentials your redirect uri any redirect uri in "keys & credentials > redirect uris section" is ok, e g https //developer intuit com/v2/oauth2playground/redirecturl https //developer intuit com/v2/oauth2playground/redirecturl your unique state any state code is ok, e g arandomstatecode if the authentication url is configured well, you will see a authentication page like this, click 'connect' will jump to the redirect uri you set into the url, which means the authentication is working now the final step of the setup includes ensuring that the webhook events in the quickbooks webhook you have set up are listening to the correct nue webhook events following the instructions on how to work with nue webhooks , please ensure the following webhook events are enabled depending on your integration use case if you are using quickbooks for payments, the following webhook events should be chosen credit memo activated credit memo applied credit memo canceled invoice activated invoice canceled if you are using quickbooks for accounting, the following webhook events should be chosen credit memo activated credit memo applied credit memo canceled invoice activated invoice canceled invoice refund processed this will ensure refunds processed through nue are received by quickbooks invoice payment processed this will ensure payments processed through nue or another collection system are received by quickbooks additional configuration quickbooks transaction field mapping documentation this documentation explains how the nue quickbooks integration supports various transaction field mappings, allowing flexible and granular data syncing between nue and your quickbooks online (qbo) instance the configuration includes options for standard and custom transaction fields, line item configuration, line item description concatenation, and payment term mapping 1\ transaction standard fields mapping purpose to map standard fields from nue (or salesforce) invoices and credit memos to their equivalent standard fields in quickbooks setup & example go to nue settings > quickbooks integration under field mapping, click add property to target enter the api name of the nue field as the source source fields use the api name shown in nue settings > business object > invoice/credit memo for the target, enter the standard qbo field name (as listed in qbo api explorer) example mapping nue field qbo field docnumber docnumber duedate duedate invoicedate txndate you can find a full list of default mappings in the nue knowledge center 2\ transaction custom fields mapping purpose to map custom fields from nue invoices/credit memos to custom fields in qbo, such as custom po numbers, special instructions, contract ids, etc setup & example qbo custom fields must be created in your qbo company and have a unique definitionid go to nue settings > quickbooks integration and add a custom mapping source nue field api name target qbo custom field's definitionid (and type if needed) example schema type suffix support (optional) string "1\ string" boolean "2\ boolean" date "3\ date" only invoices and credit memos support custom field mapping invoice lines do not support custom fields at this time 3\ transaction line standard fields mapping purpose to map standard nue line item fields (from invoice line items or credit memo lines) to qbo standard fields on the invoice line/transaction line object supported mappings nue line item field qbo line field startdate salesitemlinedetail servicedate transactionquantity salesitemlinedetail qty productid salesitemlinedetail itemref value (id) transactionamountwithouttax amount description description example mapping configuration note for detailed field names and target mapping, refer to the qbo api explorer and the nue docs 4\ transaction line description fields mapping purpose to build dynamic descriptions for qbo line items by concatenating values from one or more nue fields typical use displaying period start and end dates, asset info, or custom details on each qbo invoice item how it works you define a mapping in nue settings where each key is a nue field, and each value is the label to show in qbo description the qbo line item `description` field will be composed as \<description/name> | \<label 1> \<value 1> | \<label 2> \<value 2> if no mappings, the default product description is sent config example result in qbo description you may optionally leave out certain fields to adjust formatting this method supports both invoice and credit memo line items custom field mapping on line items is not currently supported for qbo (only header level custom fields are supported) 5\ payment term mapping purpose map the payment term field from nue to quickbooks to ensure the correct net terms (e g , net 15, net 30, due upon receipt) are set on customers/invoices behavior when creating a customer or invoice in qbo, the integration queries all available payment terms in qbo it attempts to align the customer or invoice payment term with the name/value in nue if a match is found, qbo term is set by id example nue payment term "net 30" → quickbooks term "net 30" if no payment term exists in nue, no term is assigned in qbo (defaults in quickbooks may apply) for invoices, if both customer and order have terms, customer’s value is prioritized unless configured otherwise (see related jira/bugs for quote/order vs customer confusion) common issues and best practices name matching make sure the payment term value in nue matches exactly (case/spacing) to the qbo term custom terms if you have a custom term not present in qbo, either add it to qbo or create a mapping/config override error handling if the desired term cannot be set, the invoice/customer will be created without a payment term—this is surfaced in qbo and transaction hub known edge cases "due upon receipt" requires explicit mapping/config since qbo may use a slightly different name ("due on receipt") an error is logged if no match is found if customer payment term and order/quote payment term differ, by default, the customer’s term wins on invoice creation unless logic is overridden 6\ invoice email settings purpose configures whether invoices synced to quickbooks online should be automatically sent via email to the customer allows for customization of the invoice delivery process from nue to qbo configuration & options the field is required in the quickbooks integration and offers control over invoice delivery workflows available settings typically include "save only" create the invoice in qbo but do not send an email "save and send" create the invoice and send to the customer’s email listed in qbo "save and close" (if supported) save and mark as closed, without email notification how to set up in nue quickbooks integration settings, select your desired email behavior for invoices using the dropdown the value must match one of the supported actions in qbo if an unsupported value is used, invoice creation may fail or ignore the setting example configuration notes when "save and send" is selected, qbo uses the customer’s primary email from the qbo record; ensure it is correct and up to date this setting typically applies only to invoice records, not credit memos or other transaction types best practices review automated email templates in qbo to ensure customers receive the intended message confirm customer contact information before enabling automatic sending limitations if customer email is not present in qbo, the invoice is created but may not be sent mass sending is subject to qbo limits/policies (see quickbooks documentation for caps and spam prevention) additional key points product sku field mapping as of release 2505, you can map product sku from nue to the qbo product sku field when syncing products to qbo field mapping types string (default), boolean, date — optionally provided as a suffix in config for custom fields no line custom fields qbo does not support custom fields for invoice lines via api; any extra details required should be included in the line description field metadata ensure that field metadata from salesforce is properly synced to nue before setting up any mappings always use field/definition api names not user facing labels gl account configuration multi currency in quickbooks setup requirements before enabling this feature, ensure multi currency is enabled in both salesforce and quickbooks the checkbox use nue customer currency is selected in the nue configuration customers and their corresponding currencies are correctly set in salesforce how it works example 1 invoicing a customer in gbp create a salesforce customer set currencyisocode = gbp nue sends the customer to quickbooks when use nue customer currency = true, nue includes currencyref = gbp in the qbo payload quickbooks creates or reuses a gbp customer if a gbp version of the customer doesn’t exist, nue creates one otherwise, it reuses the existing gbp customer invoice is synced to qbo in gbp nue sends the invoice to the gbp specific customer in qbo note if the currency is not specified, qbo defaults to the company’s base currency ⚠️ quickbooks limitation quickbooks does not allow a single customer to have invoices in multiple currencies to support this, nue creates separate customer records for each currency, mirroring the behavior of our netsuite integration incorrect currency setup if use nue customer currency is disabled or salesforce/qbo are not properly configured for multi currency, qbo will default to the company’s base currency, which may cause reporting or revenue issues example scenarios scenario expected outcome use nue customer currency = false send usd customer/invoice to usd quickbooks customer created in usd invoice created in usd use nue customer currency = false send gbp customer/invoice to usd quickbooks customer created in usd (since boolean is false) invoice created in usd use nue customer currency = true send gbp customer/invoice to usd quickbooks customer created in gbp invoice created in gbp use nue customer currency = true send usd customer/invoice to usd quickbooks customer created in usd invoice created in usd docid 2ec0ab583e2a6b23f44f93add56747ed3b4b2d91 map existing quickbooks customers and products with nue this step is necessary if you already have an existing quickbooks instance and want to link the customers/products in your quickbooks instance to nue before creating a new transaction in quickbooks, nue verifies if the associated customer or product already exists in quickbooks if the customer or product record does not exist, a new one is created it is crucial to use the mapping feature to clearly define the mapping relationship in quickbooks docid 2ec0ab583e2a6b23f44f93add56747ed3b4b2d91 prepare mapping data exports accounts and products from salesforce in this step, we will export salesforce accounts using dataload io provided by salesforce login to salesforce and navigate to setup search dataloader io in quick find and click to launch dataloader io login to dataloader io with salesforce click 'new export task' and select “account“/product object with “account id“/"product id" and “account name“/"product name", click save & run click to download the export file query customers and products from quickbooks via api you can use the following quickbooks api to query the customers and products ("items") data get https //quickbooks api intuit com/v3/company/{reamid}/query?minorversion={minorversion} content type\ text/plain production base url\ https //quickbooks api intuit com sandbox base url\ https //sandbox quickbooks api intuit com sample query for customers select c id,c displayname from customer c order by displayname sample query for products select i id, i name from item i order by name for more information about quickbooks query api, please checkout quickbooks api documentation https //developer intuit com/app/developer/qbo/docs/api/accounting/most commonly used/account#query an account create mapping file first, please download the customer and product mapping csv template by following the steps below login to nue, and navigate to system settings https //app nue io/settings search settings "quickbooks integration" click the 'import mapping' button, and click 'download template' in the template, insert the data using the data exported from salesforce and quickbooks to create the customers and products mapping after the mapping is complete, save it as a csv file salesforce accountid salesforce accountname quickbooks customername quickbooks customerid 00dn0000000ynvcmas nue io nue 237 salesforce productid salesforce productname quickbooks productname quickbooks productid 00dn0000000ynvcmas nue on salesforce nue on salesforce 8512 docid 2ec0ab583e2a6b23f44f93add56747ed3b4b2d91 import mapping file click the 'import' button to import the csv mapping files if there are errors, you will see an error link where you can download the error csv file you can correct the error and re import the csv file map field field mapping is the process of aligning fields from nue to corresponding fields in quickbooks, ensuring accurate data transfer and integration between systems currently, invoices and credit memos support the mapping field there are three supported mappings transaction standard fields mapping use this if you want to map a quickbooks invoice/credit memo standard field transaction custom fields mapping use this if you want to map a quickbooks invoice/credit memo custom field transaction line standard fields mapping use this if you want to map an invoice item/ credit memo item standard field to quickbooks in nue settings > quickbooks integration click on the "add property to target" button to create a mapping in the new property popup, enter the api name of the salesforce/nue field click save for source fields, use the name from nue settings > business object > invoice for target it should be for quickbooks custom field should be the definition id to get the id of a custom field in quickbooks, query a sample record (e g , invoice) it should show the definitionid of the custom field in the result (sample query select from invoice order by id desc maxresults 1 ) for quickbooks standard fields it should just be the queried name from api explorer query qbo fields jpg