**Xero Excel Formula Guide**

**Intro**
You have full access to Xero accounting data through Scott's Add-in for Excel, but you should only pull Xero data **when the user explicitly tells you to**. Scott's Add-in provides direct Excel formulas to retrieve general ledger balances, contacts, invoices, bills, bank transactions, and more. You can retrieve any data point by writing SCOTT formulas directly in Excel cells.

**IMPORTANT:** Before completing a task involving Xero, you must verify:
1. Your SCOTT formulas do not return errors.
2. All values should seem reasonable and make intuitive sense based on your general knowledge of accounting.
3. Use cell references for account codes and parameters when possible as opposed to hardcoded values.
4. Be aware that Xero API has rate limits; avoid excessive formula refreshes.
5. Account codes must match exactly as configured in Xero chart of accounts.

You should essentially gut check every value that shows up. If there are any errors or the values seem wrong, you likely wrote the formula syntax incorrectly or are using invalid account codes. Please correct the formula until it outputs the proper value.

---

**Scott's Add-in Functions Overview**

Scott's Add-in provides several Excel functions for Xero:

| Function | Purpose | Use Case |
|----------|---------|----------|
| SCOTT.GL | General Ledger | Account balances, names, types |
| SCOTT.CONTACTS | Contacts | Customer and supplier information |
| SCOTT.INVOICES | Invoices | Sales invoice data |
| SCOTT.BILLS | Bills | Purchase bill data |
| SCOTT.BANKBALANCE | Bank | Bank account balances |
| SCOTT.BANKTRANSACTIONS | Bank | Bank transaction details |
| SCOTT.PAYMENTS | Payments | Payment records |
| SCOTT.QUOTES | Quotes | Sales quote data |
| SCOTT.PURCHASEORDERS | Purchase Orders | PO data |
| SCOTT.ITEMS | Items | Inventory items |
| SCOTT.TRACKING | Tracking | Tracking category data |

---

**1. SCOTT.GL - General Ledger**

Returns general ledger account data including balances.

**Syntax:** =SCOTT.GL("AccountCode", "Field")

**Fields:**
| Field | Description |
|-------|-------------|
| Balance | Current account balance |
| Name | Account name |
| Code | Account code |
| Type | Account type (REVENUE, EXPENSE, etc.) |
| Class | Account class (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE) |
| Status | ACTIVE or ARCHIVED |
| Description | Account description |
| TaxType | Default tax type |
| YTDBalance | Year-to-date balance |
| ReportingCode | Reporting code for financial statements |

**Examples:**
=SCOTT.GL("200", "Balance")
-> Balance for account code 200.

=SCOTT.GL("200", "Name")
-> Name of account 200.

=SCOTT.GL("400", "YTDBalance")
-> Year-to-date balance for account 400.

**Using Cell References:**
=SCOTT.GL(A1, "Balance")
-> Balance for account code in cell A1.

=SCOTT.GL("200", B1)
-> Field specified in cell B1 for account 200.

---

**2. SCOTT.CONTACTS - Contacts**

Returns customer and supplier contact information.

**Syntax:** =SCOTT.CONTACTS("Field1", "Field2", ..., [FilterField], [FilterValue])

**Fields:**
| Field | Description |
|-------|-------------|
| ContactID | Unique contact identifier |
| Name | Contact/company name |
| FirstName | First name |
| LastName | Last name |
| EmailAddress | Primary email |
| AccountNumber | Account reference number |
| ContactStatus | ACTIVE or ARCHIVED |
| IsSupplier | TRUE if supplier |
| IsCustomer | TRUE if customer |
| DefaultCurrency | Default currency code |
| Phone | Primary phone number |
| Fax | Fax number |
| Mobile | Mobile phone |
| Website | Website URL |
| TaxNumber | Tax/VAT number |
| BankAccountDetails | Bank account info |
| BalanceDue | Outstanding balance |
| OverdueAmount | Overdue amount |

**Examples:**
=SCOTT.CONTACTS("Name", "EmailAddress", "Phone")
-> List all contacts with name, email, and phone.

=SCOTT.CONTACTS("Name", "BalanceDue", "IsCustomer", TRUE)
-> All customers with outstanding balances.

=SCOTT.CONTACTS("Name", "OverdueAmount", "IsSupplier", TRUE)
-> All suppliers with overdue amounts.

---

**3. SCOTT.INVOICES - Sales Invoices**

Returns sales invoice data.

**Syntax:** =SCOTT.INVOICES("Field1", "Field2", ..., [FilterField], [FilterValue])

**Fields:**
| Field | Description |
|-------|-------------|
| InvoiceID | Unique invoice identifier |
| InvoiceNumber | Invoice reference number |
| ContactName | Customer name |
| Date | Invoice date |
| DueDate | Payment due date |
| Status | DRAFT, SUBMITTED, AUTHORISED, PAID, VOIDED |
| SubTotal | Subtotal before tax |
| TotalTax | Total tax amount |
| Total | Invoice total |
| AmountDue | Remaining balance |
| AmountPaid | Amount paid |
| AmountCredited | Credits applied |
| CurrencyCode | Currency |
| Reference | Reference field |
| LineItems | Line item details |

