DECISIONLOG.md

Decision Log

Invoice Discounts Logic

The int_quickbooks__invoice_double_entry model has some unique logic to account for invoice discounts at the invoice line item level. These DiscountLineDetail invoice line detail types are handled differently from the normal SalesItemLineDetail lines. In the QuickBooks data for invoice lines these entries will not show up as a negative amount, but will instead be shown as a positive value that is to be discounted from the subtotal. As such, we do not want to add these discount lines to the total invoice cost. However, we still want to recognize them in the downstream general ledger models as they are contra revenue accounts that reduce the revenue accounts. Therefore, we need to take a different approach to debit and credit these discounts accordingly.

In particular, to handle these discounts we apply a debit to the discount_account_id (provided in the invoice line record) and a credit to the Accounts Receivable account. This is inherently different from the other behaviors of the invoice double entry model and it is handled accordingly with appropriate case when statements within the final cte.

As an example, if we have the following invoice with the relevant line items:

invoice_id	index	amount	detail_type	account_id	discount_account_id
1111	0	80000	SalesItemLineDetail	55
1111	1	32000	SalesItemLineDetail	55
1111	2	112000	SubTotalLineDetail
1111	3	14000	DiscountLineDetail		44

The corresponding entry that would result from the int_quickbooks__invoice_double_entry model would look like the following:

account_id	account_name	debit	credit
1	accounts receivable	32000
1	accounts receivable	80000
44	discount account	14000
1	accounts receivable		14000
55	cash account		80000
55	other cash account		32000

QuickBooks Cash Flow Type Logic

• In the int_quickbooks__cash_flow_classifications model, our default behavior is to classify the cash_flow_type based on the account_type, account_class or account_name fields of the balance sheet line. This logic was based on best available financial practices, with the cash flow being calculated using the indirect method rather than the direct method. Cash flow types usually fall into one of four buckets:

  • Operating: A measure of the amount of cash generated by a company's business operations. Account types like current assets & liabilities, accounts receivable & payable, credit card as well as account names like net income adjustment were assigned here by our default logic.
  • Investing: Any inflows or outflows of cash from a company's long-term investments. Account types like fixed and other assets end up here by default.
  • Financing: The movement of cash between a firm and its owners, investors, and creditors. Account types like long term liability and account classes like equity fall here under our logic.
  • Cash or Cash Equivalents: Line items that report value of a company's cash assets. Bank account types are assigned here.

• While the default case statement logic should work for many customers with basic setups, as customization gets more advanced for your specific business, this is not likely to cover all cases. This is why we created the seed functionality to allow you flexibility to adjust the cash flow types for your own custom purposes--you can read more about how to set it up in our README.

QuickBooks Financial Statement Ordinal Logic

• In the int_quickbooks__cash_flow_classifications and quickbooks__general_ledger_by_period models, we developed custom logic for ordering your financial models based on best known practices. In general, financial accounting statements have specific ordering that we've tried to preserve for balance sheets, profit and loss statements, and cash flow statements.

  • For the quickbooks__balance_sheet model, we order based on account_class: Asset, Liability, then Equity, in that order.
  • For the quickbooks__profit_and_loss model, we order based on account_class: Revenue, then Expense, in that order.
  • For the quickbooks__cash_flow_statement model, we order based on cash_flow_type: Operating, Investing, Financing, then Cash or Cash Equivalents, in that order.

• While the default case statement logic should work for many customers with basic setups, as customization gets more advanced for your specific business, this is not likely to cover all cases. This is why we created the seed functionality to allow you flexibility to adjust the ordering for your own custom purposes--you can read more about how to set it up in our README.

Accrual Basis Accounting Models

• There are two types of accounting methods - Accrual, which records revenue and expenses when transactions occur, but before money is received or dispensed. - Cash basis, which records revenue and expenses when cash related to transactions actually is received or dispensed.
• For our initial build of quickbooks__profit_and_loss, quickbooks__general_ledger_by_period, and quickbooks__balance_sheet, we used the accrual accounting method rather than cash, as it is approved by GAAP (generally accepted accounting principles). Accrual accounting requires companies match revenues with expenses incurred to generate them.
• If you'd like models that rely on the cash basis accounting, please comment on this feature and we can prioritize it for future development.

Multicurrency vs. Single Currency Configuration

We introduced multicurrency support in our v0.14.0 release. We introduced new fields to allow you the ability to pick and choose which amount, balance, and cash fields provide the most value to your end models.

These fields will be in the *_converted_* format of the original single currency amount/balance/cash fields. If you are a single currency customer, you should still leverage the original amount version of the fields.

Please leverage the below fields in your end models for your financial statements depending on what your currency configuration looks like.

Model	Multicurrency Fields	Single Currency Fields
quickbooks__general_ledger	adjusted_converted_amount, running_converted_balance	adjusted_amount, running_balance
quickbooks__general_ledger_by_period	period_net_converted_change, period_beginning_converted_balance, period_ending_converted_balance	period_net_change, period_beginning_balance, period_ending_balance
quickbooks__profit_and_loss	converted_amount	amount
quickbooks__balance_sheet	converted_amount	amount
quickbooks__cash_flow_statement	cash_converted_ending_period, cash_converted_beginning_period, cash_converted_net_period	cash_ending_period, cash_beginning_period, cash_net_period
quickbooks__ap_ar_enhanced	total_converted_amount, estimate_total_converted_amount, total_current_converted_payment	total_amount, estimate_total_amount, total_current_payment
quickbooks__expenses_sales_enhanced	total_converted_amount, converted_amount	total_amount, amount

Bringing in The Right Tax Accounts For Tax Lines

When bringing in tax lines (see the README for more details on how to enable/disable tax lines), we want to make sure we are associating each line with the right account, since they usually differ from the accounts for the regular lines. That way these lines are correctly tracked, generally as liabilities.

Our initial logic maps the tax agency display name by appending 'Payable' to the end of the name. That should ideally match one account name, which is the appropriate account for that tax line. Multiple tax accounts with the same name would cause fanout.

If tax agencies aren't where you want your mapping to take place, we then search for your default Sales Tax Payable and Global Tax Payable account available in your Quickbooks account. See this Quickbooks article for more details.

If neither of those accounts are available, the quickbooks__sales_tax_account_reference and quickbooks__global_tax_account_reference variables are made available to publish the account name you believe matches the tax line. See the README for more details.

This behavior pertains to the invoice, journal entry, refund receipt, and sales receipt tax line entries. (Purchase tax lines will be associated with their purchase accounts).

Designating a single Accounts Payable/Accounts Receivable account

The int_quickbooks__bill_payment_double_entry model requires a single account designated as 'Accounts Payable' per currency. Similarly, the int_quickbooks__invoice_double_entry, int_quickbooks__credit_memo_double_entry, and int_quickbooks__payment_double_entry models require a single account designated as 'Accounts Receivable' per currency. This aligns with QuickBooks Online requirements and accounting best practices. If you have multiple accounts designated as 'Accounts Payable' or 'Accounts Receivable' in the account_type field, all accounts will be brought into the join, causing data fanout. See example join logic here.

If it is absolutely necessary to have multiple accounts payable/receivable, a specific account can be designated for the join by configuring account type names, however we strongly recommend having a single AP/AR account per currency.