XeroConnect integration

Overview

XeroConnect is a B2B solution that allows suppliers to deliver invoices, credit notes and confirm payment for supplier invoices in a cost effective way using secure communications with acknowledgement of delivery that has been designed to leverage existing building-blocks most medium-to-large organisations as part of their ERP and customer facing solutions.

XeroConnect uses Xero's RESTful API for all communication.

Core Benefits of XeroConnect

The core elements of XeroConnect are:

  • Authenticated and secure communication between the Supplier system and the Xero organisation with guaranteed delivery directly into the connected Xeros' accounting system.
  • Invoices can be sent with differing levels of detail / grouping dependent on customer requirements.
  • Invoices processed by direct debit or other automatic means can also be marked as paid, requiring no interaction on behalf of the Xero organisation user.
  • Credit Notes can be raised against Invoices and sent via the same mechanism.
  • Attachments, including contract of sale, Tax Invoices can also be attached to the Invoice for compliance with the relevant taxation requirements - a significant saving for accountants and bookkeepers having to scan and attach.
  • Additional business processes, like delivery of invoices as a business reaches an agreed credit limit are able to be delivered in the same seamless way.
  • Designed to re-use functional building blocks of medium-to-large enterprise solutions to reduce development time.

XeroConnect Setup

Connect to Xero

To setup a XeroConnect customer, a Xero user must grant the Xeroconnect Supplier access through our standard oAuth flow from within the customer portal of the XeroConnect Supplier. Along with a user's oauth tokens, XeroConnect will obtain organisation details including:

  • level of invoice detail required by the XeroConnect customer (optional)
  • account preferences for invoices - including splitting based on product category (eg: fuel and instore purchases may be sent to different account codes)
  • Account preferences for any fees, including access and per user charges (eg employee cards)

To accomplish this, a user will login to the Suppliers portal and click a 'Connect to Xero' button and be redirected to Xero's authorization screen. A user enters their Xero login details and selects which org to authorise. The connection is authorised and the user is redirected back to the payment service portal. The payment service is now authorized to access Xero's API and complete the setup process.

Setting up Customer Preferences

Once a customer has connected their Xero org, the XeroConnect Supplier then has access to get information from the Xero customers account, including:

  • Organisation details - - including their Name which should be displayed within the Supplier portal and their LegalName which can be used to verify the entity; other fields that maybe relevant for multi-country Suppliers are the BaseCurrency of the organisation and their CountryCode to validate that their Xero organisation is operating in the correct country.
  • Account details - allowing the Xero customer to assign particular products or product categories to particular account codes streamlines the processing within Xero significantly, especially for invoices sent which may have a large number of line items. By assigning an account code to each line in the Invoice, the Xero customer may not have to do any processing in order for the invoice to be processed and paid in Xero. There is more information on integration best practices which shows examples of Account code mapping; but some common account code setups for suppliers might be:
    • Product category account codes; eg Fuel and in-store purchases
    • Shipping expenses separated from product purchases
    • Fees account (optional)
  • Contact details - allows the Xero customer to assign either an existing supplier contact or create a new supplier contact to any invoices sent via XeroConnect. For instance, the Supplier name might be called 'National Plumbing Supplies Pty Ltd' but the Xero customer might have that supplier as 'Plumbing Supplies'. By allowing the XeroConnect customer to select their Supplier, previous information about purchases and historical information is not orphaned.
  • Invoicing Detail (optional) - commonly, customers may prefer to get different levels of detail for their invoices, which occurs when delivered via other means (email, postal). Some common ways XeroConnect customers may want their invoices received are:
    • As a monthly summary invoice - containing supplier invoice references and total as a line item
    • A monthly summary invoice grouped by Product categories containing number of units sold per product category and line total.
    • A monthly summary invoice grouped by Supplier location containing total amount purchased per supplier location.
    • A monthly summary invoice grouped by employee or supplier card containing total amount purchased per employee or supplier card.
    • An individual Summary Invoice for every invoice.
    • Itemised invoice
    • Itemised invoice sorted by Product categories
    • Itemised invoices grouped by employee or supplier card

    Note that these are only examples, and the XeroConnect Supplier should work with their own customers to determine what are appropriate invoice details that may be required

    XeroConnect does not support any of the above natively and it is up to the XeroConnect Supplier to provide those within their system.

Account for Fees or Shipping Charges

Shipping charges are generally charged per invoice and account fees are generally charged per payment period.

If there are shipping charges or monthly fees (either access fees for the use of the portal or per supplier card (eg fuel card) cards), you may need to record these against a different account codes. Perform a GET on the Accounts using the WHERE clause to retrieve only accounts where Class== “EXPENSE”. Let the user pick an account and save the choice for later.

Account for Purchases

Similar to accounting for fees, allowing the Xero organisation to set the account code(s) for purchases will allow the invoices to be processed seamlessly. When selecting an account for purchases, it is recommended that the Class=="DIRECTCOSTS" or Class=="CURRLIAB"

Account for Purchases

Regardless of the level of detail that may have been set or set by default by the XeroConnect Supplier, the delivery of the Supplier Invoice is done by performing a POST to the Invoices endpoint. Where the customer as a direct debit or agreed commercial arrangement with the supplier, the Invoice can be set to either DRAFT, SUBMITTED or AUTHORISED - these are explained further here.

When generating the Invoice, the Invoice contact should be set to the Contact ID set by the Xero customer within the Supplier Portal.

If the XeroConnect Supplier has allowed for one or more account codes to be set (eg: based off product categories or supplier cards or shipping/postal expenses), these can be set within each line item of the Invoice sent down based on the invoice details, along with the DueDate of the Invoice which would identify when the Supplier expects payment or will process the direct debit.

Where the XeroConnect Supplier supports PDF generation of Invoices, these can also be associated with the Invoice by calling the Invoices/{InvoiceID}/Attachments endpoint to add the PDF attachment to the invoice.

Sending an Invoice for Fees

Where there are fees for access or charges per month per employee or supplier card, these can be delivered either as part of the summary invoice or as an individual invoice sent to the Xero organisation. Regardless, the LineItem for the invoice would include the fees account code set above.

Where the XeroConnect Supplier supports PDF generation of Invoices for Fees, these can also be associated with the Invoice in the same manner as a standard invoice as above.

Sending Credit Notes (optional functionality)

If the Supplier supports Credit Notes, those can also be delivered in a similar way to the delivery of invoices. Credit Notes are created by using the POST CreditNotes call and the XeroConnect Supplier should use the same Contact as the Invoices being sent and have a type of ACCPAYCREDIT. The XeroConnect Supplier can also allocate amounts to a specific InvoiceID which will make matching direct debit payments made to Invoices raised - this is particularly important where the Xero organisation has configured to send individual invoices, not using monthly summaries.

Where the XeroConnect Supplier supports PDF generation of Credit Notes, these can also be associated with the Credit Note in a similar manner to the Invoice attachments by calling the CreditNotes/{CreditNoteID}/Attachments endpoint to add the PDF attachment to the credit note.

Show Invoice is Paid

If the XeroConnect Supplier is using direct debit, they can also send through the payments received once the direct debit has been successfully processed. This is achieved by performing a PUT payments call and can identify the original invoice id sent to Xero and the amount paid.

Where the XeroConnect Supplier is using direct debit and sending payments to Xero, it is recommended that this processing occur once the Supplier has received confirmation from their banking institution that the funds have been received, not when the Supplier attempts the direct debit as this may result in the Invoice within Xero being marked as paid which will not allow the invoice to be altered subsequently.