Extensions › Xero
Xero Extension
Send your orders to Xero as they happen. Each order becomes an invoice with its payments, refunds become credit notes, and an invoice paid in Xero marks the order paid in your store. 14 parts.
Quick links
Where to find it:WP Admin › EasyCart › Extensions › Xero
Quick start
Set up in four steps
The short version. Each step is covered in detail below.
Install
On EasyCart › Extensions, install Xero. It comes with your Premium license and installs WP EasyCart Premium with it.
Connect
Press Connect to Xero, sign in, choose your organisation and allow access.
Check the suggestions
Look over the suggested accounts, tax and payment accounts, which come from your own chart of accounts.
Switch on sending
Switch on Send orders to Xero. Orders from that day on go as they happen; Tools sends earlier ones.
What goes to Xero
Invoices
Every order as an invoice to the customer’s contact, with its lines, discounts, shipping and the exact tax it charged.
Payments and refunds
Payments into the account you choose for each payment service, and refunds as credit notes, paid back from where the money went.
Back from Xero
An invoice paid in Xero marks the order paid in your store, as it happens.
Getting started
Connect your store to Xero
What you need, connecting your organisation, and connecting with an app of your own.
Before you start
What the extension needs, and where to find it
no stored settingsWhat you need
A WP EasyCart Premium license. Xero is a Premium extension. Install it from EasyCart › Extensions › Xero; that also installs WP EasyCart Premium, which runs the sending in the background, keeps the connection’s keys encrypted and delivers the extension’s updates.
WP EasyCart and WP EasyCart PRO 6.0.2 or newer, and WP EasyCart Premium 1.1.0 or newer. Your server’s PHP needs the OpenSSL or Sodium extension, which almost every host has turned on.
A Xero organisation, and a Xero login that can connect apps to it. Some Xero plans limit how many invoices you can send a month, and every store order becomes an invoice: check your plan before you send a busy store’s orders.
A currency Xero takes. Your store’s currency must be the organisation’s base currency, or a currency added in Xero under Settings › Currencies ( that needs a Xero plan with multi-currency ). An order in any other currency is held, and its card says why.
Where to find it
WP Admin › EasyCart › Extensions › Xero. The page has a Connection card at the top, then Sending, Accounts, Tax, Payments, Tools and Activity.
What it sends
Orders, with their customers, payments and refunds. Every order becomes a Xero invoice, its payments are recorded against it, and refunds become credit notes. Nothing is sent until you switch on Send orders to Xero, and then only orders from that day on: earlier orders go only when you send them.
Connect Xero
Sign in to Xero and choose the organisation this store sends to
3 choicesConnect with the WP EasyCart app ( recommended )
- Open EasyCart › Extensions › Xero.
- In Connection, leave WP EasyCart app chosen and press Connect to Xero.
- Sign in to Xero, choose the organisation, and press Allow access. Xero sends you back to the settings page.
- Connection shows the organisation’s name, country and currency. The accounts and tax rates below now come from your own chart of accounts.
You sign in on Xero’s own page: the store never sees your Xero password.
How to connect
WP EasyCart app needs nothing set up in Xero, and Xero tells your store about payments as they happen. Your own Xero app is for developers who run their own app in the Xero developer portal, and Custom connection is for Xero’s paid custom connections; see the next part.
More than one organisation
If you tick more than one organisation on Xero’s screen, the Connection card asks which one this store sends to. Choose it and press Use this organisation; the store gives up its access to the others.
Already connected
If Xero’s screen lists your organisation under “Already connected” ( it was connected before, for example to this store before the extension was deleted ), just press Allow access: the store picks the organisation up again.
Disconnect
Ends the connection in Xero too. Nothing already in Xero changes, and sending stops until you connect again. The organisation’s accounts and tax rates are forgotten on this site. What was sent is remembered, so connecting the same organisation again carries on where it stopped.
Connect again
When Xero ends a connection ( someone removed WP EasyCart under the organisation’s connected apps in Xero, or the connection was not used for 60 days ), the card turns red and says “Xero needs you to connect again”. Orders wait, and go once you press Connect again.
Staging copies
A copy of your site ( a staging site or a clone ) never sends to Xero: its Connection card says “This looks like a copy of your store”. Press This is my live store if the copy has become your live store, or Forget it here on a staging copy; the live store stays connected.
💡 Note: Connecting needs a current WP EasyCart Premium license. Once connected, the store sends nothing until you switch on Send orders to Xero under Sending, so you can check the suggested accounts and tax settings first.
Your own Xero app
For developers with an app of their own, and for Xero custom connections
3 settingsWhen to use it
Only if you run your own app in the Xero developer portal and want the store to connect with it, or you bought a custom connection from Xero. Most stores should use the WP EasyCart app.
Set up the app
- In the Xero developer portal ( My Apps ), make a Web app.
- In EasyCart › Extensions › Xero, choose Your own Xero app. The card shows your store’s redirect URI and webhook URL, each ready to copy.
- Give the app the redirect URI. It ends with /wp-admin/admin-post.php?action=wpec_xero_return.
- For payments made in Xero to arrive at once, add a webhook to the app for Invoices, with the webhook URL shown.
- Paste the app’s client ID and secret, and the webhook key if you added one, then press Connect to Xero.
When you connect, the store asks for offline_access, accounting.settings, accounting.contacts, accounting.invoices and accounting.payments.
Client ID
From the app’s Configuration in the Xero developer portal.
Client secret
From the same page. Kept encrypted by WP EasyCart Premium; the box shows “Saved. Type to replace it.” once it is stored.
Webhook key ( optional )
The key Xero shows for the app’s webhook. Without a webhook, the store checks Xero for payments every 15 minutes instead.
Custom connection
A custom connection is Xero’s paid connection for one organisation. Choose Custom connection, paste its client ID and secret, and press Connect to Xero: there is no sign-in, and the store connects to the organisation the custom connection was authorised for.
What goes to Xero
Orders, accounts, tax and payments
What each order becomes in Xero, and the settings that decide how.
What each order becomes
Invoices, payments, credit notes and voids
no stored settingsEvery order
An invoice to the customer’s contact, with its lines, discounts, shipping, fees, tip, duty and tax. It arrives approved, or as a draft when you choose ( Sending ).
An order paid at checkout ( card, PayPal, Square … )
A payment on the invoice, into the account chosen for that payment service under Payments, so the invoice shows as paid.
An order not paid yet ( bank transfer, pay by invoice )
The invoice waits in Xero. Once the order is paid in your store, its payment is recorded; once the invoice is paid in Xero, the order is marked paid ( see Paid in Xero ).
A gift card redeemed
A payment on the invoice from your gift card liability account ( Accounts › Gift cards ). A gift card sold is a line on that account.
A refund
A credit note. It is set against whatever is still due on the invoice, and the rest is paid back from the account the money went into ( Refunds paid by hand for refunds you gave outside the payment service ).
An order changed after it was sent ( lines, totals )
The invoice is updated to match.
An order no longer paid
Its payment is removed from the invoice.
An order cancelled or deleted
Its invoice is voided in Xero ( a deleted order after the 15 minutes you have to undo it ).
An invoice paid in Xero
The order is marked paid in your store; see Paid in Xero below.
The lines on an invoice
Each product line keeps its quantity, price and share of the order’s discount, with the product’s name and options as its description, on the account chosen for products ( products are not made as Xero items ). Shipping ( Shipping: Ground ), fees, tips and duty are lines on accounts of their own. A coupon bigger than the items it could take off is a Discount line. When the store and Xero round tax a cent differently, a Rounding line keeps the totals the same.
The tax
Always the figure the order charged. Xero works the tax out itself from each line’s rate, so the store works it out the same way first; see Tax.
Contacts
An order from a customer account goes to their Xero contact, found by their customer number ( EC-12 ), then by email, or made the first time. Guest orders go to a contact of their own each, matched by email, or all to one shared contact ( Guest orders, under Sending ). When a customer already in Xero changes their details in your store, their contact is updated, but never renamed: a name you changed in Xero stays. A new contact whose name Xero already has gets the email address after the name.
Numbers and dates
Each invoice carries the order number, with WEB- before it by default ( WEB-1042 ), or your WP EasyCart PRO invoice number when the order has one. Its reference is always the order number ( Order 1042, with the PO number when there is one ). It is due on the order’s due date when it has one ( pay by invoice terms ), else on the order date. Xero numbers credit notes itself; their reference is Refund for order 1042.
In the background
Sending runs in the background, usually within a minute, so it never slows a checkout. When Xero is busy, the store waits and tries again. When a setting or Xero needs you, the order is held with the reason: on the order’s card and in Activity.
⚠️ Careful: Once an invoice has a payment you added in Xero, or a payment reconciled with your bank, the store does not change it when the order’s total changes afterwards. The order is held with the reason: change the invoice in Xero, or remove the payment there and press Send again.
Sending
Which orders go to Xero, and how their invoices look
11 settingsSend orders to Xero
Orders, payments and refunds go to Xero as they happen. Switching it off pauses sending; nothing is lost. Switching it on for the first time, with no date in Send orders from, starts from today, so earlier orders are not sent by surprise.
Send orders from
Orders placed on or after this date ( YYYY-MM-DD ). Earlier orders go only when you send them: Tools › Send past orders, or Send to Xero on the order.
Send an order
When paid keeps unpaid and abandoned orders out of Xero. Orders you invoice ( pay by invoice ) go when the invoice is issued. When placed sends every order as it is placed.
Invoices arrive in Xero as
Approved invoices take their payments and refunds at once. Draft invoices wait for you to approve them in Xero; their payments and refunds follow once you do.
Invoice number
The invoice number in Xero: Your invoice number, else the order number, The order number, or Xero’s next number. The order number is always in the reference.
Before the order number
Keeps store invoices apart from the ones you raise in Xero ( WEB-1234 ).
Guest orders
A contact each makes a Xero contact for each guest, matched by email. One shared contact sends every guest order to one contact.
Shared contact’s name
With One shared contact: the Xero contact guest orders go to.
Invoice theme
The Xero branding theme for these invoices and credit notes.
Mark orders paid when paid in Xero
An unpaid order ( pay by invoice, bank transfer ) is marked paid once its invoice is paid in Xero.
Order status once paid in Xero
Which paid status the order moves to. Left as WP EasyCart’s usual paid status, it is Bank Transfer Received ( Direct Deposit Received on older stores ).
Accounts
Where each part of a sale goes in your chart of accounts
7 settingsHow the accounts are chosen
Left as Suggested, WP EasyCart picks the closest match in your chart of accounts, and the box says which. Choose another account to use your own.
Products
Sales of your products. Suggested: account 200 Sales, else a revenue account named Sales.
Shipping
What customers pay for shipping. Suggested: a revenue account with shipping, freight, postage or delivery in its name, else the products account.
Gift cards
Gift cards sold and redeemed. It must be a liability account with Enable payments to this account turned on in Xero ( Chart of accounts › the account ), because a redeemed gift card is a payment from it. Suggested: a liability account with gift or voucher in its name.
Fees
Checkout fees ( Flex-Fees ).
Tips
Tips added at checkout.
Duty
Import duty charged at checkout.
Rounding
Pennies of difference between how the store and Xero round tax. Suggested: Xero’s own Rounding account.
Tax
How the tax an order charged is shown in Xero. It is always the store’s figure.
11 settingsSend tax
With Xero tax rates puts a Xero tax rate on each line ( VAT, GST ). As its own line sends the tax as a line of its own to a liability account, with no rate on the other lines: it suits US sales tax, which changes by address. Suggested: As its own line for organisations in the US, With Xero tax rates everywhere else.
Tax collected
With As its own line: the liability account the tax line goes to ( e.g. Sales Tax Payable ).
VAT
With Xero tax rates: the Xero rate for items with VAT. Left as Match the order’s rate, each order uses the Xero rate whose rate matches what it charged.
Sales tax
The Xero rate for taxable items, matched to the order’s rate unless you choose one.
GST, PST, GST and PST, HST
Canada: the rate for each kind of tax, matched to the order’s rate unless you choose one.
Items without tax
The zero rate for untaxed items, shipping and rounding.
Rounding allowed
The most the store’s total and Xero’s may differ by; the difference goes to the Rounding account. A bigger difference holds the order. From 0 to 5.
When the difference is bigger
Hold the order lets you fix the tax rate first. Round it anyway sends it, with the difference on the Rounding line.
Prices that include VAT
When your prices include VAT, the invoice’s amounts include it too ( tax inclusive ), so the totals match what the customer paid.
💡 Note: Xero always works out the tax itself from each line’s rate, and takes no tax amount from the store. A bigger difference than Rounding allowed almost always means a line has the wrong rate: the order is held, and its card names both totals. Check the rates under Tax.
Payments
The account each payment goes into
6 settingsWhich account
A bank account, or a clearing account for the payment service so each payout from Stripe, Square or PayPal matches your bank statement. Any account other than a bank account needs Enable payments to this account turned on in Xero. Left as Suggested, an account with the payment service’s name ( Stripe, Square Clearing, PayPal ) is used when you have one, else your first bank account.
Stripe
Card payments through Stripe.
Square
Payments through Square.
PayPal
Payments through PayPal.
Paid by invoice or bank transfer
Orders paid outside a payment service.
Other payment services
Authorize.net, Braintree and the rest.
Refunds paid by hand
Refunds you gave outside the payment service, and refunds of orders paid in Xero.
Changing an account later
Payments already in Xero stay where they went. New payments, and refunds paid back from now on, use the account you choose.
Day to day
Payments, orders and tools
What comes back from Xero, where you see what was sent, and the tools for past and held orders.
Paid in Xero
Invoices paid in Xero mark the order paid in your store
no stored settingsWhat happens
When an invoice the store sent is paid in Xero ( a payment you record, a bank feed match, or an online payment through Xero ), the order is marked paid: it moves to the status chosen under Sending, its stock is taken, the customer gets their receipt, and its timeline says it was paid in Xero. Activity lists it under From Xero.
How quickly
With the WP EasyCart app, Xero tells your store as it happens; the Connection card says so. With your own Xero app, the same with its webhook and key, else your store checks Xero every 15 minutes. Either way, the store also checks Xero a few times a day in case a notice went missing.
Switching it off
Switch off Mark orders paid when paid in Xero under Sending, and mark the orders paid yourself.
Invoices voided in Xero
The order is not changed: Activity says “Invoice WEB-1042 was voided in Xero. The order was not changed.”, and the store does not send that order again. To send it afresh, press Send again on its card; the new invoice gets its own number ( WEB-1042-2 ).
Orders on the order screen
The Xero card on each order, and the orders list
no stored settingsThe order’s card
Each order screen has a Xero card: the invoice, its payments and credit notes, the invoice and credit notes linked to Xero, each with its amount. Send again sends the order again, to bring its invoice up to date.
An order that is held
The card says Not sent yet with the reason and a link to the settings. Once you fix a setting, saving it sends every order that waited on it; Send to Xero sends this one now.
Orders from before Send orders from
An order placed before the start date shows “Not sent to Xero.” with a Send to Xero button.
The orders list
Choose the Xero column with Columns to see each order’s state ( it starts hidden ). The filters show orders that Need attention, are Not sent or Sent, and the bulk action Send to Xero sends the orders you tick.
Activity
What was sent, what came back from Xero, and what needs you
no stored settingsWhat it shows
Every invoice, payment, credit note and void, newest first, each linked to its order. Needs attention shows only what is held; From Xero shows what came back, such as invoices paid in Xero. Activity keeps 90 days.
Above the list
How many records wait to send, how many need attention, a pause when Xero asks the store to slow down, and how many calls to Xero are left today once fewer than 1,000 remain ( Xero allows each organisation 5,000 a day; when they run out, sending waits and carries on by itself ).
Tools
Past orders, held orders and Xero’s lists
1 setting, 3 toolsSend past orders
Queues orders since the start date ( Send orders from ) that are not in Xero yet, up to 500 at a time. Set an earlier start date first to send older orders.
Try held orders again
Orders held for a setting or a problem in Xero go back in the queue.
Refresh accounts and tax rates
Reads the chart of accounts, tax rates and branding themes from Xero again ( it also happens twice a day ). Use it after adding an account or tax rate in Xero.
Log every call to Xero
Writes each request to Settings › Logs for troubleshooting. Errors are always logged.
⚠️ Careful: Send past orders sends every order since the start date that is not in Xero yet. If you entered those sales in Xero yourself, they would be there twice: set Send orders from to the day after the last sale you entered by hand first.
When something is off
Troubleshooting
What the messages on an order’s card and in Activity mean, and what to do about them.
Troubleshooting
What the messages mean, and what to do about them
no stored settingsConnecting
“This server cannot store the connection safely”
PHP on your server has neither the OpenSSL nor the Sodium extension. Ask your host to turn one on.
“Connecting needs a current WP EasyCart Premium license” or “Connecting through WP EasyCart needs your Premium license”
Add or renew your Premium license under EasyCart › Registration, then connect.
“Could not reach the WP EasyCart connection service”
Your server could not reach connect.wpeasycart.com. Try again in a few minutes; if it keeps happening, ask your host whether outgoing connections are blocked.
“No Xero organisation was chosen”
Connect again, and tick the organisation for this store on Xero’s screen.
“Connecting was cancelled in Xero. Nothing changed.”
Someone pressed Cancel on Xero’s screen. Press Connect to Xero again.
“This sign-in has expired or was started somewhere else”
The sign-in took longer than 15 minutes, or was started in another tab or by another person. Press Connect to Xero again.
“Xero needs you to connect again”
Xero no longer accepts the connection: it was removed under the organisation’s connected apps in Xero, or not used for 60 days. Press Connect again; orders that waited go once you do.
“Xero did not accept the client ID and secret” or “Your Xero app does not offer the permissions this store asks for”
Your own app or custom connection: check its client ID and secret, and its scopes, in the Xero developer portal.
“This looks like a copy of your store”
The connection was made on another address. See Staging copies under Connect Xero.
An order is held ( Not sent yet )
“Choose … in the Xero settings”, “Choose the account payments go into” or “Choose the account refunds are paid from”
A setting has no suggestion in your chart of accounts. Choose it on the settings page; saving it sends the orders that waited.
“Choose the account for gift cards in the Xero settings”
Make a gift card liability account in Xero with Enable payments to this account turned on, press Refresh accounts and tax rates, then choose it under Accounts › Gift cards.
“Xero cannot take payments into …”
Turn on Enable payments to this account for that account in Xero ( Chart of accounts ), or choose a bank account under Payments.
“No Xero tax rate matches the …% this order charged”
Add the rate in Xero, then press Refresh accounts and tax rates; or choose the rate under Tax.
“Xero would total this invoice …, but the order came to …”
Xero worked the tax out differently from the order, almost always because of a tax rate. Check the rates under Tax, or allow a bigger difference to go to the Rounding account.
“Xero will not use tax rate … here” or “Xero did not accept a tax rate”
The rate is archived, or not allowed with that account. Check the rates and accounts in the Xero settings, then press Send again.
“Account … is archived or missing in Xero”
Choose another account in the Xero settings, or restore the account in Xero.
“Your store sells in … but Xero’s base currency is …”
Add the currency in Xero under Settings › Currencies ( a Xero plan with multi-currency ), then press Send again.
“The date is before your lock date in Xero”
Xero takes nothing dated before the lock date. Move it ( Settings › Advanced › Financial settings ), or enter the order in Xero by hand.
“Invoice number … is already used in Xero by another invoice”
Change Before the order number under Sending ( Advanced ), then press Send again.
“Xero already has a contact named …”
Rename that contact in Xero, or add the customer’s email address to it, then press Send again.
“The customer’s contact is archived in Xero”
Restore the contact in Xero, then press Send again.
“Your Xero plan’s limit was reached”
Your Xero plan limits how many invoices you can send a month. Upgrade the plan in Xero, then press Try held orders again.
“The order’s total changed, but its invoice has a payment added in Xero”, “… its payment in Xero is reconciled” or “The order changed after a refund was sent to Xero”
Xero has built on the invoice. Change it in Xero, or remove the payment there and press Send again.
“Xero was not changed because … but invoice … has payments or credits in Xero”
The order was cancelled or deleted, but its invoice was already paid or credited. Void or credit it in Xero.
“This order’s invoice was voided in Xero, so it is not sent again”
Press Send again on the order to send it as a new invoice.
“Something this order was linked to is no longer in Xero”
Its invoice or contact was deleted in Xero. Press Send again to send it afresh.
“Paid in Xero, but the order status chosen for it does not count as paid”
Choose another status under Sending › Order status once paid in Xero.
“Xero refused: the connection does not have permission for this, or your Xero plan does not include it”
Connect again, and check what the organisation’s Xero plan includes.
Other messages
“Payments and refunds are added once the invoice is approved in Xero”
Invoices arrive as drafts ( Sending ). Approve the invoice in Xero; its payments and refunds follow.
“paused by Xero’s limits until …” or “Xero’s daily limit for this organisation was reached”
Xero asked the store to slow down. Sending carries on by itself at that time.
“Could not reach Xero” or “Xero is not answering properly right now”
Nothing to do: the store tries again by itself.
Good to know
Organisations, licenses, privacy, updates and removing the extension
no stored settingsOne organisation per store
A store sends to one Xero organisation. To send to another, Disconnect and connect it. Orders since Send orders from that the new organisation does not have go to it, so set that date first.
What is sent
Each order’s lines, totals, tax, payments and refunds, and the customer’s name, company, email, phone and addresses. Card numbers, passwords and admin notes are never sent. The store never writes Xero data or your keys to its logs.
Where the keys are kept
On your site, encrypted by WP EasyCart Premium. With the WP EasyCart app, WP EasyCart’s connection service only swaps your sign-in for the keys, renews them and passes Xero’s payment notices on; it keeps no keys.
If your Premium license ends
Orders keep going to Xero. The settings are locked, and connecting again needs a current license.
Updates
Come through WP EasyCart Premium, on the Plugins screen and on EasyCart › Extensions.
Removing the extension
Deleting it disconnects the store from Xero ( while WP EasyCart Premium is active ) and removes its settings. The record of what was sent stays with WP EasyCart Premium, so installing it again never sends an order twice.
Keep going
Related guides
How Premium extensions install and update.
Order statuses, payments and refunds, which decide what goes to Xero.
The same for stores that keep their books in QuickBooks Online.
Xero comes with WP EasyCart Premium
Premium includes every WP EasyCart extension: Xero, QuickBooks Online, QuickBooks Desktop, ShipStation, Stamps.com, Zapier, AvaTax and more, with updates and priority support.
