NamaCor was designed around one idea: the accounting hand-off is the product. Everything a contractor does in the app should end as a correctly coded record in Xero, without anyone re-keying it, and payments recorded in Xero should flow back so the project view is true. This guide explains exactly what moves, in which direction, and when.
What goes from NamaCor to Xero
| Event in NamaCor | What Xero receives |
|---|---|
| Project becomes submitted or active | A Xero project (the client contact is created if needed), a tracking option named after the project, and one task per labour cost code, at the configured rate |
| Name, client, deadline or budget changes | The Xero project is updated (budget before taxes, deadline at noon Toronto time) |
| Project closed, cancelled or reopened | The Xero project is closed or reopened; the tracking option is archived or restored |
| Hour approved | A time entry in minutes on the right task and date; an owner correction updates it; a de-approval deletes it |
| Cost sent | A supplier bill, draft or approved per your setting, one line at the subtotal with the document's exact taxes, coded to the cost code's expense account and the project's tracking option, receipt attached |
| Invoice issued | A customer invoice, draft or approved per your setting, lines with revenue accounts, taxes allocated per line to match the PDF, PDF and receipts attached |
| Invoice voided | Deleted if it was still a Xero draft, voided otherwise; refused if a payment exists |
What comes back from Xero
- Status, amount paid, amount due and fully-paid date of customer invoices and supplier bills. NamaCor shows a paid or partly paid badge with the date.
- The chart of accounts, tax rates, tracking categories and Xero Projects users, read when you connect and used to fill the settings lists.
- A paid lock: once a document has any payment in Xero, NamaCor refuses to edit, delete or void it. The rule lives in the database, so no screen can bypass it. Credit notes are done in Xero.
When it happens
Every server action in NamaCor queues a job. The queue is drained right after the action and every five minutes by a scheduled run, so a bill sent from the inbox is usually in Xero within seconds. Payment status is read back on every worker pass if the last read is older than ten minutes, in full every night, on demand with the refresh button on a document, and near real time through the Xero webhook when it is registered.
Guards
- Owner confirmation: a new Xero connection is stored as pending. Until the owner confirms the organisation shown (name, short code, demo or not, Projects available), the queue hands nothing to the worker.
- Allow-list: the organisations NamaCor may write to can be restricted to a list. Anything else is refused and its token revoked on the spot.
- Organisation-bound identifiers: the Xero ids of projects, tasks, contacts and documents are tied to the organisation they were created in. Confirming another organisation resets them and re-queues project creation; nothing is ever updated across two organisations.
- Account codes verified: before sending a bill or an invoice, each account code is checked against your chart. Xero used to accept the document and drop the unknown account silently.
- Retries and log: three attempts with exponential backoff, rate limits respected, every request and response logged with its duration. Failed jobs are listed in Settings and can be re-run.
A known limit worth understanding
The Xero Projects API does not let a supplier bill be attached to a Xero project. So supplier and subcontractor costs are broken down by the tracking category (for ledger reports), while labour lives in Xero Projects. The profitability shown inside Xero Projects therefore excludes supplier bills. NamaCor's project Finances tab is the one view that combines budget, suppliers, labour, variance and hours. Xero also limits a tracking category to one hundred active options, so options of closed projects are archived automatically.