> ## 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
> Sync Bill.com with DualEntry for vendors, bills, payments, credits, funding accounts, and items, keeping the chart of accounts aligned across both systems.
Connect [Bill.com](https://www.bill.com/integrations/explore/partner/dual-entry) 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.
1. Navigate to **Configuration → Company → Integrations → Bill.com** and choose the DualEntry company that should own this connection.
2. Provide your Bill.com developer key, token name (Bill.com API username), token password, and Bill.com organization id. Optionally supply a display name.
3. 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.
4. 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 **Configuration → Company → 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 **Configuration → Company → 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. |
**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.
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. |
## 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.
| Imported record | Currency comes from | Exchange rate comes from | Rate when none is available |
| --------------- | ---------------------------- | ------------------------------------------------------ | --------------------------- |
| Bill | The vendor's `bill_currency` | The rate Bill.com sends on the bill, inverted | 1.0 |
| Vendor payment | The vendor's `bill_currency` | The rate Bill.com sends on the payment, as received | 1.0 |
| Vendor credit | The vendor's `bill_currency` | The oldest stored DualEntry rate for the currency pair | 1.0 |
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.
A vendor with no `bill_currency` imports as USD with no error and no entry in the Integration Errors log. Confirm every foreign-currency vendor in Bill.com carries the currency you expect before the first sync, because the resulting records have to be corrected one at a time.
## How a Bill.com payment covering several bills imports
A Bill.com payment that settles more than one bill imports as a single DualEntry vendor payment, not as one payment per bill. The vendor payment carries the full payment amount, and each bill on the Bill.com payment becomes its own line on that vendor payment with its own bill reference and amount. Reconcile against the vendor payment total rather than expecting a separate DualEntry record per invoice.
This shape matters when you compare DualEntry against a system that splits the same payment differently. A batch that pays six bills in Bill.com produces one DualEntry vendor payment with six lines, so a per-invoice record count across the two systems does not agree even though the amounts do. Open the vendor payment and read its lines to see the per-bill breakdown.
Two behaviors explain most discrepancies you will chase here:
* **A bill already applied elsewhere is skipped.** If a bill on the Bill.com payment is already applied to a different DualEntry vendor payment, that bill is left off the imported payment and the remaining bills still import. No error is recorded and nothing appears in the Integration Errors log, so compare the vendor payment's lines against the Bill.com payment to spot a missing bill.
* **A payment dated before its earliest bill is rejected.** DualEntry does not import a Bill.com payment whose payment date precedes the date of the earliest bill it settles. Correct the date in Bill.com and run the sync again.
For how these payments behave once they are in your ledger, including how to apply and review them, see [vendor payments](../../core-financials/accounts-payable/vendor-payments).
## 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](#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:
| 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. |
For Bill.com platform outages, see [Bill.com status](https://www.billcomstatus.com/). For Bill.com API changes that may affect imports, see the [Bill.com developer changelog](https://developer.bill.com/changelog).
## 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](../../core-financials/accounts-payable/index). To compare other connectors, return to [Integrations](../index).