Overview of the Invoice Pushing Process
When invoices are pushed from Luminous to QuickBooks, the system performs a series of organized steps to ensure data consistency and proper mapping between the two platforms. This article explains the behind-the-scenes process to help support representatives understand how the integration works.
Data Source for QuickBooks Invoices
The integration uses data from the line item table in our database as the primary source for line items in QuickBooks invoices. This table contains detailed information about each order item, including:
SKU information
Product names
Quantities
Unit prices
Line item descriptions
Product relationships to other system entities
When an invoice is generated for QuickBooks, the system reads from this table to create properly formatted line items for the QuickBooks invoice.
Product Existence Verification Process
Before creating a new product in QuickBooks, the system follows a careful verification process:
SKU Verification: The system first searches QuickBooks for an existing product with the same SKU. This search is case-insensitive to avoid duplication due to capitalization differences.
Name Verification: If no match is found by SKU, the system performs a second check using the product name.
Caching Mechanism: To optimize performance and reduce unnecessary API calls, the system caches QuickBooks product information for a week. This means that once a product has been found or created in QuickBooks, the system can quickly reference it for future invoices without repeatedly checking QuickBooks.
Product Creation in QuickBooks
Only when both verification steps fail (no matching SKU or name), the system will create a new product in QuickBooks with the following attributes:
Product Type: The item is created as a "NonInventory" type in QuickBooks
Product Name: Formatted with the SKU in brackets followed by the product name
Product Details: Includes product description, unit price and SKU
Accounting References: Properly mapped to the appropriate income and expense accounts in QuickBooks
Invoice Structure in QuickBooks
The QuickBooks invoice created by Luminous has several component sections:
Header Information: Customer details, invoice date, shipping information, and invoice number
Line Items: Individual products with quantity, price, and descriptions
Subtotal Calculation: An explicit subtotal line that summarizes all product line items
Discount Line: If applicable, showing any discounts applied to the order
Shipping Line: When enabled in settings, this shows shipping charges
Tax Details: Proper tax codes applied based on product tax categories or global settings
Handling Special Cases
The integration handles several special scenarios:
Tax Code Application: Products can have specific tax codes, or a system-wide default tax code can be applied
Customer Creation: If a customer doesn't exist in QuickBooks, the system can create a new customer record
Payments Sync: Payments made in Luminous can be synchronized to QuickBooks
Error Handling: When API issues occur, the system has retry mechanisms and detailed error logging
Best Practices for Support
When assisting users with QuickBooks integration:
SKU Consistency: Advise users to maintain consistent SKUs between systems to prevent duplicate product creation
Invoice Numbering: Explain how the QuickBooks invoice numbers are generated with configurable prefixes
Tax Configuration: Help users set up the correct tax codes in QuickBooks for proper tax handling
Integration Settings: Guide users through the QuickBooks integration settings that control behaviors like shipping line items or tax handling
This overview should help support representatives understand the flow of data between Luminous and QuickBooks, particularly focusing on how products are verified before creating new ones in the QuickBooks system.