Xero

IXO Commerce sends sales orders, purchase orders, payments and refunds to Xero, and pulls account payments back from Xero into IXO. Two schedulers handle this: the update scheduler and the update payments scheduler.

How it works

1. When an order is placed in IXO, it is sent to Xero as a draft invoice. Cancelled and returned lines are left off.
2. Once every remaining line on the order has been despatched, the invoice is approved in Xero and the order is locked in IXO.
3. Only then are payments on the order sent to Xero.

No payments are sent to Xero for orders that haven't been fully despatched.

Xero only accepts payments against approved invoices, so payments taken in IXO stay unacknowledged until the invoice is approved. They are picked up by the next run of the update payments scheduler after that.

In Xero, an approved invoice sits in the Awaiting Payment tab until it is paid in full. The Xero API calls this status Authorised, so you may see either term.

Update scheduler

Calls the following functions, in this order.

getItems

Gets the default cost price of all items in Xero.

sendOrdersToXero

• Gets all orders from IXO that haven't already been acknowledged, excluding orders with a status of draft, abandoned or quote.
• Creates the customer as a contact in Xero if they don't already exist.
• Makes sure all sold products exist as items in Xero, and adds any that don't.
• Leaves out cancelled and returned lines.
• Posts the invoice to Xero as a draft.

If an order has no lines left once cancelled and returned lines are removed, and the order total is 0, IXO sends the Deleted status so that Xero deletes the invoice.

updateUnauthorisedInvoicesInXero

• Gets a list of draft invoices from Xero.
• Checks whether every line on the matching IXO order (other than cancelled or returned lines) has been despatched.
• If it has, approves the invoice in Xero and marks the order as locked in IXO.

Until this happens, the invoice stays as a draft and no payments for the order can be sent.

sendPurchaseOrdersToXero

• Gets all submitted purchase orders that haven't been acknowledged.
• Creates the supplier as a contact in Xero if they don't already exist.
• Makes sure all products exist as items in Xero.
• Creates the purchase order in Xero.

Purchase order lines use the IXO Commerce nominal code as the Xero account code.

Update payments scheduler

Calls the following functions, in this order. All of them work only on orders whose Xero invoice has been approved. Draft invoices are ignored.

sendOrderPaymentsToXero

• Gets a list of approved invoices awaiting payment from Xero.
• Matches unacknowledged payments in IXO to each invoice by Sales Order ID.
• Creates each payment in Xero individually, as long as it fits within the amount outstanding on the invoice.

If the payments don't fit, IXO nets off all pending payments and refunds on that order and sends a single payment to Xero instead:

• References are passed across.
• The payment type is passed unchanged if every payment is the same type. If the types differ, Other is used.

If the net amount is still more than the amount outstanding, nothing is sent. The invoice stays in the Awaiting Payment tab in Xero and needs to be dealt with manually.

getPaymentsFromXero

• Gets a list of customers in IXO with a credit balance.
• Gets fully paid invoices from Xero for the contact IDs matching those customers.
• For each Sales Order ID, compares unacknowledged account payments in IXO against the amount paid on the Xero invoice.
• Creates an account payment in IXO for the amount paid, if one doesn't already exist.
• Marks account payments as acknowledged where they fit within the amount paid on the invoice.

sendOrderRefundPaymentsToXero

Refunds are only sent once the order's Xero invoice is fully paid.

Non-account refunds

• Gets all unacknowledged non-account refund payments on IXO orders whose Xero invoice is paid.
• Creates an approved credit note in Xero and adds a payment to it.

Account refunds

• Gets all unacknowledged account refund payments on IXO orders whose Xero invoice is paid, where the net account payment total is negative.
• Creates an approved credit note in Xero. The credit then needs to be allocated manually against an invoice balance in Xero.

Setup

Required details

Key files

Optional

Website config

Set the website config calculatevatperline so that IXO calculates VAT per line. This matches how Xero calculates VAT and avoids rounding differences between the two systems.