# 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](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% 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/sling-cli/environment#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/sling-cli/environment#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).