Documentation

Overview

There are two sides to Client Invoices:

• Providers — businesses that invoice through Xero. You sign in with your Xero account and choose which clients to share, and who to share each client with.
• Clients — the people you invoice. They receive an email invitation and view their invoices through a passwordless link. A client can be given access by more than one provider and sees everything in one place.

By default we request read-only access to your Xero contacts and invoices, and you can revoke any share — or disconnect Xero entirely — at any time. The only thing that changes that is auto-invoicing, which is off unless you turn it on for a specific organisation and approve the extra permission at Xero yourself.

Sign in with Xero

Choose Sign in with Xero from the top of any page. You'll be taken to Xero to approve access, then returned to your Clients page. There's no separate password to create — Xero is your login, and there's no other way in.

The very first time, we ask two things of our own before letting you through: your country, and the currency you'd like to be billed in. You also accept the terms at that point. Both take one click and neither is asked again.

The first time you connect, Xero asks you to authorise these read-only permissions — and only these:

• Your name and email address (to identify your account)
• Read access to your contacts
• Read access to your invoices
• Permission to keep the connection alive in the background, so you aren't asked to sign in again every half hour

Choosing an organisation

If your Xero login has access to more than one organisation, an organisation switcher appears in the top navigation bar — the active-organisation menu, shown on every page. Pick the organisation you want to work in — the client and invoice lists always reflect the organisation that's currently selected.

To add another organisation later, use Sign in with Xero again and approve it; it'll appear in the switcher.

Settings that belong to an organisation, and settings that belong to you

Businesses in different countries are usually different Xero organisations, and they don't share their details. So the settings split in two:

• Organisation in the top navigation is about the organisation you're currently in: the currency it's billed in, the country its tax treatment comes from, who else can see it, its sign-in link, and disconnecting it. Swap organisation and this page is about the next one.
• Your account, in the organisation menu, is about you: your name, your email address, the Xero organisations you've connected, and deleting your account. It reads the same whichever organisation you're working in.

Billing currency is set per organisation, and can be changed up until that organisation's first payment — after which the subscription is fixed to it, so get in touch and we'll move it with you. Only the organisation's owner can change it. Its country comes from Xero directly, because that's what decides whether GST applies, and it follows if you change it there.

Who else can see an organisation

The People list on the Organisation page shows everyone with access to it. There's nobody to invite and nobody to remove: membership is Xero's, and a colleague appears here by signing in and authorising the same organisation themselves.

What is ours is ownership, because it decides who is billed and who can disconnect. The owner can hand it to any other member with Make owner — the subscription carries on untouched, no new card and no gap, and receipts start going to them. The previous owner keeps full access to clients and invoices, just not to billing.

Plans and billing

Plans are priced on the number of client businesses you're sharing with — the one number that decides how much work we do for you. A client is a business, not a person: however many people there sign in, it counts once.

• Free — up to 3 client businesses.
• Starter — up to 250.
• Standard — up to 2,000.
• Pro — up to 10,000.
• Enterprise — no limit. Talk to us.

It counts clients, not people and not invoices, so three people at one client is one client. Nothing else is metered: invoices are unlimited on every tier, and the portal, the statement and the forward book work the same whichever one you're on. Two things do depend on your plan — your logo and colours need an active subscription, and Stripe auto-invoicing, the embedded portal and API keys are part of the Pro plan. Your current usage is on both the Clients page and the Billing tab.

Each organisation is billed separately, so the Billing tab on the Organisation page is where you'll find everything about one organisation's plan: what it's on, what it's been charged, and the tax invoice for each payment. If you run three businesses through three Xero organisations, each has its own plan, its own currency and its own card.

The plans themselves are on the same tab, folded out of the plan card at the top — open already if the organisation is on Free, and a click away under Change plan if it isn't. Only the organisation's owner sees the option to subscribe; anyone in the organisation can see what it's on and what it has paid.

Once you're subscribed, Change plan on that same tab is where you move between tiers or between monthly and annual. Pick the plan you want and Stripe confirms it, showing you the exact amount before you agree: an upgrade is charged straight away, pro-rated for the rest of the period, and a downgrade is credited against your next invoice. Your plan keeps running throughout — there's no gap and no new card needed.

Changing your card and cancelling happen in Stripe's own portal, reachable from the same tab. One thing we don't do there: if you're sharing with more clients than a smaller plan allows, we won't move you down onto it — reduce your sharing first, or talk to us about Enterprise.

Over your limit, or a payment that failed

Two things can put an organisation above its client limit: moving down a tier, and a subscription payment that didn't go through — a failed card drops the organisation to the free allowance until it clears. Both say so in the same words, on the Clients page and on the Billing tab.

