Bills

A bill represents an amount owed for goods and services provided by a vendor.

In the bill, you can add bill line items to record details about individual goods or services. In addition, you can add invoice information for associating the bill with an invoice. See the /v3/bills API for more information about the complete list of bill operations.

Creating a bill

In your POST /v3/bills request, set the required fields.

FieldDescription
vendorIdBILL-generated ID of the vendor you want to pay. This value begins with 009.
dueDateBill due date. This value is in the yyyy-MM-dd format.
billLineItemsIn the billLineItems array, set amount as the bill line item amount.
invoiceNumberBill invoice number. This value can be your chosen number scheme or bill due date.
invoiceDateBill invoice sent date. This value is in the yyyy-MM-dd format.

See the /v3/bills API for more information about the other bill fields you can set.

Sample request

In this cURL example, a bill of $228.99 is created for the vendor (vendorId). An invoice number and invoice sent date is added to the bill.

curl --request POST \
--url 'https://gateway.sandbox.bill.com/connect/v3/bills' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}' \
--data '{
  "vendorId": "{vendor_id}",
  "dueDate": "2024-12-31",  
  "billLineItems": [{
    "amount": 149.00,
    "description": "USB audio interface"
  },
  {
    "amount": 79.99,
    "description": "Drum foot pedal"
  }],
  "invoice": {
    "invoiceNumber": "202401",
    "invoiceDate": "2024-12-31"
  }
}'

Response

In the response, a BILL-generated bill id is available. This value begins with 00n. You can use this bill id for other BILL operations.

{
  "id": "{bill_id}",
  "archived": false,
  "vendorId": "{vendor_id}",
  "dueDate": "2024-12-31",
  "invoice": {
    "invoiceNumber": "202401",
    "invoiceDate": "2024-12-31"
  },
  "billLineItems": [
    {
      "id": "{billLineItem_id01}",
      "amount": 149,
      "description": "USB audio interface"
    },
    {
      "id": "{billLineItem_id02}",
      "amount": 79.99,
      "description": "Drum foot pedal"
    }
  ],
  "createdTime": "2024-12-30T23:15:23.000Z",
  "updatedTime": "2024-12-30T23:15:23.000Z"
}

If the bill is created for an international vendor (not US), there are three bill amount-related fields to note.

FieldDescription
fundingAmountBill amount in USD.
exchangeRateExchange rate for the bill amount in the international currency (not USD).

The BILL exchange rate changes periodically and a different rate may apply at the time of payment.
amountBill line item amount. This value is in the local currency.

See the /v3/bills API for more information about the complete list of bill operations.