Xero

Requirements

Plan: Merchants must be signed up to the Professional or Enterprise plan Platform: Merchants must be using Shopify

Introduction

Xero provides online accounting tools for managing finances, invoices, and customer records. With the SparkLayer integration, your B2B orders automatically sync to Xero to create invoices and contacts - reducing manual data entry and removing the need for additional apps or systems to keep your platforms in sync.

Getting started

To get started, login to your SparkLayer dashboard and navigate to Integrations -> Partner Integrations -> Accountancy -> Xero and enable the integration. You will then be redirected to Xero to complete authentication. You will also be notified about which data we require access to at this stage.

Please note If your Xero account is associated to multiple organisations then you will be requested to select which organisation you want to connect with SparkLayer. Only one organisation can be connected to your SparkLayer dashboard.

Once you are connected, you can navigate back to the Partner Integrations page and modify the integrations configuration. You'll need to follow the steps below ("Configuration") to complete the setup.

Configuration

Below details the configuration options available in the integration.

Setting	Description
Automatic Contact Creation	Default: Disabled Controls whether SparkLayer should create contacts in Xero during the invoice synchronisation process. When creating invoices, each invoice must be associated with a contact in Xero. We first attempt to match an existing contact (as outlined in the Contact Matching section). If no match is found, this setting determines what happens next: Enabled - SparkLayer will automatically create a new contact in Xero using the customer data held in SparkLayer. You can read more about contact creation here. Disabled - SparkLayer will not create new contacts in Xero. This assumes that contacts are either: Being created by another system, or Being managed manually within Xero. In this case, if no matching contact is found, invoice creation may fail.
Default Line Item Account Code	Default: 200 Specifies the Xero account code that invoice line items will be associated with. For example, 200 You can find your account codes within the Chart of Accounts section in Xero.
Shipping Line Account Code	Default: Falls back to what is configured for "Default Line Item Account Code" Allows you to specify a Xero account code to use for shipping line items. For example, 260 If left empty, the account code used will fallback to what is configured for the Default Line Item Account Code setting. You can find your account codes within the Chart of Accounts section in Xero.
Invoice creation for Payment on account orders	Default: On order Controls when an invoice should be created for orders using the payment on account payment method. On order will create an invoice for the whole order one it reaches the processing status. On shipment will create an invoice per shipment, once any fulfilments on the order have been created. You can read more about payment on account orders below.
Invoice Line Item Mapping	Map Line Items to Item Codes Default: Disabled Controls whether or not, during the creation of invoices, we map invoice line items to Xero Items (Products) based on the SKU held for the line item in SparkLayer. Enabled - When creating an invoice, we will map the line item to an existing item (product) held in Xero based on the SKU. If no item in Xero exists for a given SKU, the invoice will not be created. Disabled - When creating an invoice, we will not attempt to map line items to items (products) held in Xero. You can read more about Invoice Line Item Mapping below.
Tracking categories	Default: None Allows you to specify which tracking category or categories we should map line items to when creating SparkLayer invoices. Mappings pairs should be formatted as a comma-separated list in the format: CategoryName:Option For example; Channel:B2B,Source:SparkLayer In this example: The Channel tracking category will be set to B2B The Source tracking category will be set to SparkLayer Note: Xero supports a maximum of two tracking categories per line item. Any additional mappings beyond this limit will be ignored.

Invoice Creation

SparkLayer automatically creates invoices in Xero for eligible customer orders as soon as the order is received from your platform.

Please note This process runs in the background to keep the checkout experience fast and uninterrupted, which means there may occasionally be a short delay before the invoice appears in Xero.

Orders eligible for invoicing

Whether an invoice is created depends on several conditions, including your integration settings and the specific details of the order.

Item	Details
Fulfilment status	We only create invoices for orders that are in either the processing or shipped fulfilment status.
Payment method	Invoices are generated only for orders using either the Payment by Invoice or Payment on Account payment methods. Payment by Invoice For Payment by Invoice orders, the invoice is created as soon as the order reaches the processing status. Payment on Account For Payment on Account orders, invoices are created depending on the integrations configuration. You can read more about payment on account orders here. You can learn more about configuring these methods our guide here

Payment on account orders & split shipments

The integration configuration allows you to decide when invoices are created for orders that use the payment on account payment method. Invoices can be created either on order or on shipment.

If you have configured your integration for on order then an invoice will be created when the SparkLayer order reaches the processing state.

If the integration is configured for on shipment then an invoice will be created at the time an fulfillment has been fulfilled on the order. This handling caters for split fulfillments as will we will create an invoice per fulfillment, containing only the line items fulfilled.