The consequence is the same either way, and it is deliberately narrow. You can't invite anyone new. Everyone you already share with keeps their access, keeps signing in, and keeps seeing their invoices; re-sending a link to someone you've already invited still works, because they're not a new client. We don't cut your clients off over a billing state that's usually an expired card.

A failed payment is never treated as though you'd chosen the free plan. The Clients page says what happened and the Billing tab says when Stripe will try the card again — often you need do nothing at all. If you'd rather not wait, Update card in Stripe is on the same tab. Your branding is untouched throughout.

Your clients

The Clients page lists the customer contacts from your selected Xero organisation. Use the search box above the list to find a client by name or email — we keep a synced copy of your contacts in the background, so search stays fast no matter how many contacts you have.

Every row carries two figures: Total, everything you have invoiced that client to date, and Due, the part of it still unpaid — each split by currency, never added together. A red OD mark sits in front of a figure when some of what it owes has passed its due date; hover it for the exact late amount, which may be only part of what's due. A settled invoice paid late is history, not a demand, so it doesn't count. Two more things ride on a row only when they're true: a green count of how many people can see that client's invoices, and a red flag if the last email we sent one of them didn't arrive.

Above the list you'll find the same two figures for the organisation as a whole, how many of your client slots are in use, and — when there's something in it — the Coming up figure described below. The totals appear once your first invoice sync has finished: until then we say so rather than show a figure we know is incomplete. After that they keep themselves current — when an invoice is paid, credited or voided in Xero, Xero tells us and the figures move with it.

Select a client and their page opens on two tabs:

• Invoices — the account. Three figures across the top (Paid, Due, and Credited when there are credit notes to explain), then every invoice.
• Shared with — who can see them, covered under Managing access.

Paid is cash received, not invoices marked PAID — so it reconciles against your bank, and a part-paid invoice counts towards both Paid and Due. Credited is what a credit note wrote off: Xero marks an invoice PAID the moment its balance reaches zero, whether money arrived or not, and showing the credit separately is what stops the three figures looking like an arithmetic error. Under Due, we say how much of it is actually late.

Each invoice row carries its number, date, due date, face value, what's still owed, what's been paid against it, and any credit notes applied. An invoice past its due date with money still on it takes a days overdue chip in place of its Xero status — the status of the document isn't the status of the debt. Every row links through to the invoice in Xero. One figure per currency throughout: we never add NZD to AUD.

Sharing invoices

On a client's page, choose Share at the top right — it sits above the tabs, on both of them. Enter the email address you want to share with, confirm it's the right recipient and that you're allowed to send them these invoices, and send the invitation. We email that address a secure link to view the invoices.

You share at the level of a whole client, not one invoice at a time — picking and sending an individual invoice on its own isn't supported yet. Sharing a client gives the recipient all of their finalised sales invoices:

• Only sales invoices (money owed to you) are shared — never bills you owe suppliers.
• Only finalised invoices — anything that isn't a draft, voided or deleted is shared, so Authorised (what Xero shows as awaiting payment), Submitted and Paid all appear. Drafts, voided, and deleted invoices are never shown.

Managing access

The Shared with tab on each client's page lists everyone you've invited for that client, with their status, when they were invited and by which of your colleagues. To remove someone, choose Revoke next to their email and confirm.

Revoking takes effect immediately: the person loses access to those invoices, any unused sign-in or invitation link stops working, and if they are signed in at that moment they are signed out and have to sign in again.

Several people at one client

Most businesses have more than one person who needs the invoices — an accounts-payable clerk, a finance manager, the owner. Share the same client with each of them and they each get their own sign-in link to the same invoices.

The links are independent in both directions. Revoking the clerk leaves the finance manager and the owner untouched, and Resend next to one person's email sends a fresh link to that person only — everybody else's existing link keeps working. Re-sending replaces that person's old link, so a link sitting in a mailbox they no longer control stops working.

Adding people costs nothing: your plan counts clients, not people, so three people at one client is still one client against your limit.

Did your email arrive?

Chasing a client who never received the invoice is wasted effort, and until you can see what happened to the email there is no way to tell that apart from a client who is ignoring you. The Shared with tab shows a Delivery state for the last email we sent each person.

• Queued — accepted by us, not yet handed on.
• Sent — we handed it to our mail provider.
• Delivered — their mail server accepted it. This is the one that matters.
• Retrying — a temporary problem at their end, such as a full mailbox. Usually resolves on its own.
• Bounced or Failed — permanently rejected, or never got out. The reason their mail server gave is shown underneath.
• Marked as spam — the recipient reported the email.
• Opened (approx.) — see the caveat below.
• Link clicked — somebody followed the link in the email.

