The webhook notification payloads for all bill-related events now include all the response fields for the bill. For example, if you have subscribed to the bill.updated event, the payload for each related notification will now include all the response fields for the each updated bill.

See Bill notification payloads for more information.

We have updated the webhooks events catalog to include the payment.failed event. When your Create a payment (with POST /v3/payments) or Create a bulk payment (with POST /v3/payments/bulk) request fails, BILL sends you a notification with information to identify your payment request and with error messages to help you debug.

You can now set up subscriptions to receive notifications for the new event.

See Payment notification payloads for more information.

BILL is introducing UUIDs in the Spend & Expense API. Each ID value that uniquely identifies an entity in Spend & Expense (such as a budget, transaction, or user) now follows the UUID4 format.

UUID v4 (or UUID4) is a randomly-generated 128-bit identifier and is highly secure. The introduction of UUIDs in the Spend & Expense API is another measure taken by BILL for further improving its security standards.

Spend & Expense webhook notifications

When BILL sends notifications for the spend.transactions.updated event, each ID in the notification payload is a UUID value. For example, uuid is the UUID of the transaction, and userUuid is the UUID of the user that created the transaction.

See Spend & Expense transaction notification payloads for more information.

❗️

IMPORTANT

While the spend.transactions.updated notification payload includes only uuid values and no id values, the Spend & Expense API responses continue to present both uuid and id values.

In the future, the Spend & Expense id values will deprecated. We will share more information when we have a timeline for this deprecation.

GET operations

Let's use the example of budgets to understand the impact of introducing UUIDs on the Spend & Expense GET operations.

When you get details about a budget with GET /v3/spend/budgets/{budgetId}, you currently set the budget id in your API request. Moving forward, you can set the budget uuid as another method for getting details about a budget.

GET response fields

For each existing Spend & Expense API object, BILL has generated a uuid value for each id value. In the GET /v3/spend/budgets/{budgetId} response example, both the uuid and id values are available to uniquely identify the budget.

Similarly, for fields with an id suffix, we now have the same field with the uuid suffix to present the UUID value. For example, for the parentBudgetId field in the API response for a budget, we now have a additional parentBudgetUuid field to present the UUID of the parent budget.

{
    "id": "QnVkZ2V0OjUyOTg2MQ==",
    "uuid": "bgt_mur9ttm5tt0m97tjj287s744t4",   // NEW UUID VALUE
    "name": "Happy Music Supplies monthly spending budget",
    "retired": false,
    "startDate": "2025-12-15",
    "recurringInterval": "MONTHLY",
    "timezone": "US/Eastern",
    "autoAddUsers": false,
    "receiptRequired": true,
    "carryOver": false,
    "budgetGroup": false,
    "parentBudgetId": "{parent_budget_id}",
    "parentBudgetUuid": "{parent_budget_uuid}",   // NEW UUID VALUE
    "shareFunds": "SHARE_MANUALLY",
    "recurringLimit": 200.00,
    "limitlessOverspend": false,
    "currentPeriod": {
        "startDate": "2025-12-01",
        "endDate": "2026-01-01",
        "limit": 200.00,
        "overspendBuffer": 0.00,
        "assigned": 0.00,
        "spent": {
            "cleared": 0.00,
            "pending": 0.00,
            "total": 0.00
        }
    },
    "default": false
}

POST, PATCH, PUT, and DELETE operations

Currently, you cannot use UUID values in the Spend & Expense POST, PATCH, PUT or DELETE operations. This feature will be available in the future. We will share more information when this feature is available.

In the payments API response, we have introduced two new fields in the rppsDisbursement object.

FieldDescription
traceNumberPayment trace number. This value is used to uniquely identify a payment in a batch.
batchNumberPayment batch number

In addition, we have introduced a new disbursementStatus field in the response to provide the payment disbursement status at each stage of the payment.

See POST /v3/payments in the API reference for more information.

We have added new API endpoints for general ledger classification bulk operations.

Chart of accounts