Customers will be able to download all invoices associated with an order from their my account section.

Shipping In the case of split shipments, the shipping method associated with the order will always be attached to the invoice created for the first shipment on the order.

Rounding issues Split shipments are in some cases susceptible to rounding issues. This is due to the differences between how your platform, SparkLayer and Xero calculate tax for line items across shipments.

If we detect a rounding issue on an invoice, we will automatically apply a "Rounding adjustment" line item to the affected invoice, assigned to Xeros rounding account code 860. This ensures totals on the Xero invoices match the order in SparkLayer.

How invoices are created

Invoices are generated using the Xero API. You can verify that an invoice was created via the SparkLayer integration by checking the History & Notes section in Xero, where an automatic note identifies SparkLayer as the source.

Each invoice is created using a combination of:

Data from the SparkLayer order

Your integration configuration

Relevant settings within Xero

The specific fields and logic used are outlined below.

Item	Details
Invoice Status	By default, invoices are created in a Submitted status in Xero. In some cases, invoices may be created in a Draft status if we are unable to determine a valid due date.
Contact	We attempt to match the invoice to an existing Xero contact using the customer details from the SparkLayer order. If a match is found, the invoice is associated with that contact. You can read more about how contact matching and syncing works in detail here.
Billing Address	The billing address shown on the invoice is taken from the billing address associated with the matched Xero Contact.
Due Date	The due date calculated for an invoice is dependant on three factors: The order date The payment type The customers payment terms
Due Date for Payment by Invoice orders	For orders using the payment by invoice payment method, the due date is set to the order date.
Due Date for Payment on Account orders	For orders using the payment on account type, the due date is calculated in the following hierarchical order: If the customer has net terms configured in SparkLayer, these are applied to the order date. You can read more about configuring net terms herehere. If not, any payment terms configured for the contact in Xero are applied. If neither of the above are set, any global payment terms configured in Xero are applied. If none of these are set, the due date defaults to the order date.
Line Item	Item Code If you have configured your integration to map line items to item codes in Xero, we'll use the line items SKU as the item code. Account Code Each line item uses the default account code set in your integration settings. Description A combination of the line item’s SKU and parent / child name is used as its description. If the item also has any custom attributes associated with it, these are also appended. Quantity The quantity matches the value recorded on the order in SparkLayer. Unit Amount, Line Amount & Tax Amount All monetary values, unit amount, line amount, and tax amount, are calculated by SparkLayer and passed directly to Xero.
Shipping	We attach shipping details to the invoice as a line item at the bottom of the invoice. We'll use the shipping method name & SKU to form the line item description alongside the relevant monetary values. The account code used is the same as other line items, using the default account code set in your integration settings.
Tracking	Xero allows you to associate each invoice line item with up to two tracking categories. If tracking category mappings are configured in the integration settings, all line items on generated invoices will automatically be assigned to the specified tracking categories.

Please note Xero supports only a single billing address per contact. If a SparkLayer customer has multiple addresses, the billing address shown on the invoice may differ from the one stored in SparkLayer. We sync a customer’s billing address only when the contact is first created in Xero. Any changes made afterwards in SparkLayer are not automatically reflected and may require manual updates on the invoice or Xero contact record.

Mapping Line Items to Xero Items (Products)

In the integration configuration section Invoice Line Item Mapping you may enable Map Line Items to Item Codes.

This setting assumes you have already pre-configured items in Xero for all of the products in your platform, using the product SKU as the item code in Xero.

When enabled, we'll map each line item to its corrersponding item in Xero based on the SKY held in SparkLayer.

If a line item is for a SKU which does not exist as an item (product) in Xero then we'll fail to create the invoice. Once any missing items are added, the invoice will be created.

Viewing Invoices

Once an invoice has been created in Xero, customers can access it directly from the My Account section of your store. When the invoice is ready, a View & Download Invoice button will appear on the relevant order.

Selecting this button will take the customer to the publicly accessible invoice URL generated by Xero. If this button is not visible, please review our troubleshooting steps below.

Contact matching & creation

When creating an invoice, we first attempt to associate it with the correct Xero contact using the customer details from the SparkLayer order.

How contact matching works

Contacts are matched in the following order:

Account number match - we check for an existing Xero contact with an account number that matches the accounting ID configured against the customer in SparkLayer. Read more on how to configure accounting IDs

Email match - If no account number match is found, we attempt to match using the customer’s email address.

If a match is found for either of these conditions, the invoice is associated with the matching contact.

Multiple contacts for a single email

