Skip to main content
Once Xero is connected, you can raise brokerage invoices straight from unbilled revenue in UMS. Every invoice UMS creates is pushed to Xero as a draft — nothing is approved or sent automatically. This guide covers how to control what those drafts look like: which account code and tax type each line uses, what the invoice reference says, and — the part most organisations want to change — the description on each invoice line.
Xero settings live under Settings → Integrations and require admin access. Raising invoices requires the Brokerage permission.

​
Where customisation happens

There are two places, and they work together:
Set the pattern you use most often as the saved mapping in Settings, then override it in the wizard only when a particular raise needs something different.

​
Connecting Xero

1

Open the Integrations section

Go to Settings → Integrations. You’ll see a Xero card with a connection status badge. (MYOB, QuickBooks, and NetSuite are listed as coming soon.)
2

Authorise UMS in Xero

Click Connect Xero. You’re sent to Xero to sign in and choose the organisation to connect. UMS requests access to invoices, contacts, and read-only access to your Xero settings.
3

Confirm the connection

After authorising you’re returned to UMS and the badge changes to Connected, showing the Xero organisation name.
The Invoice field mapping panel only appears once the status is Connected. If you disconnect and reconnect, your saved mapping is retained.

​
Setting your organisation-wide mapping

With Xero connected, the Invoice field mapping panel appears below the connection card: “Choose how brokerage data is mapped into Xero invoice fields.”

​
Defaults

Two fallbacks used for any line that doesn’t get a value from the mapping below:
  • Default account code — the Xero sales account brokerage revenue posts to. Leave blank and UMS uses the platform default, 200.
  • Default tax type — the Xero tax type applied to each line. Leave blank and UMS uses OUTPUT.

​
How to build a custom description

The Description template field controls the text on every invoice line. Write plain text and insert fields in curly braces; each placeholder is replaced with that revenue row’s value when the line is created.
1

Type the fixed wording

Start with the words you always want, for example Brokerage commission —.
2

Insert the dynamic fields

Use the Insert field dropdown beside the template box to append a placeholder at the end of the template, or type the token yourself. Fields are grouped by source (Revenue, Brokerage record, Agreement, Account, Supplier, Connection, Tariff rate, Invoice, Calculation).
3

Check the result

Raise a preview (see Overriding a single raise) — the preview step renders the template against real revenue rows before anything reaches Xero.
A worked example:
renders as:
If you leave the template blank, UMS falls back to Brokerage commission <period start>–<period end>.

​
Available fields

These are the placeholders you can use in the description template. They resolve per revenue line.
Dates accept a format suffix. {revenue.date_start:%b %Y} renders Apr 2026 instead of 2026-04-01.
A placeholder that has no value for a given row renders as empty text rather than failing the raise — so check your preview for gaps like a missing connection address. Misspelt tokens are rejected when you save. Descriptions are truncated at 4,000 characters, Xero’s limit.

​
Invoice fields

These resolve once per invoice rather than per line:
  • Reference — the Xero invoice reference. Can use a group field (see below) or any per-revenue field, or a literal value. Choose No reference to leave it off.
  • Invoice Date — defaults to today.
  • Due Date — defaults to the Xero contact’s payment terms.
Invoice-level (group) fields, available to Reference, Invoice Date, and Due Date:

​
Line fields and tracking

The line table maps Quantity, Account Code, and Tax Type. Each row offers Use default, a brokerage source field, or Literal value. Below that, UMS lists a row for each active tracking category in your Xero organisation as Tracking: <category name>. Pick the brokerage field whose value should be written to that category, or leave it Not mapped. Tracking rows take a source field only — not a literal.
Tracking categories and their options are read from Xero. UMS never creates them — add the category in Xero first, then map it here.
Click Save mapping to apply. The mapping applies to all future raises; invoices already in Xero are unchanged.

​
Overriding a single raise

Start a raise from Brokerage → Revenue (or go to /billing/raise-invoice). The wizard, Raise invoice from unbilled revenue, has five steps:
1

Select supplier

Choose the supplier whose unbilled revenue you want to bill. This step only picks the supplier — description editing is in the next-but-one step.
2

Unbilled revenue

Select the revenue rows to include on the invoice.
3

Adjust fields

Override how brokerage data maps into invoice fields for this raise only.
  • Description template — type a template here to replace the saved one. The placeholder text shows your saved default; leave it blank to keep using that default. Same tokens as the table above.
  • Per-raise field overrides — a table of Field / Default / Override for Account code, Tax type, and Reference. Leave a row on Use default to keep the saved connection mapping, or pick a source field or Literal value. Reference also offers No reference.
Tracking categories, invoice date, and due date can’t be overridden per raise — change those in Settings.
4

Billing contact

Choose the Xero contact this invoice bills against. UMS pre-selects the contact previously linked to that supplier, or you can search Xero contacts or Create new contact.
5

Preview & raise

The preview renders every line exactly as it will appear in Xero, with your template applied. Check the descriptions here, then raise. The invoice is created in Xero as a draft.

​
Which value wins

When a field is set in more than one place, UMS resolves it in this order — later layers override earlier ones:
1

Supplier defaults

For supplier-billed invoices, the supplier’s Default GL account and Default tax code seed the account code and tax type. Suppliers do not carry a description template.
2

Saved connection mapping

Whatever you saved in Settings → Integrations.
3

Per-raise override

Anything you set in the wizard’s Adjust fields step.
4

Built-in fallbacks

If account code or tax type is still empty, UMS uses your Default account code / Default tax type, then the platform defaults 200 and OUTPUT. An empty description falls back to Brokerage commission <period start>–<period end>.

​
Troubleshooting