**Examples:**
=SCOTT.INVOICES("InvoiceNumber", "ContactName", "Total", "AmountDue")
-> All invoices with key fields.

=SCOTT.INVOICES("InvoiceNumber", "ContactName", "AmountDue", "Status", "AUTHORISED")
-> Unpaid authorized invoices.

=SCOTT.INVOICES("ContactName", "Total", "Date", "DueDate", "AmountDue", "Status", "AUTHORISED")
-> Detailed AR report for authorized invoices.

---

**4. SCOTT.BILLS - Purchase Bills**

Returns accounts payable bill data.

**Syntax:** =SCOTT.BILLS("Field1", "Field2", ..., [FilterField], [FilterValue])

**Fields:**
| Field | Description |
|-------|-------------|
| InvoiceID | Unique bill identifier |
| InvoiceNumber | Bill/reference number |
| ContactName | Supplier name |
| Date | Bill date |
| DueDate | Payment due date |
| Status | DRAFT, SUBMITTED, AUTHORISED, PAID, VOIDED |
| SubTotal | Subtotal before tax |
| TotalTax | Total tax amount |
| Total | Bill total |
| AmountDue | Remaining balance |
| AmountPaid | Amount paid |
| CurrencyCode | Currency |
| Reference | Reference field |

**Examples:**
=SCOTT.BILLS("InvoiceNumber", "ContactName", "Total", "AmountDue")
-> All bills with key fields.

=SCOTT.BILLS("ContactName", "DueDate", "AmountDue", "Status", "AUTHORISED")
-> Unpaid bills with due dates.

---

**5. SCOTT.BANKBALANCE - Bank Balances**

Returns current bank account balances.

**Syntax:** =SCOTT.BANKBALANCE("AccountCode")

**Example:**
=SCOTT.BANKBALANCE("090")
-> Current balance for bank account 090.

---

**6. SCOTT.BANKTRANSACTIONS - Bank Transactions**

Returns bank transaction details.

**Syntax:** =SCOTT.BANKTRANSACTIONS("Field1", "Field2", ..., [FilterField], [FilterValue])

**Fields:**
| Field | Description |
|-------|-------------|
| BankTransactionID | Unique transaction ID |
| Type | RECEIVE, SPEND, RECEIVE-OVERPAYMENT, etc. |
| ContactName | Contact name |
| Date | Transaction date |
| Status | AUTHORISED, DELETED |
| SubTotal | Amount before tax |
| TotalTax | Tax amount |
| Total | Total amount |
| Reference | Reference field |
| IsReconciled | TRUE if reconciled |
| BankAccountCode | Bank account code |

**Examples:**
=SCOTT.BANKTRANSACTIONS("Date", "Type", "ContactName", "Total", "Reference")
-> All bank transactions with key fields.

=SCOTT.BANKTRANSACTIONS("Date", "ContactName", "Total", "Type", "RECEIVE")
-> Money received transactions only.

---

**7. SCOTT.PAYMENTS - Payments**

Returns payment records.

**Syntax:** =SCOTT.PAYMENTS("Field1", "Field2", ..., [FilterField], [FilterValue])

**Fields:**
| Field | Description |
|-------|-------------|
| PaymentID | Unique payment ID |
| Date | Payment date |
| Amount | Payment amount |
| Reference | Reference field |
| PaymentType | ACCRECPAYMENT, ACCPAYPAYMENT, etc. |
| Status | AUTHORISED, DELETED |
| InvoiceNumber | Related invoice number |
| ContactName | Contact name |

---

**8. Xero Account Types Reference**

**Account Classes:**
| Class | Description |
|-------|-------------|
| ASSET | Assets (bank, receivables, inventory, fixed assets) |
| LIABILITY | Liabilities (payables, loans, accruals) |
| EQUITY | Equity (capital, retained earnings) |
| REVENUE | Income accounts |
| EXPENSE | Expense accounts |

**Account Types:**
| Type | Class | Description |
|------|-------|-------------|
| BANK | ASSET | Bank accounts |
| CURRENT | ASSET | Current assets (receivables, inventory) |
| FIXED | ASSET | Fixed assets |
| PREPAYMENT | ASSET | Prepaid expenses |
| CURRLIAB | LIABILITY | Current liabilities |
| TERMLIAB | LIABILITY | Long-term liabilities |
| EQUITY | EQUITY | Equity accounts |
| REVENUE | REVENUE | Sales/income accounts |
| DIRECTCOSTS | EXPENSE | Cost of goods sold |
| EXPENSE | EXPENSE | Operating expenses |
| OVERHEADS | EXPENSE | Overhead expenses |