In SparkLayer, email addresses are unique - only one customer account can exist per email address. In Xero, email addresses are not unique, meaning multiple contacts can share the same email.

If multiple Xero contacts exist for the customer’s email address, we will create the invoice for the first matching contact returned by Xero.

Please note If your organisation uses multiple contacts with the same email address, we recommend configuring unique account numbers for each contact to ensure reliable matching.

Automatic contact creation

If no existing contact can be matched using the methods above, SparkLayer will automatically create a new contact in Xero using the customer data from the order. This behaviour is controlled by the Automatic Contact Creation setting in your integration configuration.

Data synced on contact creation

When a contact is created in Xero, the following information is synced once and is not automatically updated if changes occur later in SparkLayer:

Company name

First name & last name

Email address

Billing & shipping address (based on the order being invoiced at the time of matching)

Payment terms (if configured via the payment terms metafield). Contacts are created using Xero’s days after bill date payment term type.

Unique contacts in Xero

Xero requires each contact name within an organisation to be unique. To ensure successful contact creation, we use a multi-stage naming strategy when creating new contacts.

Contact creation stages:

Stage 1: If the SparkLayer Company Name metafield is populated, this is used as the contact name. Example: “The Company”

Stage 2: If a contact with this name already exists in Xero, we append the customer’s first and last name. Example: “The Company (Jane Doe)”

Stage 3: If the above name is also already in use, we fall back to using only the customer’s first and last name. Example: “Jane Doe”

If all of the above naming conventions fail to create a unique contact in Xero, to ensure an invoice is created we'll attempt each again but with a timestamp appended to the end. Example: "The Company (20260520093837)"

Payment Visibility

If payment visibility is enabled in your SparkLayer Dashboard configuration then you will see any payments made against invoices in Xero reflected as transactions on the order in SparkLayer.

We track the following Xero payment types as transactions on orders:

Payments / Offline Payments

Credit Notes applied to invoices

Overpayments applied to invoices

All payment types will be displayed as transactions on the order and modify the balance due on the order held in SparkLayer.

Please note Even if the payment visibility setting is disabled we will continue to track Xero payments as transactions on SparkLayer orders in the background.

Refunds

We do not currently track refunds on card payments as refunds are not typically applied directly to an invoice but instead reflected as a credit note on the customer account.

We do however track when any of the above payment types are removed from an invoice, and reflect this accordingly on the order in SparkLayer.

Credit Limits

As SparkLayer tracks payments made against invoices, if you have configured credit limits and account balances as outlined in Credit, Net Terms, & InvoicingCredit, Net Terms, & Invoicing, any payments made on Xero invoices for Payment on Account orders will automatically modify the customers unpaid balance accordingly.

Xero Contact Credit Limits In Xero you ahve the ability to set credit limits for contacts. Unforunately this information is not exposed in the Xero APIs. As a result, we’re unable to automatically sync credit limits configured in Xero with customers in SparkLayer.

To apply credit limits to customers, you will need to follow our documentation onCredit, Net Terms, & Invoicingon

Credit Notes

Whilst we are able to sync credit that's been applied to invoices as a payment, we are currently unable to reflect any unallocated credit held against the contact record in Xero, against the customer balance in SparkLayer.

Currently, in order to keep these in sync we'd recommend manually modifying the balance on the customers metafield to reflect any unallocated credit. Once you have allocated the credit to an invoice, you will then need to modify the balance back accordingly.

Disabling the integration

To disable the integration, log in to your SparkLayer Dashboard and navigate to Integrations → Partner Integrations → Accountancy → Xero, then toggle the integration off.

Please note If the integration is disabled, all related features will stop working.

No invoices will be created for orders placed while the integration is disabled.

Customers will no longer be able to access their Xero invoices via the link in their My Account section.

FAQ's

When connecting SparkLayer to your Xero organisation, you’ll see a list of the exact permissions requested. We follow Xero best-practice and only ask for the minimum access needed for the integration to function. Currently, this includes:

View & manage contacts - To match invoices to existing contacts and create new contacts for SparkLayer customers if your integration configuration allows.

View & manage business transactions - To create invoices in Xero for SparkLayer B2B orders and in the future, view payments made on invoices.

View organisation settings - To read configuration details such as global payment terms when calculating invoice due dates.

Troubleshooting

Below are some common issues and steps to help resolve them. If your issue isn’t listed, or the problem persists after following these steps, please contact our support team.

Known limitations

Please note the following:

Multiple tax rates per line item are not currently supported.

Invoice creation in Xero is one-way. Any changes made to invoices in Xero, such as modifications to line items or customer details will not be reflected back in SparkLayer or your platform.