Xero

join our early access beta if you’d like to join the beta and help shape the integration, please get in touch with docid\ nnuw1g9z7eaj4m78vk7t9 we’d love to involve you! 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 join our early access beta please note that the xero integration is currently in beta while we’re working to ensure a smooth and reliable experience, you may encounter occasional data inconsistencies or issues if this occurs, our support team is on hand to help, and you can disable the integration at any time if you prefer to pause its functionality 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 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 https //docs sparklayer io/xero#zr11g 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 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 invoice creation for payment on account orders default on order 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 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 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 docid\ ibikczvhm085bkejiffyv 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 https //docs sparklayer io/xero#zr11g 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 docid\ ywm70oquosykooiqb4z4g 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 the line item’s sku is used as its description 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 (typically stored via metafields) 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, the invoice sync will fail and be rejected 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 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 payment visibility if https //docs sparklayer io/payment methods#payments 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 docid\ ywm70oquosykooiqb4z4g , 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 on docid\ ywm70oquosykooiqb4z4g 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 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 how do i disconnect from xero? to disconnect from your xero organisation from sparklayer you will need to login to your sparklayer dashboard and navigate to integrations > partner integrations > accountancy > xero then disable the integration this will remove the connection from your xero organisation please read further information here on what happens when the integration is disabled https //docs sparklayer io/xero#ojttc does the integration work for d2c orders? no the integration only supports b2b orders that are created through your platforms connection with sparklayer direct to consumer (d2c) orders are not included in the sync and will not be pushed to xero as invoices what level of access does the integration require in xero? 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 customers cannot access their invoice from the my account section if links to invoices are not showing in a particular customers my account section, it could be due to a number of reasons ensure the integration is enabled in the sparklayer dashboard by navigating to integrations > partner integrations > accountancy > xero ensure the order is in a processing or shipped fulfilment status we do not create invoices for orders which are in the awaiting merchant status ensure an invoice exists in xero for the given order in some cases it may take a little time for orders to sync across if there appears to be a large delay, or an invoice has not been created, please contact support, providing the customer and order id ensure the invoice is not in a draft status xero does not provide public urls for invoices which are in a draft status if you are still experiencing issues after checking the above, or invoice urls are not showing for all of your customers, please contact support the address on the invoice is different to the address the customer used during checkout the address(es) used on an invoice in xero come directly from the related contact record whilst in sparklayer we allow for a customer to have multiple billing & shipping addresses, xero only offers support for a single billing and shipping address per contact record we will only use the addresses held in sparklayer if we create the contact as part of the contact matching and creation flow detailed above if any of these addresses change after the contact has been created, we will not automatically update them 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