Xero and BILL integration

What moves between them

The main flow runs from Xero into BILL for payables. ml-connector reads supplier contacts and approved AP bills, those with Type ACCPAY, from Xero and creates the matching vendors and bills in BILL so they can be paid through the BILL network. Once BILL records a payment, that payment flows back into Xero as a payment applied against the original bill, so the Xero ledger shows the bill as paid and the amount due falls to zero. Vendor records and GL accounts are aligned across both systems so every bill line references an account that exists on each side. The cadence is webhook-driven where possible, with a scheduled poll as backup.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Xero side it refreshes the 30-minute OAuth access token before expiry and sends the Xero-tenant-id header on every call to target the right organization. On the BILL side it logs in with the developer key and org credentials to get a sessionId, and because BILL signals an expired session only as a generic auth error, it treats any 401 as re-login and retry. A Xero AP bill maps to a BILL bill, a Xero supplier contact maps to a BILL vendor, and the GL accounts referenced on bill lines are matched between the two charts of accounts first, so nothing posts to a missing account. Xero Invoice webhooks and BILL bill and payment webhooks carry only IDs, so each one triggers a follow-up GET for the full record. Both APIs lack a native idempotency key, so ml-connector uses the Xero InvoiceID and the BILL entity id to detect duplicates and avoid creating a bill or payment twice. BILL allows only three concurrent calls per org, so requests are queued rather than run in parallel, and Xero rate-limit and BILL backoff responses are retried with a full audit trail and error replay on every record.

A real-world example

A 60-person professional services firm keeps its books in Xero and pays a steady stream of subcontractor and supplier bills through BILL so approvals and ACH payments are handled in one place. Before the integration, a bookkeeper entered each bill in Xero for the records, then re-keyed the same bill into BILL to schedule payment, and later marked the Xero bill as paid by hand once BILL released the funds. The double entry caused mismatched amounts and bills that looked unpaid in Xero long after the money had gone out. With Xero and BILL connected, an approved Xero bill creates the BILL bill automatically, the BILL payment posts back against the Xero bill, and the two systems agree without manual reconciliation.

What you can do

• •Create BILL vendors and bills from Xero supplier contacts and approved ACCPAY bills so payment runs through BILL.
• •Apply BILL payments back into Xero against the matching bill so the ledger shows what was paid.
• •Match GL accounts across the Xero and BILL charts of accounts so every bill line posts to a valid account.
• •Bridge the Xero OAuth token and tenant id with the BILL session-token login, refreshing the silently expiring BILL session on a 401.
• •Queue calls within BILL's three-concurrent limit, with retries, error replay, and a full audit trail on every record.

Questions

Which direction does data move between Xero and BILL?

The main flow is Xero into BILL for payables. Supplier contacts and approved AP bills move from Xero into BILL so they can be paid through the BILL network. BILL payments then flow back into Xero and are applied against the original bill, so the Xero ledger reflects what has been paid.

How does the integration handle BILL's session-token auth and short session life?

BILL uses a session token from a developer key and org login rather than OAuth, and the session expires after about 35 minutes of inactivity. BILL reports an expired session only as a generic auth error, so ml-connector treats any 401 as a signal to log in again and retry the call. Xero is handled separately with its OAuth refresh token and tenant id header.

Can BILL receive purchase orders from Xero?

No. BILL has no purchase order object, so it cannot store a Xero purchase order directly. Purchase orders stay in Xero, and what flows into BILL is the resulting AP bill, which BILL pays through its network. The payment is then posted back into Xero against that bill.