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 Configuration → Company → 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/loginto 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.
/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.
Step 3: Run sync
Trigger sync from Configuration → Company → Integrations → Bill.com → Sync or viaPOST /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:
Cutoff date. Bills, vendor payments, and vendor credits respect the integration’s cutoff so historical migrations can skip older Bill.com dates. Other categories pull current data without a date filter.
What syncs
The integration moves data in three directions, each with different scope:How multicurrency bills are converted
Currency and exchange rate are resolved separately on an imported record, and the three record types resolve the rate three different ways. The table below summarizes where each value comes from.
DualEntry takes the currency of an imported Bill.com record from the vendor, not from the record itself. Each Bill.com vendor carries a
bill_currency value, and DualEntry applies that currency to every bill, payment, and credit imported for that vendor. When the vendor has no bill_currency, or carries a code DualEntry does not recognize, the record imports as USD.
For a bill, the rate comes from Bill.com rather than from DualEntry’s rate table. DualEntry reads the exchange_rate that Bill.com sends and inverts it to match DualEntry’s base-currency convention, so the rate stored on the imported bill is the reciprocal of the rate Bill.com applied. No rate date is involved: the rate that arrives with the bill is the rate that posts. When Bill.com sends no rate at all, DualEntry uses 1.0 and the bill imports at parity.
Vendor payments do not invert the rate. DualEntry stores the exchange_rate that Bill.com sends on a payment exactly as received, while the same field on a bill is reciprocated. A bill and the payment that settles it therefore carry rates that are reciprocals of each other, so check both figures before relying on either one in a foreign-currency AP reconciliation.
Vendor credits follow a third path, resolving the rate from DualEntry’s own exchange rate records for the vendor currency and company currency pair. That lookup does not filter by date, so it resolves to the oldest stored rate for the pair rather than the rate in effect on the transaction date. Adding a newer rate does not change what a credit converts at. When no rate record exists for the pair at all, the credit posts at 1.0, the same silent parity a bill gets when Bill.com sends no rate. The same undated lookup runs while importing a vendor payment that applies a credit. Expect a foreign-currency vendor credit to translate at a different rate than the bill it offsets, and reconcile the two amounts by hand.
Current limitations
A few aspects of the integration are worth knowing before you rely on it:- Foreign-currency rates come from Bill.com. DualEntry does not revalue an imported bill against its own rate table, so the rate Bill.com sends on the bill is the rate that posts. See How multicurrency bills are converted.
- 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 Configuration → Company → Integrations → Bill.com. The most common causes:
For Bill.com platform outages, see Bill.com status. For Bill.com API changes that may affect imports, see the Bill.com developer changelog.