How do I add Xero?

Add Xero

Connect your Xero organisation to Supply Lens, switch on the records you want to post, route Documents to it and prove the first invoice with your finance team.

About 8 min

By the end of this guide your Xero organisation is connected to Supply Lens, it has a Configuration for each kind of record you want to post, a Mapping sends Documents to it, and you have checked a test invoice in Xero with your finance team.

Before you start

An active Xero account, with the organisation you want Supply Lens to post into. If your finance team has a Xero demo or test organisation, connect that first: postings to a ledger are hard to undo cleanly.
A Supply Lens account with access to Settings → Integration setup → Integrations.
Someone who can sign in to that Xero organisation, because you connect your Xero account to Supply Lens while creating the Integration.
Answers from finance. Agree who numbers invoices (the source system or Xero), whether invoices arrive as drafts or approved, which account codes sales, shipping, discount and charge lines post to, and whether Supply Lens or Xero sets the tax type. The Before you start lesson has the full checklist.
Your Xero details: account codes, tax types (if Supply Lens will set them), the bank accounts payments should land in, and tracking category names.
Parties for your suppliers, with a Xero identifier (Xero Contact ID, Xero Contact Name, Xero Contact Number or Xero Account Number) if you'll send supplier bills, so Xero doesn't create duplicate contacts. See Add a party identifier.
The source of your Documents already connected, for example your storefront, ERP or warehouse. Xero sits at the finance end of the flow; something else supplies the orders or shipments.

Steps

1. Create and connect the Integration

Log in to Supply Lens and go to Settings → Integration setup → Integrations.
Click + ADD INTEGRATION in the top-right, search for Xero and click ADD.
Complete the form and connect your Xero account when asked, signing in to the right Xero organisation.
Click CONNECT. The new Xero Integration appears in your list.
Click the arrow on it to expand its tile. Leave Activation disabled for now, leave State and Default Unit of Measure unset, and rename it with the pencil if you'll have more than one (for example Xero (demo) and Xero (live)).

Open Supply Lens

2. Add Configurations

Add one Configuration for each kind of record you want Supply Lens to create in Xero. Switch on only the ones you need.

Configuration	What it becomes in Xero	Direction
Xero Invoice	A sales invoice, optionally with a payment	Send (can also Receive to read invoices out of Xero)
Xero Credit	A credit note, optionally with a refund	Send
Xero Purchase Order	A purchase order	Send
Xero Purchase Invoice	A supplier bill	Send
Xero Journal	A manual journal	Send
Xero Bank Transaction	A bank transaction	Send
Xero Statement	A statement-style record from tagged amounts	Send

On the Xero tile, click Configurations, then + Add.
Choose the document type, for example Xero Invoice.
Click Send (and Receive only if you want to read invoices from Xero).
Click Create Default JSON.
Change the settings your finance team agreed. For a first test, set statusUnpaid and statusPaid to DRAFT, and set your account codes, such as shippingLineAccountCode. Every setting is explained in Xero settings.
Click Save. Repeat for each record type.

Good to know

If you send lines as descriptions only (createLinesAsDescriptionsOnly) and don't set descriptionLineAccountCode, Supply Lens uses account 200.

3. Add Mappings

A Mapping tells Supply Lens which Documents to send to Xero.

Go to Settings → Integration setup → Mappings and click + ADD.
Set Map to the document type, such as Invoice.
Set From to the Integration the Documents come from, As to Target Data, and To to your Xero Integration.
For testing, turn Automatic off so each Document waits as Ready until you process it. Leave Enabled on.
Click SAVE.

If your source produces shipments rather than invoices, use two Mappings: the Shipment As Document to produce an Invoice Document, then the Invoice As Target Data to Xero. See Add a Mapping.

4. Run a first test

On the Xero tile, set Activation to Enabled. A disabled Integration sends nothing, even by hand. Leave the Schedule off for now.
Create or pick a test Document of the type you mapped, such as a standard order that becomes an invoice, and process it to your Xero Mapping.
On the Xero tile, under Manual Operation, click Run Send.

Check it worked

The Document in Supply Lens has the status Complete.
Its Target Data (what was sent to Xero) has the communication status Sent.
The record in Xero is there as a draft. Ask finance to check the contact, number, reference, dates, account codes, tax, tracking and totals.

When finance has signed off a test for every path you configured (shipping, discounts, each tag, payments, returns), set the agreed live statuses, turn Automatic on, and choose a Schedule. The Test and go live lesson has a full test set and go-live checklist.

If something goes wrong

Nothing reaches Xero. Check Activation is enabled, each Configuration is set to Send, and the Mapping to Xero is enabled with filters that match your Documents.
The connection fails or stops working. Read the message, check you're signed in to the right Xero organisation, and try again. Xero credentials can expire or be revoked if settings change in Xero; see Update integration credentials.
Target Data is Failed. Open the Document's Logs for Xero's message; a missing account route or an unmapped tax code is the usual cause. See Troubleshoot Xero.
A resend is Cancelled. Supply Lens won't send Target Data with the same reference twice. Set the existing Target Data to Cancelled, then reprocess.

If you're still stuck, email support@supplylens.co.uk with your Integration Id from the tile.