# Xero

URL: https://docs.sparklayer.io/help/integrations/accountancy/xero
Applies to: Shopify

Connect Xero to SparkLayer on Shopify to turn B2B orders into invoices and contacts, set account codes and tracking categories, and track invoice payments.

> **Quick summary**
>
> - The Xero integration creates an invoice in Xero for each B2B order paid by invoice or on account. It can create the Xero contact too, and brings payments on those invoices back to the SparkLayer order.
> - Invoices are created shortly after the order reaches **processing** (or, if you choose, as each shipment is fulfilled). Changes you make to an invoice in Xero don't come back to SparkLayer.
> - Connect it in the SparkLayer Dashboard at **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**: turn on the switch and sign in to Xero. Needs the Pro or Enterprise plan and a Shopify store.
> - Customers can view and download their invoices from **My Account** on your store.

## What it does

[Xero](https://www.xero.com/) is online accounting software for managing finances, invoices and customer records.

SparkLayer has a direct integration with Xero. Your B2B orders sync to Xero as invoices and contacts, so there's less manual data entry and no need for another app to keep the systems in sync.

How a B2B order becomes a Xero invoice, and payments come back:

1. **B2B order**: Paid by invoice or on account, and processing or shipped
2. **Contact**: Matched by account number or email, or created
3. **Xero invoice**: Created in the background through the API
4. **Payments**: Payments and credit notes on the invoice update the SparkLayer order

### Let customers view invoices

When an invoice is ready, a **View & Download Invoice** button appears on the order in **My Account** on your store. It opens the public invoice page generated by Xero. If the button doesn't appear, see [Troubleshooting](#troubleshooting).

## What syncs and in which direction

Invoices and contacts go one way, from SparkLayer into Xero. Payments are the exception: they come back from Xero to the SparkLayer order.

| Data | Direction | Details |
| --- | --- | --- |
| Invoices | SparkLayer to Xero | One invoice for each eligible B2B order, or for each shipment if you choose. Changes you make to an invoice in Xero, such as to line items or customer details, aren't reflected back in SparkLayer or your platform. |
| Contacts | SparkLayer to Xero | Each invoice is linked to a matching Xero contact. If there's no match, SparkLayer can create one. Details are copied once, when the contact is created. |
| Payments | Xero to SparkLayer | Payments, credit notes and overpayments applied to the invoice update the SparkLayer order. See [Payment visibility](#payment-visibility). |

### How invoices are created

SparkLayer creates the invoice in Xero as soon as an eligible order arrives from your platform. This happens in the background so checkout stays fast, so the invoice can take a short while to appear in Xero. Each invoice has a note in its **History & Notes** in Xero showing it came from SparkLayer.

#### Which orders get an invoice

An order gets an invoice when both of these are true:

- **Fulfilment status is `processing` or `shipped`.** Orders that haven't reached `processing` yet, such as Shopify draft orders you haven't completed, don't get an invoice.
- **Paid with Payment by Invoice or Payment on Account.** Payment by Invoice orders are invoiced as soon as they reach `processing`. Pay on Account orders follow the **Invoice creation for Payment on account orders** setting. See [Payment methods](https://docs.sparklayer.io/help/ordering/payment-methods.md) to set these methods up.

The integration only covers B2B orders placed through SparkLayer. Retail (D2C) orders aren't sent to Xero.

#### Pay on Account orders and split shipments

| Setting | When invoices are created |
| --- | --- |
| **On order** | One invoice for the whole order, when it reaches `processing`. |
| **On shipment** | One invoice each time a fulfilment is completed, containing only the items in that fulfilment. This handles split shipments. |

Customers can download every invoice for an order from **My Account**. With split shipments, the order's shipping is always added to the invoice for the **first** shipment.

Split shipments can sometimes cause rounding differences, because your platform, SparkLayer and Xero calculate tax across shipments slightly differently. When SparkLayer detects one, it adds a "Rounding adjustment" line to the invoice, using Xero's rounding account code `860`. The Xero invoice total then matches the SparkLayer order.

#### What's on the invoice

| Field | Where it comes from |
| --- | --- |
| **Status** | **Submitted** by default. **Draft** if SparkLayer can't work out a valid due date. |
| **Contact** | The Xero contact matched (or created) from the order's customer. See [Contact matching and creation](#contact-matching-and-creation). |
| **Billing address** | The billing address on the matched Xero contact. |
| **Due date (Payment by Invoice)** | The order date. |
| **Due date (Payment on Account)** | Worked out in this order: 1) the customer's [net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) in SparkLayer, added to the order date; 2) the contact's payment terms in Xero; 3) your global payment terms in Xero; 4) otherwise, the order date. |
| **Item code** | The line's SKU, if **Map Line Items to Item Codes** is enabled. |
| **Account code** | The **Default Line Item Account Code**. |
| **Description** | The line's SKU and parent and child product names, plus any custom attributes. |
| **Quantity** | The quantity on the SparkLayer order. |
| **Unit amount, line amount and tax amount** | Calculated by SparkLayer and passed to Xero. |
| **Shipping** | A line at the bottom of the invoice, described with the shipping method name and SKU, using the **Shipping Line Account Code** (or the default account code). |
| **Tracking** | If you've set **Tracking categories**, every line gets those categories (up to 2). |

