# Bill.com

BILL (formerly Bill.com) is a financial operations platform that automates accounts payable (AP), accounts receivable (AR), and spend management for small and midsize businesses. The Sling Bill.com connector extracts data from the BILL v3 API, covering bills, invoices, payments, vendors, customers, and organizational data.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](/sling-cli/cli-pro.md) or [Platform Plan](/sling-platform/platform.md).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `username` **(required)** -> Your Bill.com login email address
* `password` **(required)** -> Your Bill.com login password
* `organization_id` **(required)** -> Your Bill.com organization ID
* `dev_key` **(required)** -> Your Bill.com developer key
* `base_url` (optional) -> API base URL. Defaults to `https://gateway.prod.bill.com/connect`. Use `https://gateway.stage.bill.com/connect` for sandbox.

**Inputs (optional):**

* `anchor_date` (optional) -> Starting date for initial incremental sync (ISO 8601 format). Defaults to 1 year ago.

### Authentication

Bill.com uses session-based authentication with a developer key. You need four credentials:

1. **Sign up** at [bill.com](https://www.bill.com) (or use the [sandbox](https://login.stage.us.bill.com/neo/login) for testing)
2. **Get your Organization ID**: Go to **Settings** > **Sync & Integrations** > **Manage Developer Keys**
3. **Generate a Developer Key**: On the same page, click **Generate developer key** and accept the terms of service
4. Your **username** is your login email and **password** is your account password

{% hint style="info" %}
Bill.com sessions expire after 35 minutes of inactivity. Sling automatically re-authenticates when the session expires.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set BILLCOM type=api spec=billcom secrets='{ username: "you@company.com", password: "your_password", organization_id: "your_org_id", dev_key: "your_dev_key" }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/connections/api-connections/pages/eAdVs2BHCgdr6RS8GoJC#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export BILLCOM='{ type: api, spec: billcom, secrets: { username: "you@company.com", password: "your_password", organization_id: "your_org_id", dev_key: "your_dev_key" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/connections/api-connections/pages/eAdVs2BHCgdr6RS8GoJC#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  BILLCOM:
    type: api
    spec: billcom
    secrets:
      username: "you@company.com"
      password: "your_password"
      organization_id: "your_org_id"
      dev_key: "your_dev_key"
```

**For sandbox testing:**

```yaml
connections:
  BILLCOM:
    type: api
    spec: billcom
    secrets:
      username: "you@company.com"
      password: "your_password"
      organization_id: "your_org_id"
      dev_key: "your_dev_key"
      base_url: "https://gateway.stage.bill.com/connect"
```

## Replication

Here's an example replication configuration to sync Bill.com to a PostgreSQL database:

```yaml
source: BILLCOM
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: public.billcom_{stream_name}

streams:
  # sync all endpoints
  '*':

  # exclude recurring endpoints if not needed
  recurring_bills:
    disabled: true
  recurring_invoices:
    disabled: true
```

This replication syncs all Bill.com endpoints to PostgreSQL using full-refresh mode, except for `recurring_bills` and `recurring_invoices` which are disabled.

## Endpoints

| Endpoint              | Description                                                   | Incremental |
| --------------------- | ------------------------------------------------------------- | ----------- |
| `bills`               | AP bills with line items, payment status, and classifications | Yes         |
| `payments`            | AP payments to vendors                                        | Yes         |
| `vendors`             | AP vendors                                                    | Yes         |
| `vendor_credits`      | Vendor credit memos                                           | Yes         |
| `recurring_bills`     | Recurring bill schedules                                      | No          |
| `invoices`            | AR invoices with line items and payment info                  | Yes         |
| `customers`           | AR customers                                                  | Yes         |
| `receivable_payments` | Payments received from customers                              | Yes         |
| `credit_memos`        | AR credit memos                                               | Yes         |
| `recurring_invoices`  | Recurring invoice schedules                                   | No          |
| `chart_of_accounts`   | Chart of accounts / GL accounts                               | No          |
| `departments`         | Organization departments                                      | No          |
| `locations`           | Organization locations                                        | No          |
| `items`               | Organization items (products/services)                        | No          |
| `employees`           | Organization employees                                        | No          |
| `jobs`                | Organization jobs                                             | No          |
| `accounting_classes`  | Accounting classes for classification                         | No          |
| `users`               | Organization users                                            | No          |
| `roles`               | User roles                                                    | No          |
| `bank_accounts`       | Organization bank accounts                                    | No          |

## Incremental Sync

Endpoints marked with **Yes** in the Incremental column support incremental sync using the `updatedTime` field. On the first sync, data is fetched from the `anchor_date` (defaults to 1 year ago). Subsequent syncs only fetch records updated since the last sync.

```yaml
source: BILLCOM
target: MY_POSTGRES

defaults:
  mode: incremental
  object: public.billcom_{stream_name}

streams:
  bills:
  invoices:
  vendors:
  customers:
  payments:
```

{% hint style="warning" %}
The `recurring_bills` and `recurring_invoices` endpoints do not support sorting or filtering by `updatedTime`, so they always run in full-refresh mode regardless of the configured mode.
{% endhint %}

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/billcom.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.