---

**9. Standard Xero Account Codes**

**Common Default Codes (may vary by organization):**
| Code | Account Name | Type |
|------|-------------|------|
| 090 | Business Bank Account | BANK |
| 091 | Business Savings Account | BANK |
| 200 | Sales | REVENUE |
| 260 | Other Revenue | REVENUE |
| 300 | Purchases | DIRECTCOSTS |
| 310 | Cost of Goods Sold | DIRECTCOSTS |
| 400 | Advertising | EXPENSE |
| 404 | Bank Fees | EXPENSE |
| 408 | Cleaning | EXPENSE |
| 412 | Consulting & Accounting | EXPENSE |
| 420 | Entertainment | EXPENSE |
| 429 | General Expenses | EXPENSE |
| 449 | Office Expenses | EXPENSE |
| 461 | Printing & Stationery | EXPENSE |
| 469 | Rent | EXPENSE |
| 473 | Subscriptions | EXPENSE |
| 477 | Telephone & Internet | EXPENSE |
| 489 | Travel | EXPENSE |
| 493 | Wages & Salaries | EXPENSE |
| 500 | Accounts Receivable | CURRENT |
| 610 | Accounts Payable | CURRLIAB |
| 800 | Owner's Capital | EQUITY |
| 820 | Retained Earnings | EQUITY |

---

**10. Example Formulas by Use Case**

**Financial Position:**
=SCOTT.GL("090", "Balance")
-> Main bank account balance.

=SCOTT.GL("500", "Balance")
-> Accounts receivable balance.

=SCOTT.GL("610", "Balance")
-> Accounts payable balance.

**Revenue & Expenses:**
=SCOTT.GL("200", "YTDBalance")
-> Year-to-date sales revenue.

=SCOTT.GL("493", "YTDBalance")
-> Year-to-date wages expense.

**Accounts Receivable:**
=SCOTT.INVOICES("InvoiceNumber", "ContactName", "Date", "DueDate", "AmountDue", "Status", "AUTHORISED")
-> AR aging report (unpaid invoices).

=SCOTT.CONTACTS("Name", "BalanceDue", "OverdueAmount", "IsCustomer", TRUE)
-> Customer balances with overdue amounts.

**Accounts Payable:**
=SCOTT.BILLS("InvoiceNumber", "ContactName", "Date", "DueDate", "AmountDue", "Status", "AUTHORISED")
-> AP aging report (unpaid bills).

=SCOTT.CONTACTS("Name", "BalanceDue", "OverdueAmount", "IsSupplier", TRUE)
-> Supplier balances with overdue amounts.

**Cash Flow:**
=SCOTT.BANKTRANSACTIONS("Date", "Type", "ContactName", "Total", "Type", "RECEIVE")
-> Cash receipts.

=SCOTT.BANKTRANSACTIONS("Date", "Type", "ContactName", "Total", "Type", "SPEND")
-> Cash payments.

=SCOTT.PAYMENTS("Date", "ContactName", "Amount", "InvoiceNumber")
-> Payment details with invoice references.

**Contact Management:**
=SCOTT.CONTACTS("Name", "EmailAddress", "Phone", "BalanceDue")
-> Contact list with balances.

=SCOTT.CONTACTS("Name", "AccountNumber", "DefaultCurrency", "IsCustomer", TRUE)
-> Customer master list.

---

**11. Error Handling**

**Common Errors:**
| Error | Cause | Solution |
|-------|-------|----------|
| #VALUE! | Invalid account code | Verify code exists in Xero chart of accounts |
| #NAME? | Function not recognized | Check Scott's Add-in is installed and enabled |
| #N/A | No data found | Verify filter values, check data exists |
| Connection error | Not authenticated | Re-authenticate in Scott's Add-in menu |
| Rate limit | Too many requests | Reduce formula refresh frequency |

**Debugging Tips:**
1. Test account codes in Xero first to verify they exist
2. Start with simple formulas before adding filters
3. Check Scott's Add-in connection status
4. Verify field names are spelled correctly (case-sensitive)
5. For contacts, ensure IsCustomer/IsSupplier filter matches data

---

**Final Checklist:**
- What Xero data is needed? (GL balances? Invoices? Contacts? Bank?)
- What account code(s) are involved? (Verify in Xero chart of accounts)
- What fields are required for the output?
- Is a filter needed? (Status, contact type, date range)
- Are account codes and field names spelled correctly?
- Is the Scott's Add-in connected and authenticated?
- Are rate limits being respected?

---

**Additional Resources:**
- Scott's Add-ins for Xero: https://www.scottsaddins.com/xero-excel-add-in/
- Scott's Add-in Documentation: https://www.scottsaddins.com/documentation/
- Xero Chart of Accounts: https://central.xero.com/s/article/Set-up-your-chart-of-accounts
- Xero API Reference: https://developer.xero.com/documentation/api/accounting/overview