Xero allows one billing address per contact. If a SparkLayer customer has several addresses, the address on the invoice may differ from the one they used. SparkLayer only copies the billing address when it creates the contact, so later changes in SparkLayer need updating by hand on the invoice or the Xero contact.

### Contact matching and creation

Every invoice needs a Xero contact. SparkLayer matches an existing one or, if you allow it, creates one.

#### How contacts are matched

When it creates an invoice, SparkLayer looks for the right Xero contact in this order:

1. **Account number:** a Xero contact whose account number matches the accounting ID on the SparkLayer customer. See [how to set accounting IDs](https://docs.sparklayer.io/help/customers/account-and-addresses.md#advanced-account-settings).
2. **Email:** a Xero contact with the same email address.

If either matches, the invoice is linked to that contact. If neither does, **Automatic Contact Creation** decides whether a new one is created.

#### Several contacts with one email

In SparkLayer, each email address belongs to one customer. In Xero, several contacts can share an email address. If they do, the invoice goes to the first matching contact Xero returns. If your organisation has several contacts with the same email, give each a unique account number so matching is reliable.

#### Data synced when a contact is created

These details are copied once, when SparkLayer creates the Xero contact. Later changes in SparkLayer aren't synced.

- Company name
- First and last name
- Email address
- Billing and shipping address, from the order being invoiced
- Payment terms, if set with the payment terms [metafield](https://docs.sparklayer.io/help/glossary.md#metafields). Contacts are created with Xero's _days after bill date_ payment term type.

#### Contact names

Xero needs every contact **name** to be unique, so SparkLayer tries these names in turn:

1. The [company name](https://docs.sparklayer.io/help/customers/account-and-addresses.md#advanced-account-settings) metafield, if it's filled in. For example, "The Company".
2. If that name is taken, the company name followed by the customer's first and last name. For example, "The Company (Jane Doe)".
3. If that's also taken, the customer's first and last name. For example, "Jane Doe".

If all of these are taken, SparkLayer tries them again with a timestamp added, for example "The Company (20260520093837)", so the invoice can still be created.

### Payment visibility

If [payment visibility](https://docs.sparklayer.io/help/ordering/payment-methods.md#payments-visibility) is turned on, payments made against invoices in Xero show as transactions on the SparkLayer order. SparkLayer tracks:

- Payments and offline payments
- Credit notes applied to invoices
- Overpayments applied to invoices

Each one appears as a transaction on the order and changes the balance due. SparkLayer keeps tracking Xero payments in the background even when payment visibility is off.

#### Refunds

Refunds on card payments aren't tracked, because they're usually recorded as a credit note on the customer's account rather than applied to an invoice. If one of the payment types above is removed from an invoice, SparkLayer updates the order to match.

#### Credit limits

If you use [credit limits and account balances](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md), payments on Xero invoices for Pay on Account orders reduce the customer's unpaid balance automatically.

Credit limits set on contacts in Xero aren't available through the Xero API, so SparkLayer can't sync them. Set credit limits in SparkLayer instead: see [Credit limits and net terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md).

#### Credit notes

Credit applied to an invoice syncs as a payment. Unallocated credit on a Xero contact doesn't sync to the customer's balance in SparkLayer. To keep them in step, adjust the balance in the customer's metafield by hand to reflect the unallocated credit. Change it back once you've allocated the credit to an invoice.

## Common workflows

| You want | What to do |
| --- | --- |
| **An invoice as soon as the order is confirmed** (the default) | Nothing. When the order reaches `processing`, SparkLayer creates the Xero invoice automatically. |
| **Payment before you process the order** | This isn't automatic. Either move the order to `processing` without fulfilling it, for example by completing the Shopify draft order with payment due later, so Xero creates the invoice. Then fulfil it once the customer has paid. Or create the invoice by hand in Xero. |

For the first option on a Pay on Account order, **Invoice creation for Payment on account orders** must be **On order**. With **On shipment**, the invoice is only created when you fulfil. See [Configure the integration](#configure-the-integration).

On Shopify, an order paid by invoice or on account moves through these stages:

From draft order to Xero invoice and fulfilment:

1. **Draft order**: The order arrives as a Shopify draft order
2. **Complete the draft**: Mark it as paid, or complete it with payment due later
3. **Processing**: It's now a completed Shopify order
4. **Xero invoice**: SparkLayer creates the invoice
5. **Fulfil**: You ship the order

Marking a draft order as paid in Shopify turns it into a completed order, but doesn't fulfil it. See [Complete a draft order by hand](https://docs.sparklayer.io/help/ordering/automation-and-workflows.md#complete-a-draft-order-by-hand).

## Set up Xero

Check the requirements, connect your Xero organisation, then choose your settings.

### Requirements

- **The Pro or Enterprise plan.** See [Plans and features](https://docs.sparklayer.io/help/plans-and-features.md).
- **A Shopify store** connected to SparkLayer. See [Shopify](https://docs.sparklayer.io/help/platforms/shopify.md).
- **A Xero organisation** to connect.

### Connect Xero

1. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
2. Under **Accountancy**, turn on the switch next to **Xero**.
3. Sign in to Xero when it opens. Xero shows the data SparkLayer needs access to (see the [FAQs](#faqs)).
4. If your Xero account has several organisations, choose the one to connect. You can connect one organisation to your SparkLayer Dashboard.
5. Back in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, open Xero and complete the settings below.

### Configure the integration

| Setting | What it does |
| --- | --- |
| **Automatic Contact Creation** | Default: **Disabled**. Each invoice needs a Xero contact. If SparkLayer can't [match an existing one](#how-contacts-are-matched), this decides what happens. **Enabled**: SparkLayer creates a new Xero contact from the customer data it holds (see [Contact matching and creation](#contact-matching-and-creation)). **Disabled**: SparkLayer doesn't create contacts, because you create them in another system or manage them by hand in Xero. If no match is found, the invoice may fail. |
| **Default Line Item Account Code** | Default: `200`. The Xero account code for invoice line items. Find your account codes in **Chart of Accounts** in Xero. |
| **Shipping Line Account Code** | The Xero account code for shipping lines, for example `260`. If you leave it empty, the **Default Line Item Account Code** is used. |
| **Invoice creation for Payment on account orders** | Default: **On order**. When to create invoices for Pay on Account orders. **On order** creates one invoice for the whole order when it reaches `processing`. **On shipment** creates an invoice for each shipment, when it's fulfilled. See [Pay on Account orders and split shipments](#pay-on-account-orders-and-split-shipments). |
| **Invoice Line Item Mapping** | Contains **Map Line Items to Item Codes**. Default: **Disabled**. When enabled, each invoice line is linked to the Xero item (product) whose item code matches the line's SKU in SparkLayer. If no Xero item has that SKU, the invoice isn't created. See [Map line items to Xero items](#map-line-items-to-xero-items). |
| **Tracking categories** | Default: none. The Xero tracking categories to set on every invoice line, as comma-separated `CategoryName:Option` pairs. For example, `Channel:B2B,Source:SparkLayer` sets the **Channel** category to **B2B** and the **Source** category to **SparkLayer**. Xero allows up to 2 tracking categories per line: any more are ignored. |

### Map line items to Xero items

If you've already created an item in Xero for every product, using the product SKU as the Xero item code, you can link invoice lines to those items:

1. In **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, open Xero.
2. Under **Invoice Line Item Mapping**, turn on **Map Line Items to Item Codes**.

If a line's SKU doesn't exist as an item in Xero, the invoice isn't created. Once you add the missing item, the invoice is created.

### Turn off the integration

1. In the SparkLayer Dashboard, go to **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app.
2. Under **Accountancy**, turn off the switch next to **Xero**.

When the integration is off:

- No invoices are created for orders placed while it's off.
- Customers can no longer open their Xero invoices from **My Account**.

## Limitations

- Multiple tax rates on one line item aren't supported.
- Invoice creation is one way. Changes to invoices in Xero, such as to line items or customer details, aren't reflected in SparkLayer or your platform.
- Xero credit limits and unallocated credit don't sync (see [Payment visibility](#payment-visibility)).

## FAQs

**How do I disconnect from Xero?**

Turn the integration off in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**. This removes the connection to your Xero organisation. See [Turn off the integration](#turn-off-the-integration) for what happens next.

**Does the integration work for D2C orders?**

No. It only covers B2B orders created through your platform's connection with SparkLayer. Direct-to-consumer (D2C) orders aren't sent to Xero as invoices.

**What access does the integration need in Xero?**

When you connect, Xero lists the exact permissions SparkLayer asks for. We follow Xero's best practice and only ask for the minimum needed:

- **View & manage contacts**: to match invoices to existing contacts, and create new ones if your settings allow.
- **View & manage business transactions**: to create invoices for SparkLayer B2B orders and, in future, to view payments made on invoices. 
- **View organisation settings**: to read settings such as global payment terms when working out due dates.

## Troubleshooting

If your issue isn't listed, or it continues after these steps, [contact support](https://docs.sparklayer.io/help/support.md).

**Customers can't see their invoice in My Account**

Check that:

- **The integration is turned on** in **Integrations > Partners** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/partners)), or **SparkLayer Wholesale > Integrations > Partners** in the Shopify app, under **Accountancy**.
- **The order is `processing` or `shipped`.** Orders that haven't reached `processing` yet, such as Shopify draft orders you haven't completed, don't get an invoice.
- **An invoice exists in Xero** for the order. It can take a little while to sync. If there's a long delay, or no invoice was created, contact support with the customer and order ID.
- **The invoice isn't a Draft.** Xero doesn't give draft invoices a public link.

If invoice links are missing for **all** your customers, contact support.

**The address on the invoice is different from the one used at checkout**

Invoice addresses come from the Xero contact. SparkLayer lets a customer have several billing and shipping addresses, but Xero allows one of each per contact.

SparkLayer only uses its own addresses when it creates the contact. If the addresses change afterwards, they aren't updated in Xero automatically.