Documentation Index
Fetch the complete documentation index at: https://docs.dualentry.com/llms.txt
Use this file to discover all available pages before exploring further.
Bill.com Integration: Setup, Mapping, and AP Sync
Connect Bill.com to a DualEntry company so vendors, bills, vendor payments, vendor credits, funding accounts, items, customers, and classification dimensions ingest into your ledger. Each Bill.com integration is scoped to a single DualEntry company; multi-entity customers create one integration per legal entity, each with its own Bill.com credentials.
This integration is two-way for chart of accounts. When you align GL accounts, DualEntry can create, update, restore, or archive chart-of-account rows in Bill.com to match your DualEntry accounts. All other data flows Bill.com → DualEntry; pushing items back to Bill.com is intentionally disabled because DualEntry items are organization-wide while Bill.com items are company-scoped.
DualEntry authenticates against Bill.com using a developer key plus a login token, exchanges them for a session, and runs an initial sync that seeds master data before scheduled syncs take over.
Prerequisites
Confirm the following before connecting:
- A Bill.com organization with the AP data you want in DualEntry, and permission to create or use a developer key plus a login token (username and password) for API access.
- The Bill.com organization id that Bill.com surfaces for API login.
- The DualEntry company that should own imported AP transactions. Each integration is scoped to one DualEntry company.
- Agreement with finance on chart-of-account alignment. DualEntry can create, update, archive, and restore rows in Bill.com’s chart of accounts to match DualEntry. Decide which system is the source of truth before first sync, especially if Bill.com currently owns the GL structure.
- Optional: if your DualEntry deployment supplies a default Bill.com developer key, you can omit it from the create payload. Otherwise, you must include it.
Step 1: Create the integration in DualEntry
Each Bill.com integration is created against a specific DualEntry company. You can do this from the UI or directly via the API.
- Navigate to Settings → Integrations → Bill.com and choose the DualEntry company that should own this connection.
- Provide your Bill.com developer key, token name (Bill.com API username), token password, and Bill.com organization id. Optionally supply a display name.
- Choose Connect. DualEntry stores the credentials, sets the integration to pending, calls Bill.com
/v3/login to authenticate, and on success enqueues the initial sync.
- If login fails, DualEntry surfaces the error from Bill.com and leaves the integration in an error state. Fix the credentials in Bill.com and retry.
For programmatic setup, the same workflow is exposed under /api/integrations/bill_com/ (create) and /api/integrations/bill_com/{integration_id}/validate/ (re-test authentication on an existing integration).
Step 2: Complete required mappings
Sync runs in a setup-incomplete mode until you finish the required mappings. Trigger-sync rejects full runs with a setup-not-completed error until every condition below is met.
- The integration is attached to a DualEntry company.
- Authentication has succeeded and the integration shows connected.
- Chart of accounts has been pulled from Bill.com and at least one DualEntry account is mapped. Among the mapped accounts you must have at least one bank or credit card, at least one expense, and at least one income account.
- Vendors have been pulled and at least one Bill.com vendor is mapped to a DualEntry vendor. The check fails when every vendor row is unmapped, and it also fails when Bill.com returns no vendors at all - create or sync at least one vendor in Bill.com first, then map it in DualEntry.
Use the integration mapping screens under Settings → Integrations → Bill.com → Mappings to link Bill.com vendors and chart-of-account rows to their DualEntry counterparts.
Step 3: Run sync
Trigger sync from Settings → Integrations → Bill.com → Sync or via POST /api/integrations/bill_com/{integration_id}/trigger-sync/. Sync proceeds in two phases.
Initial seed (first run only). After credentials succeed, DualEntry runs a pre-setup pass in this order: vendors → funding accounts → accounts → items → classifications (departments, jobs, locations, accounting classes, employees). This seeds master data and integration records before the heavier transactional pulls.
Ongoing sync plan. On every subsequent sync, DualEntry runs the full plan in a fixed order:
| Order | Pull | Notes |
|---|
| 1 | Vendors | Vendor master data. |
| 2 | Funding accounts | Bill.com bank and funding sources map to DualEntry bank-style accounts. |
| 3 | Accounts | Chart-of-account alignment, including DualEntry → Bill.com mutations described below. |
| 4 | Bills | Bill.com v3 list, with legacy v2 calls used to enrich approval status per bill. |
| 5 | Vendor credits | Subject to the integration cutoff date. |
| 6 | Vendor payments | Subject to cutoff. May call legacy v2 to resolve a chart-of-account id on the Bill.com side when needed. |
| 7 | Items | Pulled from Bill.com only; the reverse push is disabled. |
| 8 | Customers | Customer master data. |
| 9 | Classifications | Dimension sync for line-level tagging. |
Chart-of-account alignment can change Bill.com’s GL - it may create, update, archive, or restore chart-of-account rows to match DualEntry, and may create parent accounts on the Bill.com side. Run the first sync against a Bill.com sandbox organization where available, and obtain controller sign-off before pointing the integration at production Bill.com.
What syncs
The integration moves data in three directions, each with different scope:
| Direction | What syncs |
|---|
| Bill.com → DualEntry | Vendors, customers, bills (with documents where available), vendor payments, vendor credits, funding accounts, items, and classification dimensions. |
| DualEntry → Bill.com (chart of accounts) | Reconciliation may create, update, archive, or restore Bill.com chart-of-account rows, including parent accounts, to match DualEntry’s active GL. |
| DualEntry → Bill.com (items) | Disabled. DualEntry items are organization-wide while Bill.com items are company-scoped, so push is intentionally not active. |
Current limitations
A few aspects of the integration are worth knowing before you rely on it:
- One DualEntry company per Bill.com integration. Each integration row maps a single DualEntry company to a single Bill.com organization. Multi-entity customers create one integration per company, each with its own Bill.com credentials.
- Approvals stay in Bill.com. Bill approval workflows, payment scheduling, and operational AP routing remain in Bill.com. DualEntry ingests the financial result (bills, payments, credits) according to the mapping and cutoff rules.
- Items are inbound only. Bill.com items pull into DualEntry, but DualEntry items are not pushed back to Bill.com because they are organization-wide while Bill.com items are company-scoped.
- Chart-of-account alignment can mutate Bill.com. The COA reconciliation step writes back to Bill.com - the only direction in which DualEntry mutates Bill.com data. Decide which system is the source of truth for your chart of accounts before the first sync.
Troubleshoot common issues
When a record fails, it appears in the Integration Errors log under Settings → Integrations → Bill.com. The most common causes:
| Symptom | Likely cause | Resolution |
|---|
| 401 on connect or validate | Wrong developer key, token name and password, or Bill.com organization id. | Verify the credentials in Bill.com; regenerate the API token if needed; retry connect or validate. |
| ”Setup not completed” on sync | Unmapped vendors, or chart-of-account mappings missing the required types (bank or credit card, expense, income). | Complete the mappings under Settings → Integrations → Bill.com → Mappings and confirm at least one vendor is mapped. |
| Bills do not import | Invoice date is before the cutoff, the bill is not yet approved in Bill.com, or vendor / item / classification mappings are missing. | Check the integration error detail; confirm the bill date is on or after the cutoff and the referenced vendors and items exist and are mapped. |
| Vendor payment fails | Funding account is not mapped to a DualEntry bank account, or the payment references an unmapped GL account. | Map every Bill.com funding account to a DualEntry bank account; verify the chart-of-account rows used on the Bill.com payment. |
| Duplicate or unexpected chart-of-account rows on Bill.com | DualEntry’s COA alignment created new rows because no number-and-type match was found in Bill.com. | Align account numbers and types between systems before next sync; clean up duplicates in Bill.com with finance oversight. |
| Repeated 401 / 403 during long sync | Bill.com session expired and the auto-reauthentication cap was reached. | Re-run trigger-sync; if errors persist, validate the integration to refresh the session. |
Result
After credentials succeed and required mappings are complete, the linked DualEntry company stays aligned with Bill.com on vendors, bills, vendor payments, vendor credits, customers, funding accounts, items, and classification dimensions. Chart-of-account alignment will mutate Bill.com’s GL when DualEntry mappings demand it, so confirm the source of truth before going live.
To pay imported bills and view AP aging, see Accounts Payable. To compare other connectors, return to Integrations.