Connect Xero

Once Xero is connected, an authorised invoice or credit note is created in Xero for you, and invoices are marked as paid in Paperwork when Xero shows them paid. For that to work, Paperwork has to know which Xero account and tax type each of your nominal codes and tax rates corresponds to. That is the mappings step, and it is where most problems come from.

Only organisation Owners can connect, disconnect and map. Open Settings under Admin in the sidebar and click Integrations.

Connect to Xero

Click Connect to Xero

On the Xero card, click Connect to Xero. Your browser goes to Xero to sign in and approve access.

Choose the Xero organisation

If your Xero login covers more than one organisation, Paperwork asks Which Xero organisation? Pick the one this workspace invoices from and click Use this organisation. With only one, it connects straight away.

Check the card

You will see Xero connected. The card shows a Connected badge, the Xero organisation's name, and who connected it and when.

If Xero is not set up on the server you are using, the card says "Xero is not available on this server yet." and Connect to Xero is greyed out. Email [email protected].

If the sign-in does not complete, Paperwork shows one of these on return:

• "Xero sign-in was cancelled or denied. Nothing was connected."
• "That Xero sign-in link had expired. Please connect again."
• "Xero rejected the sign-in. Please try again."
• "Your Xero login has no organisations to connect."

If the card shows Expired, Xero has withdrawn access ("Xero disconnected us. Reconnect to resume syncing invoices."). Click Reconnect.

Choose which PDF customers receive

Under Documents, choose what customers get when you send, email or download a document:

• Send Paperwork's invoice PDF
• Send Xero's invoice PDF, with the online payment link

It saves the moment you click, and you will see Documents setting saved. With Xero's PDF, an invoice cannot be sent until it is in Xero.

Map your nominal codes and tax rates

The Xero mappings section has a badge at the top right. It reads N unmapped — the number of active nominal codes and tax rates that have no Xero equivalent — or All mapped. Archived rows are not counted.

Set the two defaults

Under Defaults, choose a Default sales account and a Tax type for zero-VAT lines. They are used when an invoice line has no nominal code or no tax rate. Without a default sales account, a line with no nominal code fails. Without a zero-VAT tax type, a line with no tax rate fails.

Map nominal codes to Xero accounts

In Nominal codes → Xero accounts, each row shows your Code and Name. Choose the matching account in Xero account.

Map tax rates to Xero tax types

In Tax rates → Xero tax types, each row shows your Rate and Name. Choose the matching tax type in Xero tax type.

Click Save mappings

You will see Xero mappings saved. The button is greyed out until you change something.

Paperwork pre-fills what it is confident about and marks it Suggested: a Xero account with the same code as your nominal code, a Xero tax type if exactly one has the same percentage as your tax rate, and ZERORATEDOUTPUT for zero-VAT lines. A suggestion is only a pre-fill. Nothing is stored until you click Save mappings.

If you add accounts or tax types in Xero afterwards, click Refresh from Xero to load them. It does not discard anything you have not saved.

Send an invoice to Xero

When you authorise an invoice or credit note, the dialog has a tick box, Also create this invoice in Xero. It is ticked by default. Untick it if this document should stay out of Xero.

If the customer is not yet linked to a Xero contact, the dialog says so — "isn't linked to a Xero contact yet — Paperwork will try to match it automatically" — and offers Link now. Paperwork does not create Xero contacts automatically.

Invoices authorised before Xero was connected, or with the tick box cleared, show Not in Xero, and Paperwork offers no way to send them afterwards.

Link a customer to a Xero contact

Link now, and Choose Xero contact on a stuck invoice, open Link (customer name) to a Xero contact. Under Suggested you will see contacts with a matching account number (Account number match) or the same name (Same name). Click the link button next to the right one.

If the contact is not suggested, type at least 2 characters into Search Xero contacts. If it does not exist in Xero yet, click Create (customer name) in Xero, which builds a contact from the customer's billing details. A contact you create gets the details Paperwork holds today, so check the customer's address first.

Fix an invoice that did not sync

On the invoice, the Accounting card shows a status:

Status	Meaning
Sending to Xero	Being sent now
In Xero	Done. It shows the Xero number and an Open in Xero link
Needs a Xero contact	The customer is not linked yet. Click Choose Xero contact
Xero sync failed	See the red message under the status, then click Retry

A failed invoice tells you exactly what is missing, in one of these four messages:

• "No Xero account is mapped for nominal code" followed by the code
• "No Xero tax type is mapped for tax rate" followed by the code
• "No default sales account is set for lines without a nominal code."
• "No Xero tax type is set for zero-VAT lines."

Fix the mapping or the default, click Save mappings, go back to the invoice and click Retry. You will see Sending to Xero again. Linking a contact retries it for you.

Disconnect Xero

On the card, click Disconnect and confirm Disconnect Xero. New invoices stop syncing. Invoices already in Xero keep their links, your mappings are kept, and you can reconnect at any time.

What to do next

• Learn how invoicing works
• Set up bank details and invoice emails
• Link a customer to its Xero contact
• Setup guide, step 12: Connect Xero, DWT and the customer portal if you are setting Paperwork up for the first time