Skip to content
Bottle

Accounting

Bottle raises your invoices and takes your payments. It keeps no ledger, files no VAT and reconciles no bank: that is your accounts package’s job, and the point of this page is that it can do it without anybody typing anything twice.

What moves

Section titled “What moves”
  • Customers, both ways. A contact in Xero that Bottle has never seen becomes a customer, with its street address. A Bottle customer without a match becomes a contact in Xero. A name that exists on both sides is matched, never doubled: Xero will not have two contacts of one name, and neither will Bottle create a second. Where both sides changed the same record since they last agreed, Bottle wins, because it is where the office works.
  • Invoices, one way. Every invoice Bottle raises goes to Xero as an authorised sales invoice under Bottle’s own number (INV-BTL00042), with the same lines, coded to the sales account you choose and taxed at your organisation’s matching VAT rate: 20% or 5% as the product says, Zero Rated Income for a 0% product, and No VAT on everything if you are not VAT registered in Bottle. Bottle never marks a line Exempt. An invoice cancelled in Bottle is voided in Xero. Nothing comes back the other way.
  • Payments, one way. When a Bottle invoice is paid, a payment is recorded against it in Xero, into the bank account you chose for that kind of money: cash, card (an online card payment through Stripe, or a card the office took), or a bank transfer. The payment’s reference says which, for example “Online card payment (Stripe)”. Marked unpaid again, the payment is deleted.
  • Online payments and branding. The “Online payments” and “Branding theme” shown on the invoice in Xero are Xero’s own settings, from the organisation’s default branding theme, not something Bottle sends. Xero’s demo company comes with PayPal attached to it. Change them under Invoice settings in Xero.

A few seconds after an invoice is raised, paid, unpaid or cancelled, however that happened (the office, a card payment, a driver at the door); every few minutes for every connected business, to catch anything missed; and on demand with Sync now. Running it twice sends nothing twice.

Changes made in Xero come back the same way: once the Xero app has webhooks switched on, Xero tells Bottle the moment a contact or invoice changes and the sync runs then. Without them, the clock picks the change up within a few minutes.

A contact added in Xero comes into Bottle as a customer even before it has an invoice. Only contacts Xero marks purely as suppliers are left out.

An invoice already paid in Xero keeps its lines: Xero will not change the lines of a paid invoice. If it is marked unpaid in Bottle, the payment comes off in Xero first and then the lines are brought up to date.

Connecting

Section titled “Connecting”

The Xero tile on Connections, in the sidebar. Connect Xero sends you to Xero to say yes and brings you back. If your Xero login has several organisations, the first is used; disconnect and connect again from the right one if that is wrong.

Then choose where things land, from your own chart of accounts: the sales account for invoice lines, and the bank accounts for cash, card and transfer payments. Nothing is sent until a sales account is chosen; the page says so.

Each of the three jobs can be switched off on its own.

Keeping Xero from writing to your customers

Section titled “Keeping Xero from writing to your customers”

Bottle sends your invoices. Xero should not send them as well, or a customer hears about one bill from two places and does not know which to pay.

  • Customer email addresses stay out of Xero unless you switch on Copy customer email addresses to Xero. With no address on the contact, Xero has nobody to email. Switch it on only if you send invoices from Xero yourself. Addresses already in Xero stay there.
  • Xero’s own invoice reminders. Xero can email customers about overdue invoices by itself. Bottle checks that setting on every sync, and while it is on shows a warning on the Xero page, in Business settings › Invoice reminders, and on the Xero tile under Connections. Bottle cannot turn it off for you (Xero does not allow it): in Xero, open Sales › Invoices › Invoice reminders and switch them off. The warning goes on the next sync. To chase overdue invoices, use Bottle’s own reminders.

Invoices go from the day you connected: anything older was probably keyed into Xero by hand, and sending it again would double it. Change the date if that is wrong. Also send older invoices that are still owed sends the unpaid ones from before that date as well, so Xero’s list of who owes you is complete; older paid or cancelled ones still stay out. Check Xero for any you typed in yourself first.

What it will not do

Section titled “What it will not do”
  • Pull invoices from Xero into Bottle. Bottle only sends what it raised.
  • Delete anything on either side. Disconnecting forgets which record is which; the records stay.
  • Post more than one address per customer to Xero, because Xero contacts have one street address. The customer’s first delivery address is the one sent.
  • Match by anything but name when there is no existing link. A customer renamed on one side only becomes a new record on the other; rename on both, or let the sync run before renaming.

For whoever runs the box

Section titled “For whoever runs the box”

Xero needs one app registered per installation at developer.xero.com (type: Web app), with https://<your api>/xero/callback as a redirect URI and the scopes accounting.contacts, accounting.invoices, accounting.payments and accounting.settings.read allowed, and its client id and secret in the API’s environment as XERO_CLIENT_ID and XERO_CLIENT_SECRET. Xero charges the app’s owner by connected organisation (free up to five, then tiers); that is Bottle’s cost, not the business’s. Without them the page says Xero is not switched on. Tokens are stored sealed with the same key as shop credentials and never returned.