Tutorial: Billing → Sales flow → Xero

Purpose

Narrative scenario for developers: what fires when money is recorded against services and how that relates to Application, Billing, Sales Invoice, and Xero code paths.

Documents involved

DocType / area	Role in this scenario
Application	Customer incorporation / service context; linked from Billing via business rules
Billing	Custom billing record; `after_insert` → `tasks.handle_billing` (see Billing flow)
Sales Invoice	ERPNext standard; Xero sync helpers may create/update SI lines
Xero (OAuth / tenant / invoice tables)	Settings and sync state — see Xero integration and Xero tenant

Sequence (simplified)

Where to read code

leekimerp/hooks.py — Billing after_insert
leekimerp/tasks.py — handle_billing, send_payment_success_email
leekimerp/api/xero.py — webhooks, invoice create/update
DocType reference — Billing, Xero Invoice, etc.

Billing flow
Xero integration
Debt management (if AR collection is in scope)

Verification checklist (engineering)

After changing Billing, tasks, or Xero code, validate on staging:

Step	Check
1	Create a Billing record that matches your test scenario; confirm `handle_billing` runs without traceback.
2	Confirm expected email side effects (templates, recipients) per `send_payment_success_email` and related helpers.
3	If Sales Invoice is created or updated, open the SI and verify tax, company, and customer links.
4	For Xero: trigger or wait for sync; verify invoice appears in correct Xero tenant with matching totals (allow for rounding rules).
5	Inspect Error Log for 15 minutes after test — no new recurring errors.

Failure scenarios to rehearse

Failure	Expected behavior
Xero API down	ERP should not corrupt SI; sync may retry or mark error — confirm actual implementation in `api/xero.py` and related DocTypes.
Duplicate webhook	Handlers should be idempotent — no duplicate ledger lines (Xero integration).
Email misconfiguration	Billing may succeed while mail fails — check Mandrill/email queue DocTypes.

Data you should capture in bug reports

Site name, Company, Billing name, Sales Invoice name (if any), Xero invoice id.
UTC timestamp of event; Stripe/Xero dashboard event ids if applicable.
Relevant Error Log traceback (redact PII).