A client whose email is failing is flagged on your Clients list too, so you don't have to go looking.

We keep delivery records for 24 months, then delete them automatically along with the recipient's address.

Did your client look at it?

When a client signs in and opens your portal, the Shared with tab records opened the portal against that person, and the Invoices tab shows viewed under the number of any invoice they opened.

This is a stronger signal than an email open, and it is shown separately for that reason. An email open is an invisible tracking image that many mail apps never load. A portal view is somebody who received a link, proved they control that email address, signed in, and opened the page — so if it says viewed, they were there.

Requests that announce themselves as automated are ignored, so the corporate mail scanners that follow links before your client ever sees them don't register as views. We keep only the most recent time, not a history of every visit.

Showing clients what's coming

Xero raises repeating invoices on a schedule but gives nobody a way to see the set — not your clients, and not you. Your clients see theirs automatically. If you would rather they didn't, tick Hide upcoming invoices under Branding. That switch turns the feature off for you as well as for them: we stop reading your repeating invoices from Xero altogether, so your own Coming up total and the per-client template lists go too, rather than sit there showing a frozen copy.

The usual reason to hide them is a price change you have scheduled in Xero but not yet discussed — a client would otherwise see the new amount in their portal the moment you save it.

Left on, each client portal carries an Upcoming card listing the repeating invoices scheduled against the contacts you've invited that person to — the reference, the amount, and the next scheduled date. You get the same thing twice on your own side: a Coming up total for the next 90 days on your Clients page, and the individual templates on each client's Invoices tab. Both are shown only when there's actually something scheduled — an empty card telling you nothing is due is a row of furniture, not an answer.

The 90-day total counts each repeating invoice once, and says so beneath itself. Xero tells us the next date a template falls due and nothing else about its recurrence, so a monthly template inside the window contributes one invoice to that figure, not three.

Branding your portal

Your clients can see your brand rather than ours. Open Branding in the top navigation to set it up for the organisation you're currently working in — each connected Xero organisation is branded separately, so a bookkeeper managing several can give each one its own look.

There are four things to set:

• Logo — PNG, JPG or WebP, up to 2 MB and 1000 × 400 pixels. It replaces our logo on your clients' sign-in page, their invoice list, and the emails they receive.
• Portal colours — a background and a text colour for the portal chrome. A live preview of the client view sits beside the fields and updates as you pick, so you can see the result without opening the portal yourself. We measure the contrast between the two as you go and say what it comes to; a pair too close together to read won't save.
• Portal address — the web address your clients use, for example /portal/acme-ltd. Lowercase letters, numbers and hyphens.
• Your website — where the “back to your website” link on your sign-in page sends people. Leave it empty for no link.

Your clients still always see your organisation's name, on every plan — it's how they know who shared the invoices with them. What branding changes is everything around it.

Linking from your website

The point of branding is that your clients can go straight from your own website to their invoices without it feeling like a different company. On the Organisation page you'll find Your sign-in link — the exact address to use, with a Copy button beside it. It always shows the address that is saved and working, so what you copy is safe to publish. Change the address itself under Branding, where you'll see the new link take shape as you type.

Add it to your site as an ordinary link. Wording that works well:

• “View your invoices”
• “Client login”

Your client clicks it, lands on a sign-in page wearing your logo and colours, enters their email, and gets their one-time link as usual. If you've set your website address, there's a back link on that page to return them to your site.

The invitation (for your clients)

When a provider shares invoices with you, you'll get an email from Client Invoices with a button to view them. The invitation link by itself doesn't sign you in — when you click it, we send a fresh sign-in link to that same email address to confirm it's really you.

Signing in

You don't need a password. To sign in (or to come back later), go to the client sign-in page, enter your email, and we'll email you a one-time link. Click it and you're in.

The first time you sign in there's one screen before your invoices: a short welcome page saying who holds your details and why, the terms for using the portal, and a choice about analytics. Accept it once and you go straight through from then on — we only ask again if those terms materially change.

Viewing invoices

After signing in you'll see every provider who has shared with you. Open a provider to see the invoices you've been granted; opening one takes you through to its own secure page in Xero, where you can see it in full and use whatever payment options that business has set up. If access to something is revoked, it simply stops appearing.

Your account statement

At the top of each business's portal is a summary of your account with them: what's outstanding in total, and how much of that is past its due date. Each invoice row shows its due date, what has been paid against it, and what's left — so a part-paid invoice reads as part paid rather than just "awaiting payment", and one that's late says how late.

