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 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 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 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, the invoice is also created once the order reaches the processing status you can learn more about configuring these methods docid\ ibikczvhm085bkejiffyv 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 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 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 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 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 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