OperationAPI endpoint
Create multiple chart of accountsPOST /v3/classifications/chart-of-accounts/bulk
Update multiple chart of accountsPATCH /v3/classifications/chart-of-accounts/bulk
Archive multiple chart of accountsPOST /v3/classifications/chart-of-accounts/bulk/archive
Restore multiple chart of accountsPOST /v3/classifications/chart-of-accounts/bulk/restore

Items

OperationAPI endpoint
Create multiple itemsPOST /v3/classifications/items/bulk
Update multiple itemsPATCH /v3/classifications/items/bulk
Archive multiple itemsPOST /v3/classifications/items/bulk/archive
Restore multiple itemsPOST /v3/classifications/items/bulk/restore

When you list bills (GET /v3/bills) and invoices (GET /v3/invoices), you can now filter and sort with additional fields.

Filtering bills and invoices

You can now filter bills and invoices with additional fields.

Fields you can filter withAvailable operators
payFromChartOfAccountId (Bills)eq (Equal)
ne (Not equal)
in (In)
payToChartOfAccountId (Invoices)eq (Equal)
ne (Not equal)
in (In)
classifications.chartOfAccountId (Bills)eq (Equal)
ne (Not equal)
in (In)
classifications.accountingClassIdeq (Equal)
ne (Not equal)
in (In)
classifications.departmentIdeq (Equal)
ne (Not equal)
in (In)
classifications.locationIdeq (Equal)
ne (Not equal)
in (In)
classifications.itemIdeq (Equal)
ne (Not equal)
in (In)

See Filterable fields for the complete list of fields you can filter with.

Sorting bills and invoices

You can now sort bills and invoices with the archived field. See Sortable fields for the complete list of fields you can sort with.

We have introduced a set of API endpoints for new bank account user operations. You can now nominate and archive bank account users.

When you nominate a bank account user, BILL sends the user an email asking them to sign in to the BILL web app and complete identity verification. After the verification is successful, the bank account user can pay with the specified bank account.

When you archive a bank account user, the user loses the ability to pay with the specified bank account.

OperationAPI endpoint
Nominate a bank account userPOST v3/funding-accounts/banks/users/nominate
Archive a bank account userPOST v3/funding-accounts/banks/users/{bankAccountUserId}/archive

We have added new API endpoints for general ledger classification bulk operations.

Departments

OperationAPI endpoint
Create multiple departmentsPOST /v3/classifications/departments/bulk
Update multiple departmentsPATCH /v3/classifications/departments/bulk
Archive multiple departmentsPOST /v3/classifications/departments/bulk/archive
Restore multiple departmentsPOST /v3/classifications/departments/bulk/restore

Jobs

OperationAPI endpoint
Create multiple jobsPOST /v3/classifications/jobs/bulk
Update multiple jobsPATCH /v3/classifications/jobs/bulk
Archive multiple jobsPOST /v3/classifications/jobs/bulk/archive
Restore multiple jobsPOST /v3/classifications/jobs/bulk/restore

Locations

OperationAPI endpoint
Create multiple locationsPOST /v3/classifications/locations/bulk
Update multiple locationsPATCH /v3/classifications/locations/bulk
Archive multiple locationsPOST /v3/classifications/locations/bulk/archive
Restore multiple locationsPOST /v3/classifications/locations/bulk/restore

We have added new API endpoints for general ledger classification bulk operations.

Accounting classes

OperationAPI endpoint
Create multiple accounting classesPOST /v3/classifications/accounting-classes/bulk
Update multiple accounting classesPATCH /v3/classifications/accounting-classes/bulk
Archive multiple accounting classesPOST /v3/classifications/accounting-classes/bulk/archive
Restore multiple accounting classesPOST /v3/classifications/accounting-classes/bulk/restore

Employees

OperationAPI endpoint
Create multiple employeesPOST /v3/classifications/employees/bulk
Update multiple employeesPATCH /v3/classifications/employees/bulk
Archive multiple employeesPOST /v3/classifications/employees/bulk/archive
Restore multiple employeesPOST /v3/classifications/employees/bulk/restore