Xero
Applies toShopify
What it does
Xero (opens in a new tab) 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.
B2B order
Contact
Xero invoice
Payments
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.
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. |
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
processingorshipped. Orders that haven't reachedprocessingyet, 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 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. |
| 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 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:
- Account number: a Xero contact whose account number matches the accounting ID on the SparkLayer customer. See how to set accounting IDs.
- 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. 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:
- The company name metafield, if it's filled in. For example, "The Company".
- If that name is taken, the company name followed by the customer's first and last name. For example, "The Company (Jane Doe)".
- 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 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, 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.
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.
On Shopify, an order paid by invoice or on account moves through these stages:
Draft order
Complete the draft
Processing
Xero invoice
Fulfil
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.
Set up Xero
Check the requirements, connect your Xero organisation, then choose your settings.
Requirements
- The Pro or Enterprise plan. See Plans and features.
- A Shopify store connected to SparkLayer. See Shopify.
- A Xero organisation to connect.
Connect Xero
- In the SparkLayer Dashboard, go to
SparkLayer Wholesale,Integrations,Partners (in your Shopify admin). - Under Accountancy, turn on the switch next to Xero.
- Sign in to Xero when it opens. Xero shows the data SparkLayer needs access to (see the FAQs).
- If your Xero account has several organisations, choose the one to connect. You can connect one organisation to your SparkLayer Dashboard.
- Back in SparkLayer Wholesale,Integrations,Partners (in your Shopify admin), 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, this decides what happens. Enabled: SparkLayer creates a new Xero contact from the customer data it holds (see 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. |
| 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. |
| 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:
- In SparkLayer Wholesale,Integrations,Partners (in your Shopify admin), open Xero.
- 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
- In the SparkLayer Dashboard, go to SparkLayer Wholesale,Integrations,Partners (in your Shopify admin).
- 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).
FAQs
Turn the integration off in SparkLayer Wholesale,Integrations,Partners (in your Shopify admin), under Accountancy. This removes the connection to your Xero organisation. See Turn off the integration for what happens next.
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.
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.
Check that:
- The integration is turned on in SparkLayer Wholesale,Integrations,Partners (in your Shopify admin), under Accountancy.
- The order is
processingorshipped. Orders that haven't reachedprocessingyet, 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.
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.
Last updated