Use Print statement for a printable copy of the whole account (every invoice, not just the first page), or Download CSV to open the same figures in Excel or Google Sheets. The printed statement is where the ageing lives: not yet due, 1–30, 31–60, 61–90 and over 90 days past due, with its own date on it. An invoice Xero gave no due date gets its own No due date line — owed, but never counted as late.

Invoices still to come

Some businesses also show you what's scheduled next. When they do, an Upcoming card sits beside your account summary, above your invoices, listing each repeating invoice, its amount and the date it's next scheduled for.

These are scheduled, not issued: the business can change, pause or stop a repeating invoice at any time, so the dates and amounts can move. The whole page is stamped with the date it was read, under the business's name; if the scheduled invoices were last read on a different day, the card carries that date itself.

Stripe auto-invoicing

Connect your own Stripe account so that when your customers pay, a sales invoice is automatically raised and marked paid in your Xero organisation — and made available to that customer through an embeddable portal you can drop into your own website. Both are part of the Pro plan.

Open the organisation you want the invoices raised in, go to its Integrations tab, and choose Connect a Stripe account. Because you start from the organisation, there is nothing to map afterwards: that account's payments are invoiced into the organisation you connected it from.

Running two businesses through two Xero organisations? Connect each one's Stripe account on its own Integrations tab. A Stripe account belongs to one organisation, so the same payments can never be invoiced into two sets of books.

Tax & account codes

For each Stripe→Xero mapping you choose the sales account code, tax type, whether amounts are tax inclusive or exclusive, and the bank account the payment is recorded against (so the invoice can be marked paid). These are populated from your Xero organisation once it can create invoices. You are responsible for the tax treatment of your own sales — we apply your settings, we don't give tax advice.

There is one more, and it only matters if you run more than one Stripe account into the same Xero organisation. Each invoice we raise carries the Stripe payment's id in its Reference, which tells you nothing about which account the money arrived in. Set a reference code — up to eight letters or numbers — and we write it in front, separated by a pipe:

SH|cs_live_a1B2c3…

We add the separator, so you only type the code. Leave it empty and the reference is just the Stripe id, exactly as before. Changing it affects invoices raised from then on — we never go back and edit invoices already in your books.

Turn it on

