---
updatedAt: 2026-06-29T20:33:19.000Z
---

Fetch the complete documentation index at: https://developer.bill.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Get list of bills

Get a list of bill objects. By default, you get 20 results on one page of results. Set `max` in your request to get up to 100 results on one page.

See [Search operations with lists](https://developer.bill.com/docs/search-op-with-lists) in the Guides section for filtering, sorting, and pagination examples.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "BILL v3 API",
    "description": "BILL is a cloud-based financial operations platform for an organization's accounts payable (AP), accounts receivable (AR), and spend & expense (S&E) automation.\n\nThe BILL v3 API gives you access to the same infrastructure that powers the AP, AR, and S&E products. In addition, you can receive real-time event notifications with webhooks.\n\nThe BILL Developer Documentation is available at [developer.bill.com](https://developer.bill.com/docs/home).\n\n## Quickstart\nSign-up and generate a developer key for working with the BILL v3 API. With this key, you can build with the AP, AR, BILL network, and webhook workflows. See [Sandbox API sign up](https://developer.bill.com/docs/api-sandbox-sign-up) for more information.\n\n### Spend & Expense API\nAn API token is required for working with the Spend & Expense API. See [Authentication with Spend & Expense API token](https://developer.bill.com/docs/authentication-with-api-token) for more information.\n\n### BILL v3 API in Postman\nWith this collection, you have access to the BILL v3 API in Postman. When you save your sandbox API credentials as environment variables in Postman, you can simply refer to the variables when you are testing with the BILL v3 API. See [BILL v3 API in Postman](https://developer.bill.com/docs/bill-v3-api-in-postman) for more information.",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://gateway.stage.bill.com/connect",
      "description": "sandbox"
    }
  ],
  "paths": {
    "/v3/bills": {
      "get": {
        "tags": [
          "bills"
        ],
        "summary": "Get list of bills",
        "description": "Get a list of bill objects. By default, you get 20 results on one page of results. Set `max` in your request to get up to 100 results on one page.\n\nSee [Search operations with lists](https://developer.bill.com/docs/search-op-with-lists) in the Guides section for filtering, sorting, and pagination examples.",
        "operationId": "listBills",
        "parameters": [
          {
            "name": "sessionId",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "API session ID generated with `/v3/login`",
              "nullable": true,
              "example": "{{session_id}}"
            }
          },
          {
            "name": "devKey",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "Developer key generated with your BILL developer account",
              "nullable": true,
              "example": "{{developer_key}}"
            }
          },
          {
            "name": "max",
            "in": "query",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer",
              "description": "Maximum number of results",
              "format": "int32",
              "nullable": true,
              "example": 10
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Field name and sort order. Both simple and compound sorting is available.\n\nThe format is `sort={field_01}:{sort_order},{field_02}:{sort_order}`.\n\n**NOTE**: Sorting occurs in the specified order.",
              "nullable": true,
              "example": "createdTime:desc"
            }
          },
          {
            "name": "filters",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Field name, operator, and value. Both simple and compound filtering is available.\n\nThe format is `filters={field_01}:{op}:{value},{field_02}:{op}:{value}`.",
              "nullable": true,
              "example": "id:eq:{{bill_id}}"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Next page of results.\n\nWhen a list has multiple pages, the `nextPage` and `prevPage` values in the response enable you to navigate between the pages of results. Set `page` as the `nextPage` or `prevPage` value for navigation.",
              "nullable": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Get list of bills response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListBillResponseDto"
                }
              }
            }
          },
          "4XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          },
          "5XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BdcError": {
        "required": [
          "category",
          "code",
          "severity",
          "timestamp"
        ],
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "code": {
            "type": "string"
          },
          "severity": {
            "$ref": "#/components/schemas/Severity"
          },
          "category": {
            "$ref": "#/components/schemas/Category"
          },
          "message": {
            "type": "string"
          },
          "params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Param"
            }
          },
          "detail": {
            "type": "string"
          },
          "help": {
            "type": "string"
          }
        }
      },
      "BillApprovalStatusResponse": {
        "type": "string",
        "description": "Approval status of a bill response.",
        "enum": [
          "UNASSIGNED",
          "ASSIGNED",
          "APPROVED",
          "APPROVING",
          "DENIED",
          "UNDEFINED"
        ]
      },
      "BillClassificationsDto": {
        "type": "object",
        "properties": {
          "chartOfAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the chart of accounts. The value begins with `0ca`."
          },
          "accountingClassId": {
            "type": "string",
            "description": "BILL-generated ID of the accounting class. The value begins with `cls`."
          },
          "departmentId": {
            "type": "string",
            "description": "BILL-generated ID of the department. The value begins with `0de`."
          },
          "locationId": {
            "type": "string",
            "description": "BILL-generated ID of the location. The value begins with `loc`."
          },
          "itemId": {
            "type": "string",
            "description": "BILL-generated ID of the item. The value begins with `0ii`."
          }
        },
        "description": "DTO for Bill classifications."
      },
      "BillLineItemClassificationsDto": {
        "type": "object",
        "properties": {
          "chartOfAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the chart of accounts. The value begins with `0ca`."
          },
          "accountingClassId": {
            "type": "string",
            "description": "BILL-generated ID of the accounting class. The value begins with `cls`."
          },
          "departmentId": {
            "type": "string",
            "description": "BILL-generated ID of the department. The value begins with `0de`."
          },
          "employeeId": {
            "type": "string",
            "description": "BILL-generated ID of the employee. The value begins with `emp`."
          },
          "jobId": {
            "type": "string",
            "description": "BILL-generated ID of the job. The value begins with `job`."
          },
          "locationId": {
            "type": "string",
            "description": "BILL-generated ID of the location. The value begins with `loc`."
          },
          "itemId": {
            "type": "string",
            "description": "BILL-generated ID of the item. The value begins with `0ii`."
          },
          "customerId": {
            "type": "string",
            "description": "BILL-generated ID of the customer. The value begins with `0cu`."
          }
        },
        "description": "DTO for Bill Line Item classifications."
      },
      "BillPaymentStatusDto": {
        "type": "string",
        "description": "Payment Status of a bill.",
        "enum": [
          "PAID",
          "UNPAID",
          "PARTIALLY_PAID",
          "SCHEDULED",
          "IN_PROCESS",
          "UNDEFINED"
        ]
      },
      "BillReadWithoutApproversResponseDto": {
        "required": [
          "archived",
          "id",
          "recordStatus",
          "vendorId",
          "vendorName"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the bill. The value begins with `00n`."
          },
          "recordStatus": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BillRecordStatus"
              },
              {
                "description": "Bill record status.\n\nWhen `recordStatus` is `ACTIVE`, `archived` is set as `false`. For any other `recordStatus` value, `archived` is set as `true`."
              }
            ]
          },
          "archived": {
            "type": "boolean",
            "description": "Set as `true` if the bill is archived"
          },
          "vendorId": {
            "type": "string",
            "description": "BILL-generated ID of the vendor. The value begins with `009`."
          },
          "vendorName": {
            "type": "string",
            "description": "Vendor name"
          },
          "fundingAmount": {
            "type": "number",
            "description": "Bill total amount. This value is in USD."
          },
          "amount": {
            "type": "number",
            "description": "Bill total amount. For a bill in an international currency (not USD), this value is in the local currency."
          },
          "paidAmount": {
            "type": "number",
            "description": "Bill paid amount. This value is the sum of all cleared payments and any credit amount applied to the bill."
          },
          "dueAmount": {
            "type": "number",
            "description": "Bill due amount. The value is calculated by subtracting any applied credits (`creditAmount`), scheduled payment (`scheduledAmount`), and cleared payment from the bill `amount`."
          },
          "scheduledAmount": {
            "type": "number",
            "description": "Bill scheduled amount. The value is set as the vendor payment amount that is pending clearance."
          },
          "creditAmount": {
            "type": "number",
            "description": "Credit amount applied to the bill"
          },
          "exchangeRate": {
            "type": "number",
            "description": "Exchange rate for the bill amount in an international currency (not USD).\n\nThe BILL exchange rate changes periodically and a different rate may apply at the time of payment."
          },
          "description": {
            "type": "string",
            "description": "Bill description"
          },
          "dueDate": {
            "type": "string",
            "description": "Bill due date. The value is in the `yyyy-MM-dd` format.",
            "format": "date"
          },
          "paymentTermId": {
            "type": "string"
          },
          "invoice": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Invoice"
              },
              {
                "description": "Invoice information"
              }
            ]
          },
          "billLineItems": {
            "type": "array",
            "description": "Bill line item information",
            "items": {
              "$ref": "#/components/schemas/BillResponseLineItem"
            }
          },
          "payFromChartOfAccountId": {
            "type": "string",
            "description": "BILL-generated ID of the chart of accounts for the bill payment. The value begins with `0ca`."
          },
          "paymentStatus": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BillPaymentStatusDto"
              },
              {
                "description": "Bill payment status."
              }
            ]
          },
          "approvalStatus": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BillApprovalStatusResponse"
              },
              {
                "description": "Bill approval status."
              }
            ]
          },
          "createdBy": {
            "type": "string",
            "description": "BILL-generated ID of the user that created the bill. The value begins with `006`."
          },
          "createdTime": {
            "type": "string",
            "description": "Created date and time",
            "format": "date-time"
          },
          "updatedTime": {
            "type": "string",
            "description": "Updated date and time",
            "format": "date-time"
          },
          "classifications": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BillClassificationsDto"
              },
              {
                "description": "General ledger classifications information for the bill"
              }
            ]
          },
          "purchaseOrderNumber": {
            "type": "string",
            "description": "Purchase order number linked with the bill"
          }
        },
        "description": "Bills read response without approvers."
      },
      "BillRecordStatus": {
        "type": "string",
        "description": "Record status enum for bills.",
        "enum": [
          "ACTIVE",
          "INACTIVE",
          "DRAFT",
          "DRAFT_DELETED",
          "UNDEFINED"
        ]
      },
      "BillResponseLineItem": {
        "required": [
          "amount"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the bill line item. The value begins with `bli`."
          },
          "amount": {
            "type": "number",
            "description": "Bill line item amount. For a bill in an international currency (not USD), this value is in the local currency.\n\nIf you set `amount`, `quantity`, and `price`, BILL uses the `amount` value as the bill line item total amount."
          },
          "quantity": {
            "type": "number",
            "description": "Bill line item unit quantity"
          },
          "price": {
            "type": "number",
            "description": "Bill line item unit price. For a bill in an international currency (not USD), this value is in the local currency."
          },
          "description": {
            "type": "string",
            "description": "Bill line item description"
          },
          "classifications": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BillLineItemClassificationsDto"
              },
              {
                "description": "General ledger classifications information for the bill line item"
              }
            ]
          }
        },
        "description": "Line items that define a bill's overall amount."
      },
      "Category": {
        "type": "string",
        "enum": [
          "REQUEST",
          "APPLICATION",
          "SERVER",
          "DOWNSTREAM"
        ]
      },
      "Invoice": {
        "required": [
          "invoiceDate",
          "invoiceNumber"
        ],
        "type": "object",
        "properties": {
          "invoiceNumber": {
            "maxLength": 100,
            "minLength": 1,
            "type": "string",
            "description": "User-generated invoice number. This value can be your chosen number scheme or bill due date."
          },
          "invoiceDate": {
            "type": "string",
            "description": "Date when the invoice is sent. This value is in the `yyyy-MM-dd` format.",
            "format": "date"
          }
        },
        "description": "Invoice linked to a bill."
      },
      "ListBillResponseDto": {
        "type": "object",
        "description": "Response from a list API request with paging references.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ListResponseDto_BillReadWithoutApproversResponseDto_"
          },
          {
            "properties": {
              "count": {
                "type": "integer",
                "description": "Total number of bills matching the list request, across all pages of results.",
                "format": "int32"
              },
              "totalDueAmount": {
                "type": "number",
                "description": "Sum of the balances of all bills matching the list request, across all pages of results. This value is in the organization's base currency."
              }
            }
          }
        ]
      },
      "ListResponseDto_BillReadWithoutApproversResponseDto_": {
        "type": "object",
        "properties": {
          "nextPage": {
            "type": "string"
          },
          "prevPage": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillReadWithoutApproversResponseDto"
            }
          }
        },
        "description": "Response from a list API request with paging references."
      },
      "Param": {
        "required": [
          "name",
          "value"
        ],
        "type": "object",
        "properties": {
          "additional": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "name": {
            "minLength": 1,
            "type": "string"
          },
          "value": {
            "minLength": 1,
            "type": "string"
          }
        }
      },
      "Severity": {
        "type": "string",
        "enum": [
          "ERROR",
          "WARNING",
          "INFORMATION"
        ]
      }
    }
  }
}
```