---
updatedAt: 2026-04-21T17:39:49.000Z
agentTools:
  projectIndex: https://developer.bill.com/v2/llms.txt
---

# Bulk create bills

Bulk create bill objects. The maximum number of objects you can set in a bulk operation is 100.

### What is a bill?
A bill represents an amount owed for goods and services provided by a vendor.

You can create a bill with `/v2/Crud/Create/Bill.json`. In the bill, add bill line items to record details about individual goods or services. In addition, you can associate line items to accounts tracking objects, such as item or chart of accounts.

Other bill features: 
* When a bill requires approval, you can add bill approvers with the BILL web app.
* You can reduce the total bill amount with a bill credit (with the BILL web app) or vendor credit (`/VendorCredit.json`). Total bill amount, bill credits, vendor credits, and any remaining bill amount paid or recorded is available with `/v2/Crud/Read/SentPay.json`.
* The `exchangeRate` is a required additional field for creating a bill for an international vendor (a vendor outside the US). In addition, each bill line item `amount` is in the foreign currency. Retrieve the current exchange rate with `/v2/GetDynamicExchangeRateQuote.json`.

**Note**: You must set `exchangeRate` when creating a bill for an international vendor even if the BILL foreign exchange rate changes at the time of bill payment.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "AP | Vendor transactions",
    "version": "2.0",
    "description": "BILL is a cloud-based cash flow management system for an organization's Accounts Payable (AP) and Accounts Receivable (AR) automation.\n * **AP**: Automate workflows to pay vendors bills at scale for the goods and services they provide. Pay vendors with a wide range of payment methods. Generate vendor credits, bill credits, and payment disbursement reports.\n * **AR**: Automate workflows to get paid by customers at scale for the goods and services you provide. Generate and send invoices on a schedule, generate customer and invoice credits, and seamlessly charge authorized customers.\n * **Organization**: Manage your bank accounts (for sending and receiving payments), users (with user roles), and sync with your choice of accounting software.\n\nIntegrate with the BILL API to send and receive payments for your business. See [Support Center](https://help.bill.com/hc/en-us) for resources about using the BILL web app.",
    "contact": {
      "email": "developerprogram@hq.bill.com"
    }
  },
  "servers": [
    {
      "url": "https://api-stage.bill.com/api/v2",
      "description": "Sandbox base URL"
    }
  ],
  "x-readme": {
    "samples-languages": [
      "curl",
      "java",
      "javascript",
      "python",
      "ruby"
    ]
  },
  "paths": {
    "/Bulk/Crud/Create/Bill.json": {
      "post": {
        "summary": "Bulk create bills",
        "operationId": "ap-vendortransactions-bulkcreatebill",
        "description": "Bulk create bill objects. The maximum number of objects you can set in a bulk operation is 100.\n\n### What is a bill?\nA bill represents an amount owed for goods and services provided by a vendor.\n\nYou can create a bill with `/v2/Crud/Create/Bill.json`. In the bill, add bill line items to record details about individual goods or services. In addition, you can associate line items to accounts tracking objects, such as item or chart of accounts.\n\nOther bill features: \n* When a bill requires approval, you can add bill approvers with the BILL web app.\n* You can reduce the total bill amount with a bill credit (with the BILL web app) or vendor credit (`/VendorCredit.json`). Total bill amount, bill credits, vendor credits, and any remaining bill amount paid or recorded is available with `/v2/Crud/Read/SentPay.json`.\n* The `exchangeRate` is a required additional field for creating a bill for an international vendor (a vendor outside the US). In addition, each bill line item `amount` is in the foreign currency. Retrieve the current exchange rate with `/v2/GetDynamicExchangeRateQuote.json`.\n\n**Note**: You must set `exchangeRate` when creating a bill for an international vendor even if the BILL foreign exchange rate changes at the time of bill payment.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkCreateBillResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "devKey",
                  "sessionId",
                  "data"
                ],
                "properties": {
                  "devKey": {
                    "type": "string",
                    "description": "Developer key generated with your BILL developer account"
                  },
                  "sessionId": {
                    "type": "string",
                    "description": "API session ID generated with [`/v2/Login.json`](https://developer.bill.com/reference/auth-login)"
                  },
                  "data": {
                    "$ref": "#/components/schemas/BulkCreateBillRequest"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Bills"
        ]
      },
      "parameters": []
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error_code": {
            "type": "string",
            "description": "Error code (only when `response_status` is `1`)"
          },
          "error_message": {
            "type": "string",
            "description": "Error message (only when `response_status` is `1`)"
          }
        }
      },
      "CreateBillRequest": {
        "type": "object",
        "required": [
          "obj"
        ],
        "properties": {
          "obj": {
            "type": "object",
            "required": [
              "entity",
              "vendorId",
              "invoiceNumber",
              "invoiceDate",
              "dueDate",
              "billLineItems"
            ],
            "properties": {
              "entity": {
                "type": "string",
                "description": "Object type. Set as `Bill`.",
                "default": "Bill"
              },
              "isActive": {
                "type": "string",
                "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive\n* `5`: Draft\n* `6`: Draft deleted"
              },
              "vendorId": {
                "type": "string",
                "description": "BILL-generated ID of the vendor. The value begins with `009`."
              },
              "invoiceNumber": {
                "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 bill is sent. This value is in the YYYY-MM-DD format."
              },
              "dueDate": {
                "type": "string",
                "description": "Date when the bill is due. The value is in the YYYY-MM-DD format."
              },
              "glPostingDate": {
                "type": "string",
                "description": "Bill date in your organization’s general ledger in your choice of accounting software. The value is in the YYYY-MM-DD format."
              },
              "exchangeRate": {
                "type": "number",
                "description": "Exchange rate for creating a bill for an international vendor. This value is required during bill creation and payments to international vendors."
              },
              "description": {
                "type": "string",
                "description": "Bill description"
              },
              "poNumber": {
                "type": "string",
                "description": "Purchase order number associated with the bill"
              },
              "payFromBankAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the bank account used to pay the bill. This field is available only for select BILL partners.",
                "deprecated": true
              },
              "payFromChartOfAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the chart of accounts used to pay the bill. This is an accounts tracking object. This field is available only for select BILL partners."
              },
              "paymentTermId": {
                "type": "string",
                "description": "BILL-generated payment term ID for the bill. This is an accounts tracking object."
              },
              "hasAutoPay": {
                "type": "boolean",
                "description": "Set as `true` if the bill is paid with Autopay"
              },
              "eBillCreated": {
                "type": "boolean",
                "description": "Set as `true` if an eBill is created"
              },
              "invoiceProductId": {
                "type": "string",
                "description": "BILL-generated ID of the invoice line item associated with the bill"
              },
              "chartOfAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the chart of accounts associated with the bill. This is an accounts tracking object."
              },
              "departmentId": {
                "type": "string",
                "description": "BILL-generated ID of the department associated with the bill. This is an accounts tracking object."
              },
              "locationId": {
                "type": "string",
                "description": "BILL-generated ID of the location associated with the bill. This is an accounts tracking object."
              },
              "actgClassId": {
                "type": "string",
                "description": "BILL-generated ID of the accounting class associated with the bill. This is an accounts tracking object.\n\n`actgClassId` must be set at the `billLineItems` level."
              },
              "source": {
                "type": "string",
                "description": "Bill creation source.\n* `0`: Default\n* `1`: Pay a vendor\n* `2`: Simple basic\n* `3`: Paymentus"
              },
              "useBillDesc": {
                "type": "boolean",
                "description": "Set as `true` if the bill description is used for expense description"
              },
              "defaultInvoiceNumber": {
                "type": "boolean",
                "description": "Set as `true` if the invoice number defaults to the invoice date"
              },
              "isAutoSaved": {
                "type": "boolean",
                "description": "Set as `true` if the bill is auto-saved"
              },
              "billTemplateId": {
                "type": "string",
                "description": "BILL-generated ID of the bill template"
              },
              "billLineItems": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "entity",
                    "amount"
                  ],
                  "properties": {
                    "entity": {
                      "type": "string",
                      "description": "Object type. Set as `BillLineItem`.",
                      "default": "BillLineItem"
                    },
                    "amount": {
                      "type": "number",
                      "description": "Bill line item amount"
                    },
                    "chartOfAccountId": {
                      "type": "string",
                      "description": "BILL-generated ID of the chart of accounts associated with the bill line item. This is an accounts tracking object."
                    },
                    "departmentId": {
                      "type": "string",
                      "description": "BILL-generated ID of the department associated with the bill line item. This is an accounts tracking object."
                    },
                    "locationId": {
                      "type": "string",
                      "description": "BILL-generated ID of the location associated with the bill line item. This is an accounts tracking object."
                    },
                    "jobId": {
                      "type": "string",
                      "description": "BILL-generated ID of the job associated with the bill line item. This is an accounts tracking object."
                    },
                    "customerId": {
                      "type": "string",
                      "description": "BILL-generated ID of the customer associated with the bill line item. This is an accounts tracking object."
                    },
                    "jobBillable": {
                      "type": "boolean",
                      "description": "Set as `true` if the job associated with the bill line item is billable"
                    },
                    "description": {
                      "type": "string",
                      "description": "Bill line item description"
                    },
                    "lineType": {
                      "type": "string",
                      "description": "Bill line item type.\n* `1`: Expense (if the price is not associated with an item)\n* `2`: Item"
                    },
                    "itemId": {
                      "type": "string",
                      "description": "BILL-generated ID of the item associated with the bill line item. This is an accounts tracking object."
                    },
                    "quantity": {
                      "type": "number",
                      "description": "Bill line item quantity"
                    },
                    "unitPrice": {
                      "type": "number",
                      "description": "Bill line item unit price"
                    },
                    "employeeId": {
                      "type": "string",
                      "description": "BILL-generated ID of the employee associated with the bill line item. This is an accounts tracking object."
                    },
                    "actgClassId": {
                      "type": "string",
                      "description": "BILL-generated ID of the accounting class associated with the bill line item. This is an accounts tracking object."
                    },
                    "purchaseOrderBillLinkId": {
                      "type": "string",
                      "description": "BILL-generated ID of the purchase order bill link associated with the bill line item"
                    },
                    "unitOfMeasureId": {
                      "type": "string",
                      "description": "BILL-generated ID of the unit of measure associated with the bill line item"
                    },
                    "lineOrder": {
                      "type": "number",
                      "description": "Bill line item order"
                    },
                    "useSmartApprovers": {
                      "type": "boolean",
                      "description": "Set as `true` if the previous bill approvers and default approvers are automatically added to the bill"
                    }
                  }
                }
              }
            }
          },
          "allowDuplicateInvNum": {
            "type": "boolean",
            "description": "Set as `true` if `invoiceNumber` can be a duplicate value.\n\n**Note**: Duplicate invoice numbers can cause issues when syncing with your choice of accounting software."
          }
        }
      },
      "CreateBillResponse": {
        "type": "object",
        "properties": {
          "response_status": {
            "type": "integer",
            "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_message": {
            "type": "string",
            "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_data": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            ],
            "properties": {
              "entity": {
                "type": "string",
                "description": "Object type. Set as `Bill`."
              },
              "id": {
                "type": "string",
                "description": "BILL-generated ID of the bill. The value begins with `00n`."
              },
              "isActive": {
                "type": "string",
                "description": "Object visibility status. Inactive objects are hidden by default in the BILL web app.\n* `1`: Active\n* `2`: Inactive\n* `5`: Draft\n* `6`: Draft deleted"
              },
              "vendorId": {
                "type": "string",
                "description": "BILL-generated ID of the vendor. The value begins with `009`."
              },
              "invoiceNumber": {
                "type": "string",
                "description": "User-generated invoice number. This value can be your chosen number scheme or bill due date."
              },
              "approvalStatus": {
                "type": "string",
                "description": "Bill approval status.\n* `0`: Unassigned\n* `1`: Assigned\n* `3`: Approved\n* `4`: Approving\n* `5`: Denied"
              },
              "invoiceDate": {
                "type": "string",
                "description": "Date when the bill is sent. This value is in the YYYY-MM-DD format."
              },
              "dueDate": {
                "type": "string",
                "description": "Date when the bill is due. The value is in the YYYY-MM-DD format."
              },
              "glPostingDate": {
                "type": "string",
                "description": "Bill date in your organization’s general ledger in your choice of accounting software. The value is in the YYYY-MM-DD format."
              },
              "amount": {
                "type": "number",
                "description": "Bill total amount"
              },
              "localAmount": {
                "type": "number",
                "description": "Bill total amount in local currency"
              },
              "exchangeRate": {
                "type": "number",
                "description": "Exchange rate for creating a bill for an international vendor. This value is required during bill creation and payments to international vendors."
              },
              "scheduledAmount": {
                "type": "number",
                "description": "Bill scheduled amount"
              },
              "paidAmount": {
                "type": "number",
                "description": "Bill paid amount"
              },
              "dueAmount": {
                "type": "number",
                "description": "Bill due amount"
              },
              "paymentStatus": {
                "type": "string",
                "description": "Payment status.\n* `0`: Paid in full\n* `1`: Open\n* `2`: Partial payment\n* `4`: Scheduled\n* `6`: In process"
              },
              "description": {
                "type": "string",
                "description": "Bill description"
              },
              "poNumber": {
                "type": "string",
                "description": "Purchase order number associated with the bill"
              },
              "createdTime": {
                "type": "string",
                "description": "Created date and time"
              },
              "updatedTime": {
                "type": "string",
                "description": "Updated date and time"
              },
              "payFromBankAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the bank account used to pay the bill. This field is available only for select BILL partners.",
                "deprecated": true
              },
              "payFromChartOfAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the chart of accounts used to pay the bill. This is an accounts tracking object. This field is available only for select BILL partners."
              },
              "paymentTermId": {
                "type": "string",
                "description": "BILL-generated payment term ID for the bill. This is an accounts tracking object."
              },
              "hasAutoPay": {
                "type": "boolean",
                "description": "Set as `true` if the bill is paid with Autopay"
              },
              "eBillCreated": {
                "type": "boolean",
                "description": "Set as `true` if an eBill is created"
              },
              "invoiceProductId": {
                "type": "string",
                "description": "BILL-generated ID of the invoice line item associated with the bill"
              },
              "chartOfAccountId": {
                "type": "string",
                "description": "BILL-generated ID of the chart of accounts associated with the bill. This is an accounts tracking object."
              },
              "departmentId": {
                "type": "string",
                "description": "BILL-generated ID of the department associated with the bill. This is an accounts tracking object."
              },
              "locationId": {
                "type": "string",
                "description": "BILL-generated ID of the location associated with the bill. This is an accounts tracking object."
              },
              "actgClassId": {
                "type": "string",
                "description": "BILL-generated ID of the accounting class associated with the bill. This is an accounts tracking object.\n\n`actgClassId` must be set at the `billLineItems` level."
              },
              "source": {
                "type": "string",
                "description": "Bill creation source.\n* `0`: Default\n* `1`: Pay a vendor\n* `2`: Simple basic\n* `3`: Paymentus"
              },
              "numApprPolicyEx": {
                "type": "string",
                "description": "Number of approval policy violations on the bill"
              },
              "useBillDesc": {
                "type": "boolean",
                "description": "Set as `true` if the bill description is used for expense description"
              },
              "defaultInvoiceNumber": {
                "type": "boolean",
                "description": "Set as `true` if the invoice number defaults to the invoice date"
              },
              "isAutoSaved": {
                "type": "boolean",
                "description": "Set as `true` if the bill is auto-saved"
              },
              "billTemplateId": {
                "type": "string",
                "description": "BILL-generated ID of the bill template"
              },
              "hasLinkedPurchaseOrders": {
                "type": "boolean",
                "description": "Set as `true` if the bill has linked purchase orders"
              },
              "multipleBillLineItems": {
                "type": "boolean",
                "description": "Set as `true` if the bill has multiple bill line items"
              },
              "item": {
                "type": "object",
                "properties": {
                  "count": {
                    "type": "integer",
                    "description": "Total bill line items count"
                  },
                  "totalAmount": {
                    "type": "number",
                    "description": "Total bill line items amount"
                  }
                }
              },
              "expense": {
                "type": "object",
                "properties": {
                  "count": {
                    "type": "integer",
                    "description": "Total bill line items count for expenses (if the price is not associated with items)"
                  },
                  "totalAmount": {
                    "type": "number",
                    "description": "Total bill line items amount for expenses (if the price is not associated with items)"
                  },
                  "chartOfAccountGroup": {
                    "type": "array",
                    "maxItems": 1,
                    "description": "Chart of accounts group information. This information is available when more than one line item is associated with the same chart of accounts.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "chartOfAccountId": {
                          "type": "string",
                          "description": "BILL-generated ID of the chart of accounts group. This is an accounts tracking object."
                        },
                        "count": {
                          "type": "integer",
                          "description": "Total bill line items count"
                        },
                        "totalAmount": {
                          "type": "number",
                          "description": "Total bill line items amount"
                        }
                      }
                    }
                  }
                }
              },
              "billLineItems": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "entity": {
                      "type": "string",
                      "description": "Object type. Set as `BillLineItem`."
                    },
                    "id": {
                      "type": "string",
                      "description": "BILL-generated ID of the bill line item. The value begins with `bli`."
                    },
                    "billId": {
                      "type": "string",
                      "description": "BILL-generated ID of the bill. The value begins with `00n`."
                    },
                    "amount": {
                      "type": "number",
                      "description": "Bill line item amount"
                    },
                    "chartOfAccountId": {
                      "type": "string",
                      "description": "BILL-generated ID of the chart of accounts associated with the bill line item. This is an accounts tracking object."
                    },
                    "departmentId": {
                      "type": "string",
                      "description": "BILL-generated ID of the department associated with the bill line item. This is an accounts tracking object."
                    },
                    "locationId": {
                      "type": "string",
                      "description": "BILL-generated ID of the location associated with the bill line item. This is an accounts tracking object."
                    },
                    "jobId": {
                      "type": "string",
                      "description": "BILL-generated ID of the job associated with the bill line item. This is an accounts tracking object."
                    },
                    "customerId": {
                      "type": "string",
                      "description": "BILL-generated ID of the customer associated with the bill line item. This is an accounts tracking object."
                    },
                    "jobBillable": {
                      "type": "boolean",
                      "description": "Set as `true` if the job associated with the bill line item is billable"
                    },
                    "description": {
                      "type": "string",
                      "description": "Bill line item description"
                    },
                    "createdTime": {
                      "type": "string",
                      "description": "Created date and time"
                    },
                    "updatedTime": {
                      "type": "string",
                      "description": "Updated date and time"
                    },
                    "lineType": {
                      "type": "string",
                      "description": "Bill line item type.\n* `1`: Expense (if the price is not associated with an item)\n* `2`: Item"
                    },
                    "itemId": {
                      "type": "string",
                      "description": "BILL-generated ID of the item associated with the bill line item. This is an accounts tracking object."
                    },
                    "quantity": {
                      "type": "number",
                      "description": "Bill line item quantity"
                    },
                    "unitPrice": {
                      "type": "number",
                      "description": "Bill line item unit price"
                    },
                    "employeeId": {
                      "type": "string",
                      "description": "BILL-generated ID of the employee associated with the bill line item. This is an accounts tracking object."
                    },
                    "actgClassId": {
                      "type": "string",
                      "description": "BILL-generated ID of the accounting class associated with the bill line item. This is an accounts tracking object."
                    },
                    "purchaseOrderBillLinkId": {
                      "type": "string",
                      "description": "BILL-generated ID of the purchase order bill link associated with the bill line item"
                    },
                    "unitOfMeasureId": {
                      "type": "string",
                      "description": "BILL-generated ID of the unit of measure associated with the bill line item"
                    },
                    "lineOrder": {
                      "type": "number",
                      "description": "Bill line item order"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "BulkCreateBillRequest": {
        "type": "object",
        "required": [
          "bulk"
        ],
        "properties": {
          "bulk": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreateBillRequest"
            }
          }
        }
      },
      "BulkCreateBillResponse": {
        "type": "object",
        "properties": {
          "response_status": {
            "type": "integer",
            "description": "Response status.\n* `0`: Success response\n* `1`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_message": {
            "type": "string",
            "description": "Response status.\n* `Success`: Success response\n* `Error`: Error response. Only `error_code` and `error_message` is returned in `response_data`."
          },
          "response_data": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            ],
            "properties": {
              "bulk": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CreateBillResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}
```