Auto-invoicing is off by default. Enable it per connection with the Auto-raise invoices toggle. Only turn it on if you are not already invoicing those Stripe payments in Xero another way (for example Xero's native Stripe feed) — otherwise you could double-invoice. We do skip a payment when an invoice already exists in that organisation carrying the reference we would have written — the Stripe payment's id, behind your reference code if you set one — so we will never raise the same payment twice. It won't catch an invoice something else raised under a different reference, which is why the warning above matters. The Recent auto-invoicing activity panel shows what we've raised, held or skipped, with the reason; where something failed or is held, Retry on that panel has another go.

Embed the portal

Show a customer their invoices on your own site. Your backend mints a short-lived token for one customer (see the developer section), then you embed it. Either paste an iframe:

<iframe src="https://clientinvoices.com/embed/invoices?token=THE_TOKEN"
        style="width:100%;border:0" title="Invoices"></iframe>

…or use the snippet, which injects the iframe for you:

<div id="client-invoices"></div>
<script src="https://clientinvoices.com/js/client-invoices-embed.js"
        data-token="THE_TOKEN"
        data-target="#client-invoices"></script>

Add your site's address(es) under Allowed website addresses on the organisation's Integrations tab — only those addresses can embed and read that organisation's portal.

Developer: API keys

The embed API is authenticated by a server-side API key, created on an organisation's Integrations tab and shown only once. A key belongs to that one organisation and can only ever read its invoices. Keep it on your backend — never put it in client-side or embed code. Send it as a bearer token:

Authorization: Bearer sk_live_…

Requests are rate limited to 120 a minute per key, and 300 a minute per IP address; over either, you get a 429. Only the organisation's owner can create or revoke keys, and only on the Pro plan, which is what the embed API belongs to. Revoke one at any time from the Integrations tab; a revoked or unknown key returns 401.

Embed sessions (ephemeral tokens)

Mint a short-lived token scoped to one customer. Your backend has already authenticated that customer on your site, so the embedded view trusts your vouching and skips the email proof.

POST https://clientinvoices.com/api/v1/embed-sessions
Authorization: Bearer sk_live_…
Content-Type: application/json

{ "xero_contact_id": "…" }

→ 201 { "token": "…", "expires_in": 300 }

The organisation comes from the key, so you only send the customer. (You may still send xero_connection_id; if it disagrees with the key's organisation you get a 403 rather than a quietly wrong token.) The token is bound to that one customer and expires in a few minutes — mint a fresh one per page render. A token for one customer can never read another's invoices.

Minting also returns 403 if the organisation's plan no longer includes the embedded portal. Pages already embedded keep working; it is new tokens that stop, so a downgrade shows up here first.

Connect webhook

We receive connected-account payment events on a single platform endpoint, routed by the event's account, and verify Stripe's signature on every one. We act on checkout.session.completed and checkout.session.async_payment_succeeded for one-off payments, and invoice.paid for subscriptions. A completed session is only invoiced once the money is actually collected, so a delayed method — bank transfer, direct debit, Konbini, Boleto, or a card still processing — is invoiced when it settles rather than when the customer finishes checkout. Subscription-mode sessions are left to their invoice.paid. We re-fetch the object from Stripe (never trusting the webhook payload) and raise the invoice idempotently. Nothing for you to configure — connecting your Stripe account wires this up.

Security & privacy

• Read-only Xero access by default. We can only read your contacts and invoices — we cannot create, edit or delete anything. The one exception is an organisation you turn Stripe auto-invoicing on for: Xero asks you to approve create-invoice permission for it separately, and we use it only to raise a sales invoice when one of your customers pays. Disconnect at any time — from the Organisation page, from Xero itself, or by deleting your account.
• Encrypted credentials. Your Xero tokens are encrypted at rest and never exposed.
• Passwordless clients. Clients sign in with single-use links that expire after 15 minutes — there are no client passwords to leak.
• You only ever see what's granted. Clients can only open invoices that have been explicitly shared with them; nothing else is reachable.
• Instant revocation. Revoking a share — or deleting your account — removes access right away.
• Safe to publish. Your sign-in page can go on your public website. It shows your branding and nothing else, it's protected against automated abuse, and it never reveals whether a particular email address is one of your clients.

Troubleshooting & FAQ

A client's invoices aren't showing

Only finalised sales invoices are shareable. If a client has only draft invoices, or only bills (purchases), there's nothing to share yet. Make sure the invoice is Authorised, Submitted, or Paid in Xero.

It says my Xero connection needs re-authorising

Xero connections can expire if they're left unused for a long time, or if access is revoked in Xero. Choose Reconnect Xero on the prompt (or use Sign in with Xero again) to restore the connection — your existing shares are unaffected.

Can a client get invoices from more than one business?

Yes. A client signs in with their email and sees every provider who has shared with them, each listed separately.

What if I shared with the wrong email?

Revoke that invitation from the client's Shared with tab, then share again with the correct address. The old link stops working immediately.

Do I need a particular plan for branding?

No — any active subscription includes it, on every paid plan. The free plan keeps a working portal address and shows your organisation's name; the logo, colours and “powered by” footer are what a subscription adds. Stripe auto-invoicing, the embedded portal and API keys are the exception: those are part of the Pro plan rather than any subscription.

What happens to my branding if I cancel?

Your clients go back to seeing Client Invoices branding, but nothing you've set is deleted — your logo, colours and website address stay saved. Subscribe again and your branding reappears immediately, with no need to set it up a second time. Your portal address keeps working throughout, so any link on your website stays live.

Can I change my portal address later?

Yes, from the Branding page. Bear in mind that any link already on your website points at the old address, so update it at the same time. A few words are reserved and some may already be taken by another business — you'll be told if the one you want isn't available.

Someone used an old link to my portal — what do they see?

If the link points at your current portal address — an old bookmark of a page deeper in the portal, say — they land on your own sign-in page, branded as yours, rather than a generic one. If you have since changed the address itself, the old one no longer resolves and they get the plain Client Invoices sign-in page instead. That's the reason to update any link on your website at the same time as the address.

Can I embed the sign-in page inside my website?

Not as an embedded frame — a sign-in form inside another page is a well-known target for scams that mimic it, so we don't allow it. Link to it instead; your clients keep your branding either way. If what you want is the invoices themselves inside your own pages, that's what the embedded portal does: your site vouches for the customer, so there's no sign-in form to frame.

Where do I find the link to put on my website?

On the Organisation page, under Website integration, with a copy button beside it. It shows the address that's saved and working, so what you copy is always safe to publish; the address itself is edited on the Branding page. See Linking from your website.

What happens when I reach my client limit?

You keep everything you have. Every client you already share with carries on exactly as before, and you can still re-send links to them — and adding another person at one of those clients is always free, because it counts once however many people are there. What stops is adding a new client business, until you move up a tier. See Over your limit, or a payment that failed.