--- title: "Connecting Xero to Qualy" description: "How the Qualy–Xero integration works—invoices for your payments, bills for commission splits, two-way \"paid\" sync, contact matching by email, account and GST mapping, and how to fix the issues that come up." lastModified: "2026-08-27" lang: "en" wordCount: 2419 url: https://qualyhq.com/training/integrations/xero --- ## Site navigation - [For schools](/international-education/for-schools.md) — For international education schools - [For agents](/international-education/for-education-agents.md) — For international education agents - [Explore](/training.md) — Watch videos on how to use Qualy - [About](/about.md) — Learn about Qualy's mission and values - [Pricing](/pricing) - [5-min demo](/demo.md) - [Login](https://dashboard.qualyhq.com) # Connecting Xero to Qualy > Keep your Xero books in step with the payments and commissions you run through Qualy. ## At a glance - **Intended for:** Admins & accountants - **Category:** Accounting - **Reading time:** 7 minutes - **Last updated:** 12th July 2026 ## Quick summary Connect Xero in Settings → Add-ons & integrations. Once connected, Qualy creates an invoice in Xero for each payment (numbered QLY-PYMT-…), creates a bill for each commission split, and keeps the "paid" status in step both ways—mark a payment paid in Qualy and the Xero invoice is marked paid, and vice-versa. Records are matched to Xero contacts by email first. Two settings decide most behaviour: when payments sync (instantly, or only once fully paid) and which Xero accounts and tax rates each line maps to. Most issues trace back to one of three things: an email that doesn't match, a Xero lock date on a closed period, or a Xero account that isn't set to "Enable payments". ## Overview The Xero integration keeps your accounting in step with Qualy automatically, so you're not re-keying invoices and payments by hand. Once connected, Qualy will: - **Create an invoice** in Xero for each payment you take (numbered `QLY-PYMT-…`) - **Create a bill** in Xero for each commission split you owe a partner or supplier - **Keep "paid" in step both ways** — mark a payment paid in Qualy and the Xero invoice is marked paid; mark the Xero invoice paid and Qualy records the payment - **Retire the Xero record** when you cancel a payment in Qualy — deleting a draft, voiding an approved one, and never touching one that's already paid You stay in control of the detail: **when** payments sync, whether they post as invoices or bills, and how your **accounts**, **tax rates** and **items** map across. Qualy syncs with a **single Xero organisation**. Pick the one you want kept in step—the sync can't be split across two. ## Connecting Xero Open **Settings → Add-ons & integrations**. Find **Xero** and choose **Connect**. You'll be sent to Xero to sign in and authorise Qualy. Back in Qualy, choose the **Xero organisation** to sync with. Map your **accounts, tax rates and items** (below), and choose **when payments sync**. That's it—from then on, new payments and splits flow into Xero on their own. If you're moving your history across from Xero, read [Coming from Xero already?](#coming-from-xero-already) before you start. ## What syncs, and when ### Payments become invoices Every payment you create in Qualy becomes an **invoice in Xero**, numbered `QLY-PYMT-` followed by the payment number. You decide **when** that happens: - **Instantly** — the invoice is created as soon as the payment exists (good for keeping receivables complete), or - **When fully paid** — Qualy only creates the invoice once the payment is settled (good if you'd rather Xero show only real, paid revenue). When the payment is paid, Qualy marks the matching Xero invoice **paid** for you—unless you've asked it not to (see [marking paid](#who-marks-things-paid)). ### Commission splits become bills When you split a payment to pay a school, agent or supplier their commission, Qualy creates a **bill** (accounts payable) in Xero for that partner. That's what lets your Xero show both sides of the deal—the revenue you invoiced and the commission you owe. By default payments post as **invoices** and splits post as **bills**. If your accounting is set up differently, both can be changed—tell us how you'd like each to post. ### Two-way "paid" sync The integration works in **both directions**: - **Qualy → Xero** — a payment paid in Qualy marks its Xero invoice paid. - **Xero → Qualy** — mark the `QLY-PYMT-` invoice paid in Xero, and Qualy hears about it and records the payment against the student. So whichever side your team reconciles in, the other keeps up. ### Who marks things paid You can let Qualy **mark invoices and bills paid automatically**, or turn that off and reconcile payments yourself in Xero while still letting Qualy create the invoices. Payments and commission splits each have their own toggle, so you can, for example, auto-mark student invoices paid but reconcile commission bills by hand. ## One organisation, matched by email Qualy lines your records up with Xero **contacts by email address** first. Emails are normalised for accents (so "josé" and "jose" match). If there's no email match, it falls back—in order—to the contact number, the account number, an exact name match, and finally a name-with-number format. Email is by far the most reliable match. A student or agent whose email differs between Qualy and Xero (or is missing on one side) is the single most common reason an invoice ends up on the wrong contact or gets duplicated. Keep emails **consistent and correct on both sides**. ## Accounts, tax rates and items During setup you tell Qualy how each line should land in your chart of accounts: ### Revenue and expense accounts Set a **default account** for payments, and optionally map specific **fee categories** to specific accounts (for example, tuition to one account, application fees to another). Commission splits post to their own **partnership** and **supplier** accounts. Qualy can also **match an item's name to a Xero account** automatically to fill any gaps—exactly, or with a fuzzy match at a similarity threshold you choose. ### Tax rates (GST/VAT) Map the tax you charge in Qualy to the matching **Xero tax rate**. Qualy automatically uses the correct side of the rate for the account—an income rate on revenue accounts, an expense rate on commission accounts—so the same tax item works on both an invoice and a bill. See [GST and tax rates](#gst-and-tax-rates) for the detail. ### Items and tracking categories Map Qualy items to **Xero items**, and (if you use them) map to **Xero tracking categories** so revenue and commissions are tagged to the right course, campus or cost centre. ### The invoice reference Choose what goes in the Xero **Reference** field—the contact number, the contact number and name, or the supplier and due date—so your invoices and bills are easy to search and reconcile. ## GST and tax rates This is worth understanding, because it's behind the most common accounting question we get: *"why was a commission bill created without GST?"* In Xero, a tax rate belongs to a **side**: an *income* (output) rate is only valid on a **revenue** account, and an *expense* (input) rate only on an **expense** account. Qualy stores one tax rate per item and automatically flips it to the correct side for the account a line posts to, so you don't have to keep two mappings. A line ends up **without GST** when Xero refuses the rate, which happens if: - the tax rate mapped to the item isn't valid for that account, or - the **contact** or **account** isn't set up for GST in Xero. When Xero refuses the rate, the invoice or bill is still created—just without the tax on that line. If commission bills are coming through without GST for agents you know are GST-registered, the fix is in the **mapping and account setup**, not in each bill. Check that the tax rate is mapped to the right Xero tax type for the commission (expense) account, and that the account and the agent's contact are configured for GST. Send us an example and we'll review the mapping with you. ## Cancelling and voiding Cancel or delete a payment in Qualy and Qualy **retires the Xero invoice for you**, based on where that invoice is: - **Draft** → deleted in Xero - **Approved (authorised) but unpaid** → voided in Xero - **Already paid** → left untouched, so your reconciled books never change The same logic applies to a cancelled commission split and its bill. If Xero happens to be rate-limiting at that moment the change can lag by a few minutes—Qualy keeps retrying until it goes through, and a background reconciliation pass catches anything that was dropped. ## Coming from Xero already? If you're moving across from Xero, Qualy brings your history over and matches it to your students and agents, then takes over ongoing invoicing. A few things make the migration go smoothly: - **Paid invoices are protected.** Anything already paid in Xero is never modified or deleted—your reconciled history is safe. - **Unpaid drafts and approved invoices** that pre-date Qualy can be cleared so Qualy re-creates clean `QLY-PYMT-…` invoices it manages going forward. This is what avoids duplicates. - **`XRO-` numbers are your migrated history**, not duplicates. You may see them alongside the `QLY-PYMT-…` invoices Qualy manages. Don't bulk-delete `XRO-` invoices thinking they're duplicates—most aren't. If a specific one looks wrong, send it to us and we'll confirm before anything is removed. ## Troubleshooting ### "I marked it paid in Qualy but Xero didn't update" Check your **lock date** first—it's the most common cause. If the invoice falls in a closed (locked) accounting period, Xero won't let Qualy update it or mark it paid. Next, check that the Xero account has **"Enable payments to this account"** ticked. If neither applies, it may be a brief Xero rate-limit that Qualy is already retrying. ### "An invoice was created even though the payment was already received" The account the payment posts to needs **"Enable payments to this account"** enabled in Xero—otherwise Xero won't attach the payment and the invoice looks unpaid. Also confirm the student's **email matches** the Xero contact, so Qualy finds the existing invoice instead of making a new one. ### "Old, already-paid invoices were recreated" During a heavy period Xero can **rate-limit** the sync, and "paid" confirmations can arrive out of order. Qualy retries through it and a reconciliation pass corrects the order on its own—no data is lost. If something still looks off afterwards, send us the examples. ### "A payment shows Failed but the money arrived" This can follow a mid-payment split amount edit and usually **self-heals**. If a payment is still showing the wrong status after a little while, tell us and we'll refresh it. ### Rate limits, generally Xero limits how fast any connected app may call it. In busy periods a sync can lag by minutes; Qualy queues and retries automatically and reconciles anything dropped, so it catches up without losing data. Prefer not to sync at all for something? You can always export the same data as CSV from **Reports** and import it into Xero manually. ## Frequently asked questions ### When I cancel or delete a payment in Qualy, does it void in Xero too? Yes. Qualy retires the matching Xero invoice automatically: if it's still a draft it's deleted, if it's been approved (authorised) but not paid it's voided, and if it's already paid it's left untouched so your reconciled books never change. The same applies to a cancelled commission split and its bill. If Xero is rate-limiting at that moment the change can lag by a few minutes—Qualy keeps retrying until it goes through. ### Why were some agent commission bills created without GST, even for GST-registered agents? A line only carries GST when the tax rate mapped to it is valid for the Xero account the line posts to. Xero rejects an income (output) tax rate on an expense account and vice-versa, and it rejects any GST rate on a contact or account not set up for it—when that happens the bill is still created, just without the tax. The fix is in your tax mapping and account setup, not in the individual bill: map the tax rate to the correct Xero tax type for that account, and make sure the commission (expense) account and the agent contact are configured for GST. Contact us and we'll check the mapping with you. ### I see invoices in Qualy or Xero with an "XRO-" prefix. Are they duplicates? Almost always no. XRO- invoices are historical invoices brought across when you migrated from Xero into Qualy—they preserve your existing records. Invoices Qualy creates and manages itself are numbered QLY-PYMT-…. Don't bulk-delete XRO- invoices; if you think a specific one is a genuine duplicate, send it to us and we'll confirm before anything is removed. ### Qualy created an invoice even though the payment was already received. What happened? Two common causes. First, the Xero account the payment posts to must have "Enable payments to this account" ticked in Xero—without it, Xero won't let Qualy attach the payment, so the invoice looks unpaid. Second, matching: if the student's email in Qualy doesn't match the Xero contact, Qualy can't find the existing invoice and creates a new one. Fix the account setting and align the email, and it reconciles. ### I marked a payment paid in Qualy but the Xero invoice didn't update. Why? Usually a lock date. If the invoice is dated inside a closed (locked) accounting period, Xero won't let Qualy change it or mark it paid—check your lock date for that period first. The other causes are the "Enable payments to this account" setting, or a brief Xero rate-limit that Qualy retries through on its own. ### How does Qualy match my students and agents to Xero contacts? By email address first (accents are normalised so "josé" and "jose" match). If there's no email match it falls back, in order, to the contact number, account number, an exact name match, and finally a name-with-number format some contacts use. Email is by far the most reliable—keeping it consistent and correct on both sides is what makes matching "just work". ### Can I connect more than one Xero organisation? No. Qualy syncs with a single Xero organisation. You can't split the sync across two—choose the organisation you want Qualy to keep in step. ### Can I control when and how payments sync? Yes. You choose whether a payment syncs the moment it's created or only once it's fully paid; whether it posts as an invoice or a bill; and whether Qualy marks the Xero record paid automatically or leaves that to you. Commission splits post as bills by default. We set these with you during onboarding and you can change them any time. ### A payment shows "Failed" in Qualy but the money arrived. What do I do? This can happen after a split amount is edited mid-payment, and it normally self-heals—Qualy re-checks and corrects the status. If a payment is still showing the wrong status after a little while, send it to us and we'll refresh it. ## Prefer doing this via the Qualy API? Head over to our developer docs for everything you need—endpoints, examples, and simple how-tos. [View API Docs](https://docs.qualyhq.com/docs) ## More on Qualy **Industries** - [For schools](/international-education/for-schools.md) — For international education schools - [For agents](/international-education/for-education-agents.md) — For international education agents **Support** - [Training](/training.md) - [System status](https://qualyhq.statuspage.io/) — Qualy system status - [Product updates](https://changelog.qualyhq.com) — As we work on Qualy, here we spotlight what we’ve learned and updated across our products - [Contact](/contact-us.md) **Product** - [Demo](/demo.md) - [Enterprise](/enterprise.md) - [Testimonials](/testimonials.md) — Learn what some customers have to say about Qualy - [About](/about.md) — Learn about Qualy's mission and values - [Blog](/blog) — International education payments blog by Qualy - [Trust center](/trust.md) - [API](/api.md) — Qualy API for international education payments - [Zapier](/zapier.md) — Connect Qualy to 7,000+ apps with Zapier - [NexPay](/nexpay.md) — Qualy + NexPay — automate everything around the payment **Legal** - [General terms](/terms-and-conditions.md) - [Payer terms](/terms-for-payers.md) - [Privacy policy](/privacy-policy.md) - [BECS DDR](/becs-dd-service-agreement.md)