--- 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. # Create a bill Create a new bill. See [Bills](https://developer.bill.com/docs/ap-bills) in the Guides section for more information, sample requests, and responses. # 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": { "post": { "tags": [ "bills" ], "summary": "Create a bill", "description": "Create a new bill.\n\nSee [Bills](https://developer.bill.com/docs/ap-bills) in the Guides section for more information, sample requests, and responses.", "operationId": "createBill", "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}}" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillCreateRequestDto" } } }, "required": true }, "responses": { "201": { "description": "Create a bill response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillResponseDto" } } } }, "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": { "ApproverDto": { "required": [ "userId" ], "type": "object", "properties": { "userId": { "type": "string", "description": "BILL-generated ID of the individual user or approval group.\n* **Individual user**: The value begins with `006`.\n* **Approval group**: The value begins with `agp`." }, "status": { "allOf": [ { "$ref": "#/components/schemas/ApproverStatusDto" }, { "description": "Bill approver status." } ] }, "approverOrder": { "type": "number", "description": "Bill approval order." }, "statusChangedTime": { "type": "string", "description": "Status change date and time", "format": "date-time" } }, "description": "Approver DTO." }, "ApproverStatusDto": { "type": "string", "description": "Approver status DTO.", "enum": [ "WAITING", "VIEWED", "REROUTED", "DENIED", "APPROVED", "UPCOMING", "STALE", "UNDEFINED" ] }, "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." }, "BillCreateLineItemDto": { "type": "object", "properties": { "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": { "maxLength": 4000, "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." }, "BillCreateRequestDto": { "required": [ "billLineItems", "dueDate", "invoice", "vendorId" ], "type": "object", "properties": { "vendorId": { "minLength": 1, "type": "string", "description": "BILL-generated ID of the vendor. The value begins with `009`." }, "description": { "maxLength": 4000, "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" }, "billLineItems": { "minItems": 1, "type": "array", "description": "Bill line items information", "items": { "$ref": "#/components/schemas/BillCreateLineItemDto" } }, "invoice": { "allOf": [ { "$ref": "#/components/schemas/Invoice" }, { "description": "Invoice information" } ] }, "payFromChartOfAccountId": { "type": "string", "description": "BILL-generated ID of the chart of accounts for the bill payment. The value begins with `0ca`." }, "classifications": { "allOf": [ { "$ref": "#/components/schemas/BillClassificationsDto" }, { "description": "General ledger classifications information for the bill" } ] }, "vendorCredits": { "type": "array", "description": "Vendor credits applied to the bill", "items": { "$ref": "#/components/schemas/BillVendorCreditRequestItemDto" } }, "purchaseOrderNumber": { "type": "string", "description": "Purchase order number linked with the bill" }, "billApprovals": { "type": "boolean", "description": "Set as `true` for BILL to add approvals information in the response.\n\nWhen you have approval policies set up for bills and a bill matches a policy, you see an additional `approvers` array of objects in the response. The array shows the list of individual users and/or user groups assigned as bill approvers. In addition, the array provides information about the status of the bill in the current approval flow.\n\n**Note**: When you set `billApprovals` as `true`, you must set the field as `true` if you want to update the bill (`PATCH /v3/bills/{billId}`) or replace the bill (`PUT /v3/bills/{billId}`)." }, "allowDuplicateInvoiceNumber": { "type": "boolean", "description": "Set as `false` to reject the request when the bill's `invoice.invoiceNumber` duplicates an existing invoice number for the vendor. Defaults to `true`, which allows duplicate invoice numbers." } }, "description": "Create a bill", "example": { "vendorId": "{{vendor_id}}", "dueDate": "2026-12-31", "billLineItems": [ { "amount": 149, "description": "USB audio interface" }, { "amount": 79.99, "description": "Drum foot pedal" } ], "invoice": { "invoiceNumber": "202601", "invoiceDate": "2026-12-31" } } }, "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" ] }, "BillResponseDto": { "required": [ "archived", "id", "vendorId" ], "type": "object", "properties": { "id": { "type": "string", "description": "BILL-generated ID of the bill. The value begins with `00n`." }, "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`." }, "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" }, "approvers": { "type": "array", "description": "Bill approvers information", "items": { "$ref": "#/components/schemas/ApproverDto" } } }, "description": "Bills response." }, "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." }, "BillVendorCreditRequestItemDto": { "required": [ "amount", "id" ], "type": "object", "properties": { "id": { "minLength": 1, "type": "string", "description": "BILL-generated ID of the vendor credit applied to the bill payment. The value begins with `vcr`." }, "amount": { "minimum": 0, "type": "number", "description": "Credit amount" } }, "description": "API level DTO for apply vendor credit to bill request item." }, "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." }, "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" ] } } } } ```