Applicable to: Association and Club Administrators
Application(s): Admin Portal > Settings > General > Integrations
This article will cover the following:
- How to connect your PlayHQ organisation with your Xero account
- Setting up contacts and mapping GL accounts
- Understanding automated invoice generation
Related articles:
Introduction
Connect your PlayHQ organisation with your Xero account to reconcile your finances and automate invoice generation every time you receive a deposit to your connected bank account/s.
This integration will help streamline your financial management by automatically creating sales invoices in Xero that match your PlayHQ transactions, saving you time and reducing manual data entry.
Before You Begin
To set up the Xero integration, you need:
- To be an 'account holder' Xero user to setup and manage a Xero integration
- Administrator access to your PlayHQ organisation
- Your organisation's Xero GL account codes ready for mapping
Connecting Your Xero Account
-
Access the Integrations tab
Navigate to Settings > General > Integrations tab in the Admin Portal. Make sure you are Using as the correct organisation before proceeding. Click the Connect button in the Xero section.
-
Log in to Xero
Click the Log in to Xero button. Enter your Xero credentials when prompted.
If you're already logged in to Xero in another browser tab, the system will automatically recognise your existing session.
-
Select your Xero Organisation and Authorise
Choose the Xero organisation that you want to link to your PlayHQ organisation, then click Allow access to authorise the connection.
-
Select a Primary Contact
After connecting to Xero, you'll need to select a primary contact to use as the reference for generating sales invoices. We recommend creating a contact named "PlayHQ" specifically for this purpose
Note: If you need to create this contact first, do so in Xero, then refresh the PlayHQ page to see the new contact in the dropdown list.
Set Up Your GL Account Mapping
Important: At minimum, you must map the 'Unmapped Revenue Items' category to a GL account (such as Suspense). This is required to complete the setup and ensures any future transaction types that don't match existing categories will still be processed.
-
Map Categories to GL Accounts
You'll see a table with predefined categories, including product sales, registrations, and deductions like vouchers and fees.
For each category, select the corresponding Xero General Ledger (GL) account from the dropdown menu. You can assign the same GL account or tracking code to multiple categories if required.
-
Set Up Tracking Codes (Optional)
If you have tracking codes configured in Xero, up to two additional tracking columns will appear.
You can optionally map these tracking codes to relevant categories for more detailed financial reporting.
-
Save Your Configuration
After completing all mandatory fields, click Save to apply your settings
You'll see a confirmation that your Xero account is now connected
Understanding Automated Invoice Generation
Once your integration is complete, PlayHQ will automatically generate invoices in your Xero account whenever funds are disbursed to your organisation.
How Invoices Are Generated
When a payout is processed to your organisation:
- A sales invoice is automatically created in your Xero account
- The invoice includes a breakdown of the pre-tax funds by the categories you mapped during setup
- Xero will calculate Tax/GST in the invoice based on the mapped GL account codes
- Line items are grouped by category and mapped to the appropriate GL accounts
- The invoice is created using the primary contact you selected during setup
Sample invoice:
Tax Considerations
Important Tax Information:
- It is your responsibility to ensure that each GL code in Xero has the appropriate tax rate configured if your organisation is registered for GST
- PlayHQ sends pre-tax amounts to Xero, and Xero calculates the tax based on your GL account settings
- If tax is calculated correctly, the payout total should match the invoice total (with possible minor differences due to rounding)
- Incorrect tax configurations may result in discrepancies in the invoice totals
Managing Your Xero Integration
-
Updating Your Settings
You can modify your Xero connection details or mapping settings at any time.
Navigate to Settings > General > Integrations tab.
Click Edit in the Xero section to make changes.
-
Refreshing Xero Data
If you make updates in Xero (like adding a new contact or GL account), simply refresh the page in the Admin Portal to see these changes reflected.
-
Disconnecting from Xero
If needed, you can disconnect your Xero integration by clicking the Disconnect button.
Note that disconnecting will stop all future invoice generation until reconnected.
Troubleshooting Common Issues
If a GL account code or contact that was previously mapped in PlayHQ is subsequently removed from Xero:
- An error will appear in the Xero connection page
- The error will indicate which mapping was removed
- You'll need to select a new mapping before saving the updated configuration
If the Xero integration becomes disconnected:
- All subsequent invoices will cease generating
- An error will appear in your organisation's Xero connection details
- To resolve this, click Disconnect in PlayHQ and then reconnect to Xero by following the steps outlined above
Support Resources
If you encounter any issues or have questions during the setup process:
- Contact PlayHQ Support for integration-related issues
- For Xero-specific questions, visit the Xero Support Centre