AddThisFeature

Xero Invoice Sync

Keep Xero invoices, contacts, and payment state aligned with what the app believes.

involved Payments & Finance

What it adds

Alignment between app transactions and invoices in the connected accounting organisation, covering contacts, tax rates, and payment status.

What your agent is told to do

5
  1. 1

    Make the operator choose the organisation explicitly when connecting and store that choice, because one login commonly reaches several organisations and the first one returned is not necessarily the right one.

  2. 2

    Resolve the contact before the invoice, matching on a stored external reference first and creating a contact only when nothing matches with confidence.

  3. 3

    Read tax rates and account codes from the connected organisation rather than assuming any standard set, and revalidate a saved mapping before each send.

  4. 4

    Treat approval as the boundary of ownership. The app may create and amend a draft, but once an invoice is approved or paid the ledger owns it; do not let the app rewrite an approved invoice.

  5. 5

    Pull payment, credit note, and void status back onto the app record so the app's view of what is outstanding matches the ledger's. QuickBooks Invoice Creation is the sibling for a different ledger; share the matching and queueing path rather than writing a second one.

Edge cases it handles

8
  • One login can reach several organisations. If the connection does not pin one, invoices eventually land in the wrong company's books, which is not something an accountant can undo quickly.
  • Matching contacts on name alone joins unrelated businesses. Match on a stored reference, and treat a near match as something to confirm rather than something to assume.
  • An invoice moves through draft, submitted, approved, paid, voided, and credited, and most of those transitions are one-way. Model the whole lifecycle rather than a paid flag.
  • Tax treatment and currency rules belong to the organisation's configuration, not to the app. Send the codes the organisation defines and let it compute what it computes.
  • Once an invoice is approved, editing it from the app either fails or corrupts a filed return. After approval the app raises a credit note or a new invoice; it does not rewrite the original.
  • Access tokens for this kind of connection expire quickly and the refresh token may itself rotate on use. Persist the new refresh token atomically, because losing it forces the operator to reconnect by hand.
  • Rate limits are enforced per organisation and per application. Queue sends and back off when refused, and never place an accounting call inside a user-facing request.
  • When the ledger is unreachable, show the invoice as pending with the reason and the time of the last attempt. A silent failure is discovered at the end of the quarter.

Definition of done

9
  • The connected organisation is chosen explicitly at setup and every request is scoped to it.
  • Contacts are matched by stored reference before any new contact is created.
  • Draft, approved, paid, voided, and credited invoices are each represented distinctly in the app.
  • Approved invoices are read-only from the app, and corrections are made by credit note or new invoice.
  • Token refresh, including a rotating refresh token, survives a restart with no operator action.
  • Payment and credit status flows back so the app's outstanding balance matches the ledger's.
  • Rate-limited and unreachable states are visible with a reason and a last-attempt time.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.