New in the BILL v3 API | Bill Approvals launches Sept 29

On September 29, 2025, we will release Bill Approvals in the BILL v3 API. With this release, approvals information will automatically be added to bills created with the v3 API.

What's New

When we release bill approvals in the BILL v3 API, approvals information will automatically be added to bills created with the v3 API. If you have approval policies set up for bills using the BILL web app, you will now see an additional approvers array of objects in the v3 bills response.

For example, if your bill approval policy requires approval for all bills greater than or equal to $1000, a bill created with amount set as 1500.00 will include a list of assigned approvers in the v3 bills response.

{
  "id": "{bill_id}",
  "archived": false,
  "vendorId": "{vendor_id}",
  "amount": 1500.00,
  "dueDate": "2025-12-31",
  "invoice": {
    "invoiceNumber": "202501",
    "invoiceDate": "2025-12-31"
  },
  "billLineItems": [
    {
      "id": "{billLineItem_id01}",
      "amount": 1500.00
    }
  ],
  "paymentStatus": "UNPAID",
  "approvalStatus": "ASSIGNED",
  "createdTime": "2025-12-30T23:15:23.127+00:00",
  "updatedTime": "2025-12-30T23:15:23.127+00:00",
  "approvers": [
    {
      "userId": "{user_id}",
      "status": "WAITING",
      "approverOrder": 0,
      "statusChangedTime": "2025-12-30T23:15:23.127+00:00"
    }
  ]
}

In this sample response, the approvers array shows the current user assigned as an approver for the bill. In addition, status is set as WAITING to state that BILL is waiting for the user to perform an approval action on the bill. If there are multiple approvers assigned in an approval policy, each user is listed in an object, and approverOrder provides the order in which bill approvals are required.

Developer Actions

In your integrations,

If you create a bill with POST /v3/bills or POST /v3/bills/bulk, and
Pay the bill with POST /v3/payments or POST /v3/payments/bulk,

👉 Make sure that any bill approvals are complete before paying any bill with the API.

👉 Ensure that you handle the added approvers object in the v3 bills response in the production environment.