Xero accounting

1. Connect your Xero organisation from Settings → Integrations. (Owner / admin only.)
2. Set your default revenue account code on the same page. Xero Singapore's default Sales account is 200 — use that unless you want a different mapping.
3. Issue invoices as usual. Nothing happens on Xero's side until an invoice is marked PAID.
4. When you mark an invoice paid (manually or via Stripe), Zeng Book pushes it to Xero as an AUTHORISED invoice. The push runs fire-and-forget— your "mark paid" click returns immediately; the push happens in the background and writes its outcome to the invoice's Xero sync card.
5. If the push fails (Xero rate-limit, expired token, wrong account code, etc.), the invoice detail page shows a red error card with a Retry push button.

Zeng Book maps your invoice into a Xero ACCREC (accounts-receivable) invoice:

{
  "Type": "ACCREC",
  "Contact": { "Name": "Tan Renovations Pte Ltd", "EmailAddress": "[email protected]" },
  "Date": "2026-05-15",
  "DueDate": "2026-06-14",
  "InvoiceNumber": "INV-2026-0117",
  "Reference": "Zeng Book INV-2026-0117",
  "Status": "AUTHORISED",
  "LineAmountTypes": "Exclusive",
  "CurrencyCode": "SGD",
  "LineItems": [
    {
      "Description": "Phase 2 — Carpentry installation (40%)",
      "Quantity": 1,
      "UnitAmount": 18000.00,
      "AccountCode": "200",
      "TaxType": "OUTPUT"
    },
    {
      "Description": "Less retention (5.0%)",
      "Quantity": 1,
      "UnitAmount": -900.00,
      "AccountCode": "200",
      "TaxType": "OUTPUT"
    }
  ]
}

• Money— Zeng Book stores integer cents; the push divides by 100 for Xero's decimal-dollar format.
• Retention— a single negative line item at the same TaxType as the rest of the invoice. Math is identical to Zeng Book's subtotal → retention → net → GST → total order.
• TaxType — OUTPUT when the invoice has a non-zero GST rate, NONE otherwise.
• InvoiceNumber — copied verbatim from Zeng Book so both systems share the same identifier.
• Status — pushed as AUTHORISED. Payment reconciliation in Xero is still manual today; automatic payment push is on the roadmap.

The push is idempotent per Zeng Book invoice: each invoice maps to at most one Xero invoice. The mapping is tracked in the XeroInvoiceMapping table with three states:

• synced — push succeeded. A retry returns the existing Xero invoice ID with no duplicate create.
• failed — last attempt failed. The retry button deletes the failed row and tries again.
• (no row) — invoice has never been pushed. First push creates a fresh mapping.

The fire-and-forget push has a 15-second timeout and a try/catch around every external call — a Xero outage never blocks payment recording.

The implementation lives in lib/xero.ts:

• pushInvoiceToXero(orgId, invoiceId) — idempotent, returns XeroPushResult (never throws)
• mapInvoiceToXero(invoice, currency, accountCode) — pure function, easy to unit-test
• getValidAccessToken(orgId) — refreshes the token if it's within 60s of expiry

The hook into the user flow is in lib/invoice-service.ts on the line where recordPaymentEntry flips status to PAID. Same hook in bulkMarkPaid.

To build a custom push pipeline, call pushInvoiceToXero directly from your own action / cron / webhook handler. Or pull invoices via the REST API and push them through your own pipeline.